security-rs 0.2.0

Safe Rust bindings for Apple's Security framework — keychain, identity, certificates, trust, authorization, CMS, SecureTransport, and cryptographic primitives on macOS
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

# security-rs

Safe Rust bindings for Apple's [Security](https://developer.apple.com/documentation/security) framework on macOS.

> **Status:** v0.2.0 adopts a Swift bridge for the safe API and expands coverage across keychain, identities, certificates, policies, trust, authorization, code signing, random bytes, transforms, SecureTransport, CMS, key derivation, and key agreement.

## Highlights

- Swift bridge over `Security.framework` with retained opaque handles and ergonomic Rust wrappers.
- Raw C FFI preserved behind the `raw-ffi` Cargo feature.
- Safe modules for all primary logical areas:
  - `keychain`
  - `identity`
  - `certificate`
  - `policy`
  - `trust`
  - `authorization`
  - `code`
  - `random_bytes`
  - `transform`
  - `secure_transport`
  - `cms`
  - `key_derivation`
  - `key_agreement`
- Headless examples and smoke tests for every area.

## Quick start

```rust,no_run
use security::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let certificate = Certificate::from_der(&std::fs::read("tests/fixtures/test-cert.der")?)?;
    let policy = Policy::basic_x509()?;
    let mut trust = Trust::new(&certificate, &[policy])?;
    trust.set_anchor_certificates(&[certificate])?;
    trust.set_anchor_certificates_only(true)?;
    trust.evaluate()?;

    let encoded = Transform::encode_base64(b"hello")?;
    assert_eq!(Transform::decode_base64(encoded.as_bytes())?, b"hello");

    let random = SecureRandom::bytes(16)?;
    assert_eq!(random.len(), 16);
    Ok(())
}
```

## Area overview

- **`Keychain`:** generic-password CRUD and service account listing.
- **`Identity`:** PKCS#12 import, certificate access, and private-key attribute inspection.
- **`Certificate`:** DER/PEM loading, summaries, names, emails, serials, validity dates, and public keys.
- **`Policy` / `Trust`:** basic X.509, SSL, revocation, custom anchors, and evaluated trust results.
- **`Authorization`:** authorization creation and external-form round trips.
- **`Code`:** current-process code objects, static-code inspection, designated requirements, and task entitlements.
- **`RandomBytes`:** `SecRandomCopyBytes` wrappers.
- **`Transform`:** base64 encode/decode using deprecated but still functional `SecTransform` APIs.
- **`SecureTransport`:** minimal context creation, protocol bounds, and state inspection.
- **`CMS`:** certificate-bag encode/decode.
- **`KeyDerivation`:** PBKDF2-style symmetric-key derivation through `SecKeyDeriveFromPassword`.
- **`KeyAgreement`:** ephemeral P-256 key generation and ECDH shared-secret derivation.

## Examples

Run every numbered example:

```bash
for ex in examples/*.rs; do cargo run --example "$(basename "$ex" .rs)"; done
```

Key examples:

- `01_keychain_password`
- `05_trust_evaluate`
- `07_code_signing_info`
- `11_cms_cert_bag`
- `13_key_agreement_shared_secret`

## Raw FFI

Enable the legacy raw C declarations when you need direct `Security.framework` symbols:

```bash
cargo test --features raw-ffi
```

The default API path stays on the Swift bridge so Rust code does not call the C-only framework surface directly.

## Coverage notes

See [COVERAGE.md](COVERAGE.md) for the header audit and per-area implementation / partial / skipped status.

## License

Licensed under either of [Apache-2.0](LICENSE-APACHE) or [MIT](LICENSE-MIT) at your option.