oxicrypt 0.26.1

Rust interface to the separately built and signed oxicrypt shared library (liboxicrypt_ffi). Outside the cryptographic boundary and not the module itself: holds no cryptographic code and depends on no oxicrypt-* crate.
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
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
//! Initialisation of the library and the `Module` token.

use core::ffi::{CStr, c_int};
use core::fmt;
use std::sync::OnceLock;

use crate::error::{DetailError, Error, InitError, Site, status};
use crate::sys;

/// An algorithm profile of the module.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum Profile {
    /// Code 0: every approved algorithm.
    Unrestricted,
    /// Code 1: the CNSA 2.0 suite.
    Cnsa2,
    /// Code 2: the CNSA 1.0 suite.
    Cnsa1,
    /// Code 3: CNSA 1.0 and CNSA 2.0 together; not a CNSA profile.
    Migration,
    /// A code this crate does not know. The library refuses it as an
    /// initialisation request with [`Error::InvalidInput`]; it appears when a
    /// newer library reports a profile this crate predates. `Unknown` of a
    /// code this crate does know is that profile: [`Module::init`] treats
    /// `Unknown(1)` as [`Profile::Cnsa2`].
    Unknown(i32),
}

impl Profile {
    /// The code the C ABI uses for this profile.
    #[must_use]
    pub const fn code(self) -> i32 {
        match self {
            Self::Unrestricted => 0,
            Self::Cnsa2 => 1,
            Self::Cnsa1 => 2,
            Self::Migration => 3,
            Self::Unknown(code) => code,
        }
    }

    /// The profile a C ABI code names.
    #[must_use]
    pub const fn from_code(code: i32) -> Self {
        match code {
            0 => Self::Unrestricted,
            1 => Self::Cnsa2,
            2 => Self::Cnsa1,
            3 => Self::Migration,
            other => Self::Unknown(other),
        }
    }
}

/// The pre-operational integrity test's indicator, as `oxi_integrity_status`
/// reports it. The library latches it on the first run.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum IntegrityStatus {
    /// 0: the test has not run in this process.
    NotRun,
    /// 1: the signature over the image verified.
    Passed,
    /// 2: the image does not match its signature.
    SignatureInvalid,
    /// 3: the slot is the unsigned template.
    SlotInvalid,
    /// 4: the test was not performed: the image could not be read.
    Unreadable,
    /// 5: the test was reached before its self-tests passed.
    CastNotRun,
    /// 6: the record held a value the library never writes (the header's
    /// `Unknown`).
    UnknownRecord,
    /// 7: the module refused a primitive, so the test was not performed.
    Refused,
    /// 8: the library carries no verifying key.
    NoVerifyKey,
    /// 9: the slot was signed for a different key than the library embeds.
    KeyMismatch,
    /// 10: the slot, the key record or a bound import is damaged.
    SlotDamaged,
    /// A value this crate does not know.
    Unknown(i32),
}

impl IntegrityStatus {
    /// The indicator a C ABI value names.
    #[must_use]
    pub const fn from_code(code: i32) -> Self {
        match code {
            0 => Self::NotRun,
            1 => Self::Passed,
            2 => Self::SignatureInvalid,
            3 => Self::SlotInvalid,
            4 => Self::Unreadable,
            5 => Self::CastNotRun,
            6 => Self::UnknownRecord,
            7 => Self::Refused,
            8 => Self::NoVerifyKey,
            9 => Self::KeyMismatch,
            10 => Self::SlotDamaged,
            other => Self::Unknown(other),
        }
    }
}

/// The SHA-256 fingerprint of the verifying key a library embeds. Public
/// data: it names a signer.
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct Fingerprint([u8; 32]);

impl Fingerprint {
    /// The 32 bytes of the fingerprint.
    #[must_use]
    pub const fn as_bytes(&self) -> &[u8; 32] {
        &self.0
    }

    /// Parses exactly 64 hex digits, with or without the `sha256:` prefix.
    /// Anything else, a sign or whitespace included, is `None`.
    #[must_use]
    pub fn from_hex(text: &str) -> Option<Self> {
        let hex = text.strip_prefix("sha256:").unwrap_or(text).as_bytes();
        if hex.len() != 64 || !hex.iter().all(u8::is_ascii_hexdigit) {
            return None;
        }
        let mut out = [0u8; 32];
        for (byte, pair) in out.iter_mut().zip(hex.chunks_exact(2)) {
            let digits = core::str::from_utf8(pair).ok()?;
            *byte = u8::from_str_radix(digits, 16).ok()?;
        }
        Some(Self(out))
    }
}

impl fmt::Display for Fingerprint {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("sha256:")?;
        for b in &self.0 {
            write!(f, "{b:02x}")?;
        }
        Ok(())
    }
}

impl fmt::Debug for Fingerprint {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self, f)
    }
}

/// Proof that the library this program loaded is initialised.
///
/// Returned only by a successful [`Module::init`] (or
/// [`Module::init_unpinned`]); every service is a method on it, so a call
/// before initialisation does not compile. It does not make a service
/// infallible: a conditional self-test can move the library to its error
/// state between calls, after which every service returns
/// [`Error::NotOperational`].
#[derive(Debug, Clone, Copy)]
pub struct Module {
    _private: (),
}

/// Which verifying key `init_with` accepts.
#[derive(Clone, Copy)]
enum Pin {
    /// Only the key whose fingerprint is these 64 hex digits.
    #[cfg_attr(not(any(oxicrypt_pinned, doc)), allow(dead_code))]
    Required(&'static str),
    /// Any key.
    #[cfg_attr(not(oxicrypt_unpinned), allow(dead_code))]
    Unpinned,
}

/// The fingerprint `OXICRYPT_LIB_FINGERPRINT` pinned at build time, as 64
/// lower-case hex digits.
#[cfg(oxicrypt_pinned)]
const PIN: &str = env!("OXICRYPT_BINDINGS_PIN");

impl Module {
    /// Initialises the library with `profile` and checks that it is the
    /// library this crate was built for.
    ///
    /// In order: the library's `oxi_abi_version` must return this crate's
    /// [`OXI_ABI_VERSION`](crate::OXI_ABI_VERSION), else
    /// [`Error::LibraryAbi`]; a library without that function must be this
    /// crate's own release version, else [`Error::LibraryVersion`] (checked
    /// once per loaded library, before anything but `lama_manifest` is
    /// called). Then `oxi_init(profile)` must return 0, else the code it
    /// returned is reported with the integrity indicator and detail as the
    /// library reports them after this call; the library must report itself
    /// operational; its integrity indicator must read
    /// [`IntegrityStatus::Passed`], else [`Error::IntegrityUnverified`]; the
    /// verifying key it embeds must have the fingerprint pinned at build
    /// time; and its active profile must be `profile`. Operational state, the
    /// indicator and the active profile are read on every call, never cached.
    ///
    /// The first call runs the library's power-up self-tests and blocks for
    /// their duration. Later calls are cheap, and every caller sharing the
    /// loaded library shares its one initialisation: a later call with
    /// another profile is refused with [`Error::ProfileMismatch`]. A failed
    /// initialisation is terminal for the loaded library until the process
    /// restarts; this function never retries it.
    ///
    /// Present when the crate was built with `OXICRYPT_LIB_FINGERPRINT`.
    #[cfg(any(oxicrypt_pinned, doc))]
    #[allow(clippy::result_large_err)] // not a hot path; the size is immaterial
    pub fn init(profile: Profile) -> Result<Self, InitError> {
        #[cfg(oxicrypt_pinned)]
        let pin = Pin::Required(PIN);
        // A documentation build without a pin compiles a body that accepts
        // no library.
        #[cfg(not(oxicrypt_pinned))]
        let pin = Pin::Required("");
        Self::init_with(profile, pin)
    }

    /// As [`Module::init`], accepting a library that embeds any verifying key.
    ///
    /// Present only when the crate was built with `OXICRYPT_LIB_UNPINNED=1`.
    #[cfg(any(oxicrypt_unpinned, doc))]
    #[allow(clippy::result_large_err)] // not a hot path; the size is immaterial
    pub fn init_unpinned(profile: Profile) -> Result<Self, InitError> {
        Self::init_with(profile, Pin::Unpinned)
    }

    #[cfg_attr(not(any(oxicrypt_pinned, oxicrypt_unpinned)), allow(dead_code))]
    #[allow(clippy::result_large_err)] // not a hot path; the size is immaterial
    fn init_with(profile: Profile, pin: Pin) -> Result<Self, InitError> {
        // `Unknown(1)` and `Cnsa2` send the same code, so they must be the
        // same request.
        let profile = Profile::from_code(profile.code());
        let refused = |code| InitError {
            code,
            integrity: Some(integrity_status()),
            detail: integrity_detail(),
        };
        // A library the ABI or version check refuses is called for nothing
        // but its manifest and `oxi_abi_version`, so its indicator is not
        // read.
        library_compatible().map_err(|code| InitError {
            code,
            integrity: None,
            detail: Ok(None),
        })?;
        // SAFETY: U1; no pointers.
        let code = unsafe { sys::oxi_init(profile.code()) };
        status(code, Site::Other).map_err(refused)?;
        // A correct library returns 0 from `oxi_init` only when it is
        // operational; this refusal holds if it is not, which the control
        // tests provoke with an overriding shared object.
        // SAFETY: U1; no pointers.
        if unsafe { sys::oxi_is_operational() } != 1 {
            return Err(refused(Error::NotOperational));
        }
        // An operational library has passed its integrity test; the
        // indicator must say so, or the library is refused.
        if integrity_status() != IntegrityStatus::Passed {
            return Err(refused(Error::IntegrityUnverified));
        }
        if let Pin::Required(hex) = pin {
            let found = key_fingerprint().map_err(refused)?;
            if found.to_string() != format!("sha256:{hex}") {
                let expected = Fingerprint::from_hex(hex).unwrap_or(Fingerprint([0; 32]));
                return Err(refused(Error::KeyFingerprint { found, expected }));
            }
        }
        // SAFETY: U1; no pointers.
        let active = Profile::from_code(unsafe { sys::oxi_active_profile() });
        if active != profile {
            return Err(refused(Error::ProfileMismatch {
                active,
                requested: profile,
            }));
        }
        Ok(Self { _private: () })
    }

    /// Whether the library is in its operational state now, read live.
    #[must_use]
    pub fn is_operational(self) -> bool {
        // SAFETY: U1; no pointers.
        unsafe { sys::oxi_is_operational() == 1 }
    }

    /// The integrity test's latched indicator.
    #[must_use]
    pub fn integrity_status(self) -> IntegrityStatus {
        integrity_status()
    }

    /// The fingerprint of the verifying key the library reports embedding,
    /// for a log line. Self-reported: it cannot authenticate the library.
    pub fn key_fingerprint(self) -> Result<Fingerprint, Error> {
        key_fingerprint()
    }

    /// The file the loader bound this program's `oxi_*` references to, for a
    /// log line. Never a check. `None` when the platform does not say.
    #[must_use]
    pub fn library_path() -> Option<std::path::PathBuf> {
        crate::platform::library_path()
    }
}

fn integrity_status() -> IntegrityStatus {
    // SAFETY: U1; no pointers.
    IntegrityStatus::from_code(unsafe { sys::oxi_integrity_status() })
}

fn key_fingerprint() -> Result<Fingerprint, Error> {
    let mut out = [0u8; 32];
    // SAFETY: U1; U3, `out` is 32 writable bytes and `out_len` says so.
    let code = unsafe { sys::oxi_integrity_key_fingerprint(out.as_mut_ptr(), out.len()) };
    status(code, Site::Other)?;
    Ok(Fingerprint(out))
}

/// The longest detail text the crate reads.
pub(crate) const DETAIL_MAX: usize = 64 * 1024;

fn integrity_detail() -> Result<Option<String>, DetailError> {
    let mut needed: usize = 0;
    // SAFETY: U1; U6, the sizing call: `out` null with `out_len` 0, which the
    // header permits, and `written` points to a live usize.
    let code =
        unsafe { sys::oxi_integrity_status_detail(core::ptr::null_mut(), 0, &raw mut needed) };
    detail_from((code, needed), |buf| {
        let mut written: usize = 0;
        // SAFETY: U1; U6, `buf` has the `needed` bytes the sizing call
        // reported, and `out_len` says so.
        let code = unsafe {
            sys::oxi_integrity_status_detail(buf.as_mut_ptr(), buf.len(), &raw mut written)
        };
        (code, written)
    })
}

/// The detail text from the sizing call's `(status, needed)` and a `read`
/// that fills a buffer of `needed` bytes and returns `(status, written)`.
pub(crate) fn detail_from(
    sizing: (c_int, usize),
    read: impl FnOnce(&mut [u8]) -> (c_int, usize),
) -> Result<Option<String>, DetailError> {
    let (code, needed) = sizing;
    // Status 1 with nothing needed: the integrity test has not failed, so
    // there is no text. Status 11 is the sizing call's normal answer.
    if needed == 0 && matches!(code, 0 | 1) {
        return Ok(None);
    }
    if !matches!(code, 0 | 11) {
        return Err(DetailError::Sizing(Error::from_code(code, Site::Other)));
    }
    if needed > DETAIL_MAX {
        return Err(DetailError::TooLong { needed });
    }
    let mut buf = vec![0u8; needed];
    let (code, written) = read(&mut buf);
    status(code, Site::Other).map_err(DetailError::Read)?;
    if written > buf.len() {
        return Err(DetailError::Overrun {
            written,
            capacity: buf.len(),
        });
    }
    buf.truncate(written);
    if buf.last() == Some(&0) {
        buf.pop();
    }
    Ok((!buf.is_empty()).then(|| String::from_utf8_lossy(&buf).into_owned()))
}

/// The library's API manifest, copied. `None` when the library returns null.
fn manifest() -> Option<String> {
    // SAFETY: U1; no pointers in.
    let ptr = unsafe { sys::lama_manifest() };
    if ptr.is_null() {
        return None;
    }
    // SAFETY: U5, the header states the string is NUL-terminated and valid
    // for the library's lifetime; it is copied before use.
    let text = unsafe { CStr::from_ptr(ptr) };
    Some(text.to_string_lossy().into_owned())
}

/// The value of `version:` directly under the top-level `library:` mapping
/// of a manifest, unquoted. No other `version:` key is read.
pub(crate) fn manifest_library_version(manifest: &str) -> Option<&str> {
    let mut in_library = false;
    let mut child_indent: Option<usize> = None;
    for line in manifest.lines() {
        let content = line.trim_start();
        if content.is_empty() || content.starts_with('#') {
            continue;
        }
        let indent = line.len().saturating_sub(content.len());
        if indent == 0 {
            if in_library {
                return None;
            }
            in_library = content.trim_end() == "library:";
            continue;
        }
        if !in_library {
            continue;
        }
        let expected = *child_indent.get_or_insert(indent);
        if indent != expected {
            continue;
        }
        if let Some(value) = content.strip_prefix("version:") {
            let value = value.split(" #").next().unwrap_or("").trim();
            let value = value
                .strip_prefix('"')
                .and_then(|v| v.strip_suffix('"'))
                .unwrap_or(value);
            return (!value.is_empty()).then_some(value);
        }
    }
    None
}

/// Whether the loaded library is one this crate may call: that its
/// `oxi_abi_version` returns this crate's ABI number or, for a library that
/// predates the function, that its manifest states exactly this crate's
/// version. Checked once per loaded library instance, calling nothing that needs
/// initialisation.
fn library_compatible() -> Result<(), Error> {
    static CHECKED: OnceLock<Result<(), Error>> = OnceLock::new();
    CHECKED
        .get_or_init(|| {
            match crate::platform::abi_version() {
                Some(library) if library == crate::OXI_ABI_VERSION => return Ok(()),
                Some(library) => {
                    return Err(Error::LibraryAbi {
                        library,
                        crate_: crate::OXI_ABI_VERSION,
                    });
                }
                None => {}
            }
            let crate_ = env!("CARGO_PKG_VERSION");
            let text = manifest();
            let library = text.as_deref().and_then(manifest_library_version);
            if library == Some(crate_) {
                Ok(())
            } else {
                Err(Error::LibraryVersion {
                    library: library.map(str::to_owned),
                    crate_,
                })
            }
        })
        .clone()
}

/// Shared by the safe layer: status 0 or the mapped error for `Site::Other`.
pub(crate) fn check(code: c_int) -> Result<(), Error> {
    status(code, Site::Other)
}