Skip to content

Commit 8f3e6a8

Browse files
JstatiaCopilot
Jstatia
and
Copilot
committed
Add comprehensive module-level docs and README.md files for all FFI crates
Upgrade all 13 FFI crate lib.rs files with standardized module-level documentation including sections for ABI Stability, Panic Safety, Error Handling, Memory Ownership, and Thread Safety. Each crate's description is tailored to its specific functionality. Create 9 missing README.md files for FFI crates (crypto/openssl, headers, validation/core, validation/primitives, certificates, certificates/local, mst, azure_key_vault, did/x509) following the existing README pattern with exported function tables, handle types, build instructions, and links to parent library crates. Also add missing copyright headers to FFI crate lib.rs files that lacked them (validation/core, validation/primitives, certificates, mst, azure_key_vault). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 472303c commit 8f3e6a8

File tree

22 files changed

+1075
-112
lines changed

22 files changed

+1075
-112
lines changed

‎native/rust/did/x509/ffi/README.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT License. -->
2+
3+
# did_x509_ffi
4+
5+
C/C++ FFI projection for DID:x509 identifier operations.
6+
7+
## Overview
8+
9+
This crate provides C-compatible FFI exports for parsing, building, validating, and resolving
10+
DID:x509 identifiers against X.509 certificate chains. It wraps the `did_x509` crate for
11+
core functionality.
12+
13+
## Exported Functions
14+
15+
### ABI & Error Handling
16+
17+
| Function | Description |
18+
|----------|-------------|
19+
| `did_x509_abi_version` | ABI version check |
20+
| `did_x509_error_message` | Get error description string |
21+
| `did_x509_error_code` | Get error code |
22+
| `did_x509_error_free` | Free an error handle |
23+
| `did_x509_string_free` | Free a string returned by this library |
24+
25+
### Parsing
26+
27+
| Function | Description |
28+
|----------|-------------|
29+
| `did_x509_parse` | Parse a DID:x509 identifier string |
30+
| `did_x509_parsed_get_fingerprint` | Get the certificate fingerprint |
31+
| `did_x509_parsed_get_hash_algorithm` | Get the hash algorithm used |
32+
| `did_x509_parsed_get_policy_count` | Get the number of policies |
33+
| `did_x509_parsed_free` | Free a parsed DID handle |
34+
35+
### Building
36+
37+
| Function | Description |
38+
|----------|-------------|
39+
| `did_x509_build_with_eku` | Build a DID:x509 with EKU policy |
40+
| `did_x509_build_from_chain` | Build a DID:x509 from a certificate chain |
41+
42+
### Validation & Resolution
43+
44+
| Function | Description |
45+
|----------|-------------|
46+
| `did_x509_validate` | Validate a DID:x509 against a certificate chain |
47+
| `did_x509_resolve` | Resolve a DID:x509 to a public key |
48+
49+
## Handle Types
50+
51+
| Type | Description |
52+
|------|-------------|
53+
| `DidX509ParsedHandle` | Opaque parsed DID:x509 identifier |
54+
| `DidX509ErrorHandle` | Opaque error handle |
55+
56+
## C Header
57+
58+
`<cose/did/x509.h>`
59+
60+
## Parent Library
61+
62+
[`did_x509`](../../x509/) — DID:x509 implementation.
63+
64+
## Build
65+
66+
```bash
67+
cargo build --release -p did_x509_ffi
68+
```

‎native/rust/did/x509/ffi/src/lib.rs‎

Lines changed: 28 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,45 @@
55
#![deny(unsafe_op_in_unsafe_fn)]
66
#![allow(clippy::not_unsafe_ptr_arg_deref)]
77

8-
//! C/C++ FFI for DID:x509 parsing, building, validation and resolution.
8+
//! C-ABI projection for `did_x509`.
99
//!
10-
//! This crate (`did_x509_ffi`) provides FFI-safe wrappers for working with DID:x509
11-
//! identifiers from C and C++ code. It uses the `did_x509` crate for core functionality.
10+
//! This crate provides C-compatible FFI exports for DID:x509 identifier
11+
//! operations. It wraps the `did_x509` crate, enabling C and C++ code to
12+
//! parse, build, validate, and resolve DID:x509 identifiers against X.509
13+
//! certificate chains.
1214
//!
13-
//! ## Error Handling
15+
//! # ABI Stability
16+
//!
17+
//! All exported functions use `extern "C"` calling convention.
18+
//! Opaque handle types are passed as `*mut` (owned) or `*const` (borrowed).
19+
//! The ABI version is available via `did_x509_abi_version()`.
20+
//!
21+
//! # Panic Safety
22+
//!
23+
//! All exported functions are wrapped in `catch_unwind` to prevent
24+
//! Rust panics from crossing the FFI boundary.
25+
//!
26+
//! # Error Handling
1427
//!
1528
//! All functions follow a consistent error handling pattern:
1629
//! - Return value: 0 = success, negative = error code
1730
//! - `out_error` parameter: Set to error handle on failure (caller must free)
1831
//! - Output parameters: Only valid if return is 0
1932
//!
20-
//! ## Memory Management
33+
//! # Memory Ownership
2134
//!
22-
//! Handles and strings returned by this library must be freed using the corresponding `*_free` function:
23-
//! - `did_x509_parsed_free` for parsed identifier handles
24-
//! - `did_x509_error_free` for error handles
25-
//! - `did_x509_string_free` for string pointers
35+
//! - `*mut T` parameters transfer ownership TO this function (consumed)
36+
//! - `*const T` parameters are borrowed (caller retains ownership)
37+
//! - `*mut *mut T` out-parameters transfer ownership FROM this function (caller must free)
38+
//! - Every handle type has a corresponding `*_free()` function:
39+
//! - `did_x509_parsed_free` for parsed identifier handles
40+
//! - `did_x509_error_free` for error handles
41+
//! - `did_x509_string_free` for string pointers
2642
//!
27-
//! ## Thread Safety
43+
//! # Thread Safety
2844
//!
29-
//! All handles are thread-safe and can be used from multiple threads. However, handles
30-
//! are not internally synchronized, so concurrent mutation requires external synchronization.
45+
//! All functions are thread-safe. Handles are not internally synchronized,
46+
//! so concurrent mutation requires external synchronization.
3147
3248
pub mod error;
3349
pub mod types;

‎native/rust/extension_packs/azure_artifact_signing/ffi/src/lib.rs‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,40 @@
33

44
#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
55

6-
//! Azure Artifact Signing pack FFI bindings.
6+
//! C-ABI projection for `cose_sign1_azure_artifact_signing`.
7+
//!
8+
//! This crate provides C-compatible FFI exports for the Azure Artifact Signing
9+
//! (AAS) extension pack. It enables C/C++ consumers to register the AAS trust
10+
//! pack with a validator builder, with support for both default and custom
11+
//! trust options (endpoint URL, account name, certificate profile name).
12+
//!
13+
//! # ABI Stability
14+
//!
15+
//! All exported functions use `extern "C"` calling convention.
16+
//! Opaque handle types are passed as `*mut` (owned) or `*const` (borrowed).
17+
//! The ABI version is available via `cose_sign1_ats_abi_version()`.
18+
//!
19+
//! # Panic Safety
20+
//!
21+
//! All exported functions are wrapped in `catch_unwind` to prevent
22+
//! Rust panics from crossing the FFI boundary.
23+
//!
24+
//! # Error Handling
25+
//!
26+
//! Functions return `cose_status_t` (0 = OK, non-zero = error).
27+
//! On error, call `cose_last_error_message_utf8()` for details.
28+
//! Error state is thread-local and safe for concurrent use.
29+
//!
30+
//! # Memory Ownership
31+
//!
32+
//! - `*mut T` parameters transfer ownership TO this function (consumed)
33+
//! - `*const T` parameters are borrowed (caller retains ownership)
34+
//! - `*mut *mut T` out-parameters transfer ownership FROM this function (caller must free)
35+
//! - Every handle type has a corresponding `*_free()` function
36+
//!
37+
//! # Thread Safety
38+
//!
39+
//! All functions are thread-safe. Error state is thread-local.
740
841
#![deny(unsafe_op_in_unsafe_fn)]
942
#![allow(clippy::not_unsafe_ptr_arg_deref)]

‎native/rust/extension_packs/azure_key_vault/ffi/README.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT License. -->
2+
3+
# cose_sign1_azure_key_vault_ffi
4+
5+
C/C++ FFI projection for the Azure Key Vault extension pack.
6+
7+
## Overview
8+
9+
This crate provides C-compatible FFI exports for the Azure Key Vault trust pack.
10+
It enables C/C++ consumers to register the AKV trust pack with a validator builder,
11+
author trust policies that constrain Key Vault KID properties, and create signing
12+
keys and signing services backed by Azure Key Vault.
13+
14+
## Exported Functions
15+
16+
### Pack Registration
17+
18+
| Function | Description |
19+
|----------|-------------|
20+
| `cose_sign1_validator_builder_with_akv_pack` | Add AKV pack (default options) |
21+
| `cose_sign1_validator_builder_with_akv_pack_ex` | Add AKV pack (custom options) |
22+
23+
### KID Trust Policies
24+
25+
| Function | Description |
26+
|----------|-------------|
27+
| `..._require_azure_key_vault_kid` | Require AKV KID detected |
28+
| `..._require_not_azure_key_vault_kid` | Require AKV KID not detected |
29+
| `..._require_azure_key_vault_kid_allowed` | Require KID is in allowed list |
30+
| `..._require_azure_key_vault_kid_not_allowed` | Require KID is not in allowed list |
31+
32+
### Key Client Lifecycle
33+
34+
| Function | Description |
35+
|----------|-------------|
36+
| `cose_akv_key_client_new_dev` | Create key client (dev credentials) |
37+
| `cose_akv_key_client_new_client_secret` | Create key client (client secret) |
38+
| `cose_akv_key_client_free` | Free a key client handle |
39+
40+
### Signing Operations
41+
42+
| Function | Description |
43+
|----------|-------------|
44+
| `cose_sign1_akv_create_signing_key` | Create a signing key from AKV |
45+
| `cose_sign1_akv_create_signing_service` | Create a signing service from AKV |
46+
| `cose_sign1_akv_signing_service_free` | Free a signing service handle |
47+
48+
## Handle Types
49+
50+
| Type | Description |
51+
|------|-------------|
52+
| `cose_akv_trust_options_t` | C ABI options struct for AKV trust configuration |
53+
| `AkvKeyClientHandle` | Opaque Azure Key Vault key client |
54+
| `AkvSigningServiceHandle` | Opaque AKV-backed signing service |
55+
56+
## C Header
57+
58+
`<cose/sign1/extension_packs/azure_key_vault.h>`
59+
60+
## Parent Library
61+
62+
[`cose_sign1_azure_key_vault`](../../azure_key_vault/) — Azure Key Vault trust pack implementation.
63+
64+
## Build
65+
66+
```bash
67+
cargo build --release -p cose_sign1_azure_key_vault_ffi
68+
```

‎native/rust/extension_packs/azure_key_vault/ffi/src/lib.rs‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,42 @@
1-
//! Azure Key Vault pack FFI bindings.
1+
// Copyright (c) Microsoft Corporation.
2+
// Licensed under the MIT License.
3+
4+
//! C-ABI projection for `cose_sign1_azure_key_vault`.
5+
//!
6+
//! This crate provides C-compatible FFI exports for the Azure Key Vault
7+
//! extension pack. It enables C/C++ consumers to register the Azure Key Vault
8+
//! trust pack with a validator builder, author trust policies that constrain
9+
//! Key Vault KID properties (detection, allowed/denied lists), and create
10+
//! signing keys and signing services backed by Azure Key Vault.
11+
//!
12+
//! # ABI Stability
13+
//!
14+
//! All exported functions use `extern "C"` calling convention.
15+
//! Opaque handle types are passed as `*mut` (owned) or `*const` (borrowed).
16+
//!
17+
//! # Panic Safety
18+
//!
19+
//! All exported functions are wrapped in `catch_unwind` to prevent
20+
//! Rust panics from crossing the FFI boundary.
21+
//!
22+
//! # Error Handling
23+
//!
24+
//! Functions return `cose_status_t` (0 = OK, non-zero = error).
25+
//! On error, call `cose_last_error_message_utf8()` for details.
26+
//! Error state is thread-local and safe for concurrent use.
27+
//!
28+
//! # Memory Ownership
29+
//!
30+
//! - `*mut T` parameters transfer ownership TO this function (consumed)
31+
//! - `*const T` parameters are borrowed (caller retains ownership)
32+
//! - `*mut *mut T` out-parameters transfer ownership FROM this function (caller must free)
33+
//! - Every handle type has a corresponding `*_free()` function:
34+
//! - `cose_akv_key_client_free` for key client handles
35+
//! - `cose_sign1_akv_signing_service_free` for signing service handles
36+
//!
37+
//! # Thread Safety
238
//!
3-
//! This crate exposes the Azure Key Vault KID validation pack and signing key creation to C/C++ consumers.
39+
//! All functions are thread-safe. Error state is thread-local.
440
541
#![cfg_attr(coverage_nightly, feature(coverage_attribute))]
642
#![deny(unsafe_op_in_unsafe_fn)]

‎native/rust/extension_packs/certificates/ffi/README.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT License. -->
2+
3+
# cose_sign1_certificates_ffi
4+
5+
C/C++ FFI projection for the X.509 certificate validation extension pack.
6+
7+
## Overview
8+
9+
This crate provides C-compatible FFI exports for registering the X.509 certificate trust pack
10+
with a validator builder and authoring trust policies that constrain X.509 chain properties.
11+
Supported constraints include chain trust status, chain element identity and validity, public key
12+
algorithms, and signing certificate identity.
13+
14+
## Exported Functions
15+
16+
### Pack Registration
17+
18+
| Function | Description |
19+
|----------|-------------|
20+
| `cose_sign1_validator_builder_with_certificates_pack` | Add certificate pack (default options) |
21+
| `cose_sign1_validator_builder_with_certificates_pack_ex` | Add certificate pack (custom options) |
22+
23+
### Chain Trust Policies
24+
25+
| Function | Description |
26+
|----------|-------------|
27+
| `..._require_x509_chain_trusted` | Require chain is trusted |
28+
| `..._require_x509_chain_not_trusted` | Require chain is not trusted |
29+
| `..._require_x509_chain_built` | Require chain was successfully built |
30+
| `..._require_x509_chain_not_built` | Require chain was not built |
31+
| `..._require_x509_chain_element_count_eq` | Require specific chain length |
32+
| `..._require_x509_chain_status_flags_eq` | Require specific chain status flags |
33+
| `..._require_leaf_chain_thumbprint_present` | Require leaf thumbprint present |
34+
| `..._require_leaf_subject_eq` | Require leaf subject matches |
35+
| `..._require_issuer_subject_eq` | Require issuer subject matches |
36+
| `..._require_leaf_issuer_is_next_chain_subject_optional` | Require leaf-to-chain issuer linkage |
37+
38+
### Signing Certificate Policies
39+
40+
| Function | Description |
41+
|----------|-------------|
42+
| `..._require_signing_certificate_present` | Require signing cert present |
43+
| `..._require_signing_certificate_subject_issuer_matches_*` | Require subject-issuer match |
44+
| `..._require_signing_certificate_thumbprint_eq` | Require specific thumbprint |
45+
| `..._require_signing_certificate_thumbprint_present` | Require thumbprint present |
46+
| `..._require_signing_certificate_subject_eq` | Require specific subject |
47+
| `..._require_signing_certificate_issuer_eq` | Require specific issuer |
48+
| `..._require_signing_certificate_serial_number_eq` | Require specific serial number |
49+
| `..._require_signing_certificate_*` (validity) | Time-based validity constraints |
50+
51+
### Chain Element Policies
52+
53+
| Function | Description |
54+
|----------|-------------|
55+
| `..._require_chain_element_subject_eq` | Require element subject matches |
56+
| `..._require_chain_element_issuer_eq` | Require element issuer matches |
57+
| `..._require_chain_element_thumbprint_eq` | Require element thumbprint matches |
58+
| `..._require_chain_element_thumbprint_present` | Require element thumbprint present |
59+
| `..._require_chain_element_*` (validity) | Element time-based validity constraints |
60+
61+
### Public Key Algorithm Policies
62+
63+
| Function | Description |
64+
|----------|-------------|
65+
| `..._require_not_pqc_algorithm_or_missing` | Require non-PQC algorithm |
66+
| `..._require_x509_public_key_algorithm_thumbprint_eq` | Require specific algorithm thumbprint |
67+
| `..._require_x509_public_key_algorithm_oid_eq` | Require specific algorithm OID |
68+
| `..._require_x509_public_key_algorithm_is_pqc` | Require PQC algorithm |
69+
| `..._require_x509_public_key_algorithm_is_not_pqc` | Require non-PQC algorithm |
70+
71+
### Key Utilities
72+
73+
| Function | Description |
74+
|----------|-------------|
75+
| `cose_sign1_certificates_key_from_cert_der` | Create key handle from DER certificate |
76+
77+
## Handle Types
78+
79+
| Type | Description |
80+
|------|-------------|
81+
| `cose_certificate_trust_options_t` | C ABI options struct for certificate trust configuration |
82+
83+
## C Header
84+
85+
`<cose/sign1/extension_packs/certificates.h>`
86+
87+
## Parent Library
88+
89+
[`cose_sign1_certificates`](../../certificates/) — X.509 certificate trust pack implementation.
90+
91+
## Build
92+
93+
```bash
94+
cargo build --release -p cose_sign1_certificates_ffi
95+
```

0 commit comments

Comments
 (0)