Skip to main content

Crate zerodds_security_pki

Crate zerodds_security_pki 

Source
Expand description

Crate zerodds-security-pki. Safety classification: SAFE (a pure wrapper around rustls-webpki; no raw-crypto code in this crate).

PKI/X.509 backend for the DDS-Security 1.1 §8.3 AuthenticationPlugin SPI: identity validation, handshake-token sign/verify, OCSP stapling liveness, CRL validation, delegation chains.

§Layer position

Layer 4 — Core Services. Consumes zerodds-security (SPI).

§Public API (as of 1.0.0-rc.1)

  • PkiAuthenticationPlugin — AuthenticationPlugin impl (X.509 + RSA-PSS + ECDSA-P256/P384 + Ed25519).
  • IdentityConfig / IdentityHandle — identity loading.
  • [HandshakeToken] / [HandshakeError] — handshake state machine (challenge/response).
  • [AuthRequestMessage] — auth_request token codec (spec §9.3.2.4).
  • IdentityStatusToken — identity-status subscription (spec §8.3.2.13).
  • ocsp module — OCSP stapling validation (RFC 6960).
  • crl module — CRL online checks + cache.
  • delegation module — DelegationLink sign/verify + DelegationChain.
  • PskAuthenticationPlugin — PSK variant (spec §10.7).

§Architecture rationale

All real crypto checks delegate to rustls-webpki (the same code that rustls uses for TLS). We only adapt the input (PEM → DER) and the output (OK/Err) to the AuthenticationPlugin trait. This avoids our own crypto implementation and profits from rustls’ audit history.

§Example (pseudo — real PEMs are missing in the doctest)

ⓘ
use zerodds_security::AuthenticationPlugin;
use zerodds_security_pki::{PkiAuthenticationPlugin, IdentityConfig};

let mut plugin = PkiAuthenticationPlugin::new();
let cfg = IdentityConfig {
    identity_cert_pem: ALICE_CERT_PEM.into(),
    identity_ca_pem: CA_PEM.into(),
};
let local = plugin.validate_with_config(cfg, [0xAA; 16])?;

Re-exports§

pub use auth_request::AUTH_REQUEST_CLASS_ID;
pub use auth_request::AuthRequestToken;
pub use auth_request::FUTURE_CHALLENGE_KEY;
pub use auth_request::auth_request_properties;
pub use crl::CrlParseError;
pub use crl::parse_crl_serials;
pub use crl::validate_crl;
pub use delegation::DELEGATION_MAGIC;
pub use delegation::DELEGATION_VERSION;
pub use delegation::DelegationChain;
pub use delegation::DelegationError;
pub use delegation::DelegationResult;
pub use delegation::MAX_CHAIN_DEPTH_HARD_CAP;
pub use delegation::MAX_PARTITION_PATTERNS;
pub use delegation::MAX_PATTERN_LEN;
pub use delegation::MAX_TOPIC_PATTERNS;
pub use delegation::SignatureAlgorithm;
pub use guid_adjust::adjust_participant_guid_prefix;
pub use handshake_token::FinalBuildInput;
pub use handshake_token::FinalTokenView;
pub use handshake_token::ReplyBuildInput;
pub use handshake_token::ReplyTokenView;
pub use handshake_token::RequestBuildInput;
pub use handshake_token::RequestTokenView;
pub use handshake_token::algo;
pub use handshake_token::build_final_token;
pub use handshake_token::build_reply_token;
pub use handshake_token::build_request_token;
pub use handshake_token::class_id;
pub use handshake_token::compute_hash_c;
pub use handshake_token::final_signing_bytes;
pub use handshake_token::parse_final_token;
pub use handshake_token::parse_reply_token;
pub use handshake_token::parse_request_token;
pub use handshake_token::prop;
pub use handshake_token::reply_signing_bytes;
pub use handshake_token::serialize_bin_prop_seq;
pub use identity_status::IDENTITY_STATUS_CLASS_ID;
pub use identity_status::IdentityStatusKind;
pub use identity_status::IdentityStatusToken;
pub use identity_status::KEY_EXPIRY_TIME;
pub use identity_status::KEY_OCSP_RESPONSE;
pub use identity_status::KEY_OCSP_STATUS;
pub use identity_status::identity_status_properties;
pub use identity_token::IDENTITY_TOKEN_CLASS_ID;
pub use identity_token::IdentityToken;
pub use identity_token::KEY_CA_ALGO;
pub use identity_token::KEY_CA_SN;
pub use identity_token::KEY_CERT_ALGO;
pub use identity_token::KEY_CERT_SN;
pub use identity_token::build_identity_token_from_der;
pub use identity_token::build_identity_token_from_pem;
pub use identity_token::subject_match;
pub use psk::HKDF_INFO_SHARED_SECRET;
pub use psk::PROP_PSK_ID;
pub use psk::PROP_PSK_KEY_HEX;
pub use psk::PskAuthenticationPlugin;
pub use psk::derive_psk_shared_secret;

Modules§

auth_request
AuthRequestMessageToken — DDS-Security 1.2 §9.3.2.5.1.1.
crl
CRL validation (certificate revocation list, RFC 5280 §5).
delegation
Delegation link / delegation chain.
guid_adjust
DDS-Security §9.3.3 participant GUID adjustment.
handshake_token
DDS-Security 1.2 §10.3.2.6-8 — HandshakeMessageToken Codec.
identity_status
IdentityStatusToken — DDS-Security 1.2 §9.3.2.5.1.2.
identity_token
IdentityToken (PKI-DH) — DDS-Security 1.2 §10.3.2.1.
psk
Built-in pre-shared-key authentication plugin (spec §10.7).

Structs§

BinaryProperty
Spec §7.2.6 Tab.6 — wire BinaryProperty_t (name + value as sequence<octet>).
DataHolder
Spec §7.2.7 Tab.7 — generic DataHolder_t wire struct. All security tokens are type aliases of DataHolder with a fixed class_id value.
HandshakeHandle
Opaque handle for a running handshake.
IdentityConfig
One input for crate::PkiAuthenticationPlugin::validate_with_config: identity certificate + associated CA (both PEM).
IdentityHandle
Opaque handle for a validated identity. The plugin-internal state (X.509 cert, keys) is not exposed outward through this handle.
PkiAuthenticationPlugin
PKI/X.509-based AuthenticationPlugin. Verifies identity certs against a given trust anchor and runs a 3-round PKI-DH handshake (spec §10.3.2.6-8 Tab.56/57/58) with the peer.
SharedSecretHandle
Opaque handle for a shared secret (output of a completed handshake). Passed on to the CryptographicPlugin.
WireProperty
Spec §7.2.6 Tab.5 — wire Property_t (name + value, both CDR strings). Unlike crate::Property, no propagate field; token properties are always propagated.

Enums§

CertKeyAlgo
Detected algorithm from the identity cert. Determines which c.dsign_algo values and sign routines are used.
HandshakeStepOutcome
Result of a handshake step.
OcspStatus
Cert status from an OCSP response.
PkiError
Internal errors of the PKI backend. Wrapped in zerodds_security::SecurityError.

Functions§

first_cert_der
Extracts the DER of the first certificate from a PEM block.
parse_ocsp_status
Scans a DER OCSP response and returns the cert status for the (single) contained SingleResponse.
require_good_status
High level: returns Ok(()) only if the response is Good. Any other status → Err with SecurityErrorKind::AuthenticationFailed.