Struct PkiAuthenticationPlugin 

pub struct PkiAuthenticationPlugin { /* private fields */ }

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.

Wire (C3.1): three DataHolder tokens DDS:Auth:PKI-DH:1.2+AuthReq / +AuthReply / +AuthFinal. Both sides echo cert_der + dh* + challenge* + hash bindings. The replier signs (kagree || ch1 || dh1 || ch2 || dh2) with the identity private key; the initiator signs (kagree || ch2 || dh2 || ch1 || dh1).

Implementations

impl PkiAuthenticationPlugin

pub fn new() -> Self

Constructor.

pub fn set_local_permissions(&mut self, permissions_p7s: Vec<u8>)

Sets the local CMS-signed permissions document (.p7s bytes) that is sent along as c.perm in the HandshakeRequest/Reply. Required for cross-vendor interop with active AccessControl (FastDDS/Cyclone/RTI validate the permissions signature against the permissions_ca).

pub fn set_preferred_kx_suite(&mut self, suite: KxSuite)

Sets the preferred key agreement as initiator. Only for a deliberate vendor-extension choice (e.g. KxSuite::X25519 between pure ZeroDDS peers) — the default EcdhP256 is the spec/cross-vendor choice and should NOT be changed for interop.

pub fn validate_with_config( &mut self, cfg: IdentityConfig, _participant_guid: [u8; 16], ) -> SecurityResult<IdentityHandle>

Programmatic variant: pass IdentityConfig directly instead of a PropertyList. Useful for tests + native Rust callers.

Errors

See PkiError.

pub fn secret_bytes(&self, handle: SharedSecretHandle) -> Option<&[u8]>

Reads the raw 32-byte SharedSecret bytes. Primarily for tests; in the production path the SharedSecretHandle is passed through to the CryptoPlugin without the caller seeing the bytes.

Trait Implementations

impl AuthenticationPlugin for PkiAuthenticationPlugin

fn validate_local_identity( &mut self, props: &PropertyList, participant_guid: [u8; 16], ) -> SecurityResult<IdentityHandle>

Called once at participant start: validate the local identity (certificate, key, trust anchor) and return a handle.

fn validate_remote_identity( &mut self, local: IdentityHandle, _remote_participant_guid: [u8; 16], remote_auth_token: &[u8], ) -> SecurityResult<IdentityHandle>

Called as soon as a remote participant has been discovered via SPDP. The plugin validates the remote cert (from remote_auth_token) against its trust store.

fn get_identity_token(&self, local: IdentityHandle) -> SecurityResult<Vec<u8>>

Returns the IdentityToken for a local identity (spec §9.3.2.4). Published in the SPDP announce as PID_IDENTITY_TOKEN (0x1001). Default: empty token (= the plugin does not support the feature).

fn get_permissions_token(&self) -> Vec<u8>

Returns the PermissionsToken (spec §7.2.4, PID_PERMISSIONS_TOKEN 0x1002) for the SPDP announce. Strictly per spec the AccessControlPlugin produces it; since ZeroDDS holds the permissions in the auth plugin (set_local_permissions, for the c.perm handshake), the getter lives here. Default: empty (no permissions configured ⇒ AccessControl inactive ⇒ token omitted). Cross-vendor requirement: secure vendors (cyclone/FastDDS) only validate a remote if SPDP carries both tokens (identity + permissions).

fn set_local_participant_data(&mut self, pdata: Vec<u8>)

Sets the local ParticipantBuiltinTopicData as PL_CDR bytes that are sent along in the handshake as c.pdata (spec §9.3.2.5.2). The replier deserializes c.pdata as a ParameterList and binds the participant_guid to the authenticated identity. Default: no-op.

fn set_algo_nul_terminate(&mut self, nul: bool)

Cross-vendor quirk: determines whether the next handshake algorithm strings (c.dsign_algo/c.kagree_algo) are emitted + hashed NUL-terminated. OpenDDS compares them with sizeof (incl. \0) and needs the NUL form; FastDDS (#3803) needs them WITHOUT; cyclone is tolerant. Since the handshake runs per-peer, the discovery layer calls this based on the peer’s VendorId BEFORE begin_handshake_request or begin_handshake_reply. Default no-op (NUL-free = spec/FastDDS/ Cyclone-conformant).

fn begin_handshake_request( &mut self, initiator: IdentityHandle, _replier: IdentityHandle, ) -> SecurityResult<(HandshakeHandle, HandshakeStepOutcome)>

Starts the handshake. Returns the first token that must be sent to the peer.

fn begin_handshake_reply( &mut self, replier: IdentityHandle, _initiator: IdentityHandle, request_token: &[u8], ) -> SecurityResult<(HandshakeHandle, HandshakeStepOutcome)>

Peer side of the handshake start. request_token is what the initiator sent via begin_handshake_request.

fn process_handshake( &mut self, handshake: HandshakeHandle, token: &[u8], ) -> SecurityResult<HandshakeStepOutcome>

Pass through follow-up handshake messages.

fn shared_secret( &self, handshake: HandshakeHandle, ) -> SecurityResult<SharedSecretHandle>

Ends the handshake and returns the final SharedSecret. Failure aborts. Called by the caller after a Complete outcome to pull the secret out of the plugin.

fn plugin_class_id(&self) -> &str

Identity plugin name (e.g. “DDS:Auth:PKI-DH:1.2”). Announced in SPDP as dds.sec.auth.plugin_class.

fn get_identity_status_token( &self, _local: IdentityHandle, ) -> Result<Vec<u8>, SecurityError>

Returns the IdentityStatusToken for a local identity (spec §9.3.2.5.1.2). Default: empty.

fn set_permissions_credential_and_token( &mut self, _local: IdentityHandle, _permissions_credential: &[u8], _permissions_token: &[u8], ) -> Result<(), SecurityError>

Sets the permissions credential and the permissions token on a local identity (spec §9.3.2.4 + §9.3.2.5.4). Fed by the caller layer with the output of the AccessControlPlugin.

fn get_authenticated_peer_credential_token( &self, _handshake: HandshakeHandle, ) -> Result<Vec<u8>, SecurityError>

Returns the AuthenticatedPeerCredentialToken (spec §9.3.2.5.6). Fetched by the AccessControl layer after a successful handshake to perform the caller subject match. Default: empty.

impl Default for PkiAuthenticationPlugin

fn default() -> Self

Returns the “default value” for a type.

impl SharedSecretProvider for PkiAuthenticationPlugin

fn get_shared_secret(&self, handle: SharedSecretHandle) -> Option<Vec<u8>>

Returns the raw bytes of the shared key. None if the handle is unknown (handshake not yet completed or already discarded).

fn get_shared_secret_challenges( &self, handle: SharedSecretHandle, ) -> Option<([u8; 32], [u8; 32])>

Returns (challenge1, challenge2) of the associated handshake (challenge1 = initiator, challenge2 = replier). These feed into the VolatileSecure key derivation (DDS-Security §9.5.3.5, calculate_kx_keys) — both peers derive the same Kx key from (SharedSecret, challenge1, challenge2). Default None for providers without challenge tracking (e.g. PSK/mock); their Kx path then uses the fallback.