noxtls-psa 0.1.2

Internal implementation crate for noxtls: PSA Crypto adapter and provider abstractions.
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

// Copyright (c) 2019-2026, Argenox Technologies LLC
// All rights reserved.
//
// SPDX-License-Identifier: GPL-2.0-only OR LicenseRef-Argenox-Commercial-License
//
// This file is part of the NoxTLS Library.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by the
// Free Software Foundation; version 2 of the License.
//
// Alternatively, this file may be used under the terms of a commercial
// license from Argenox Technologies LLC.
//
// See `noxtls/LICENSE` and `noxtls/LICENSE.md` in this repository for full details.
// CONTACT: info@argenox.com

use noxtls_core::{Error, Result};

/// Enumerates normalized PSA status classes used by the public adapter layer.
#[derive(Copy, Clone, Debug, Eq, PartialEq)]
pub enum PsaResultCode {
    /// The operation completed successfully.
    Success,
    /// A supplied argument or encoded payload is invalid.
    InvalidArgument,
    /// The requested operation is not permitted by key policy.
    NotPermitted,
    /// The key handle is unknown or no longer valid.
    InvalidHandle,
    /// Operation failed because output or input buffer sizes are insufficient.
    BufferTooSmall,
    /// Operation failed due to capability not present in the target backend.
    NotSupported,
    /// Signature, MAC, or decrypt checks failed.
    InvalidSignature,
    /// A generic backend failure was returned.
    GenericError,
}

/// Carries a normalized PSA error class and optional backend detail.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct PsaError {
    /// Normalized status class for API consumers.
    pub code: PsaResultCode,
    /// Optional backend-specific numeric status code.
    pub detail_status: Option<i32>,
}

impl PsaError {
    /// Constructs a new normalized PSA error object.
    ///
    /// # Arguments
    ///
    /// * `code` - Normalized status class derived from PSA backend behavior.
    /// * `detail_status` - Optional backend status integer for diagnostics.
    ///
    /// # Returns
    ///
    /// A new [`PsaError`] value with caller-provided fields.
    pub fn new(code: PsaResultCode, detail_status: Option<i32>) -> Self {
        Self {
            code,
            detail_status,
        }
    }

    /// Converts this PSA error to a `noxtls-core` error with uniform posture.
    ///
    /// # Arguments
    ///
    /// * `self` - Error instance produced by PSA wrapper or provider layers.
    ///
    /// # Returns
    ///
    /// A [`noxtls_core::Error`] suited for protocol/provider integration.
    pub fn to_noxtls_error(&self) -> Error {
        match self.code {
            PsaResultCode::Success => Error::CryptoFailure("psa success mapped as error"),
            PsaResultCode::InvalidArgument => Error::ParseFailure("psa invalid argument"),
            PsaResultCode::NotPermitted => Error::StateError("psa operation not permitted"),
            PsaResultCode::InvalidHandle => Error::StateError("psa key handle invalid"),
            PsaResultCode::BufferTooSmall => Error::InvalidLength("psa buffer too small"),
            PsaResultCode::NotSupported => Error::UnsupportedFeature("psa capability unavailable"),
            PsaResultCode::InvalidSignature => {
                Error::CryptoFailure("psa cryptographic operation failed")
            }
            PsaResultCode::GenericError => Error::CryptoFailure("psa backend failure"),
        }
    }
}

/// Converts a raw PSA status code to a normalized [`PsaResultCode`].
///
/// # Arguments
///
/// * `status` - Backend-provided status integer from PSA-like API surface.
///
/// # Returns
///
/// A normalized status class that can be mapped to stable noxtls errors.
pub fn normalize_psa_status(status: i32) -> PsaResultCode {
    match status {
        0 => PsaResultCode::Success,
        -133 => PsaResultCode::NotPermitted,
        -134 => PsaResultCode::InvalidArgument,
        -136 => PsaResultCode::InvalidHandle,
        -138 => PsaResultCode::BufferTooSmall,
        -1344 => PsaResultCode::InvalidSignature,
        -1345 => PsaResultCode::NotSupported,
        _ => PsaResultCode::GenericError,
    }
}

/// Translates a raw PSA status into a `noxtls-core` result.
///
/// # Arguments
///
/// * `status` - Raw PSA status integer where zero indicates success.
///
/// # Returns
///
/// Returns `Ok(())` when status is success, otherwise a mapped noxtls error.
///
/// # Errors
///
/// Returns mapped [`noxtls_core::Error`] for any non-zero status.
pub fn map_status_to_result(status: i32) -> Result<()> {
    let normalized = normalize_psa_status(status);
    if normalized == PsaResultCode::Success {
        Ok(())
    } else {
        Err(PsaError::new(normalized, Some(status)).to_noxtls_error())
    }
}