Struct Pkey 

pub struct Pkey<T> { /* private fields */ }

An asymmetric key (EVP_PKEY*) with a compile-time role marker.

Cloneable via EVP_PKEY_up_ref; wrapping in Arc<Pkey<T>> is safe.

Implementations

impl<T: HasParams> Pkey<T>

pub unsafe fn from_ptr(ptr: *mut EVP_PKEY) -> Self

Construct from a raw (owned) EVP_PKEY*.

Safety

ptr must be a valid, non-null EVP_PKEY* that the caller is giving up ownership of.

pub fn as_ptr(&self) -> *mut EVP_PKEY

Raw EVP_PKEY* pointer valid for the lifetime of self.

pub fn bits(&self) -> u32

Size of the key in bits (e.g. 256 for P-256, 2048 for RSA-2048).

pub fn security_bits(&self) -> u32

Security strength in bits (e.g. 128 for P-256, 112 for RSA-2048).

pub fn is_a(&self, name: &CStr) -> bool

Return true if this key is of the named algorithm (e.g. c"EC", c"RSA").

Examples found in repository

examples/pkcs12.rs (line 44)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── Generate key and self-signed certificate ───────────────────────────────

    let mut kgen = KeygenCtx::new(c"ED25519")?;
    let priv_key = kgen.generate()?;
    let pub_key = native_ossl::pkey::Pkey::<native_ossl::pkey::Public>::from(priv_key.clone());

    let mut name = X509NameOwned::new()?;
    name.add_entry_by_txt(c"CN", b"example.com")?;

    let cert = X509Builder::new()?
        .set_version(2)?
        .set_serial_number(1)?
        .set_not_before_offset(0)?
        .set_not_after_offset(365 * 86400)?
        .set_subject_name(&name)?
        .set_issuer_name(&name)?
        .set_public_key(&pub_key)?
        .sign(&priv_key, None)?
        .build();

    // ── Create the PKCS#12 bundle ─────────────────────────────────────────────

    let password = "correct horse battery staple";
    let p12 = Pkcs12::create(password, "example.com", &priv_key, &cert, &[])?;
    let der = p12.to_der()?;
    println!("PKCS#12 bundle: {} bytes", der.len());

    // ── Parse it back ─────────────────────────────────────────────────────────

    let loaded = Pkcs12::from_der(&der)?;
    let (recovered_key, recovered_cert, ca_chain) = loaded.parse(password)?;

    println!(
        "Recovered key algorithm: Ed25519 = {}",
        recovered_key.is_a(c"ED25519")
    );
    if let Some(subject) = recovered_cert.subject_name().to_string() {
        println!("Recovered cert subject:  {subject}");
    }
    println!("CA chain length: {}", ca_chain.len());

    // Public keys must match.
    assert!(priv_key.public_eq(&recovered_key));
    assert_eq!(cert.to_der()?, recovered_cert.to_der()?);
    println!("Key and certificate match original: OK");

    // ── DER round-trip ────────────────────────────────────────────────────────

    let der2 = loaded.to_der()?;
    assert_eq!(der, der2);
    println!("DER round-trip: OK");

    Ok(())
}

pub fn public_eq<U: HasPublic>(&self, other: &Pkey<U>) -> bool

where T: HasPublic,

Return true if this key’s public component equals other’s.

Wraps EVP_PKEY_eq. Useful for verifying that a certificate’s public key matches a private key before using them together.

Examples found in repository

examples/pkcs12.rs (line 52)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── Generate key and self-signed certificate ───────────────────────────────

    let mut kgen = KeygenCtx::new(c"ED25519")?;
    let priv_key = kgen.generate()?;
    let pub_key = native_ossl::pkey::Pkey::<native_ossl::pkey::Public>::from(priv_key.clone());

    let mut name = X509NameOwned::new()?;
    name.add_entry_by_txt(c"CN", b"example.com")?;

    let cert = X509Builder::new()?
        .set_version(2)?
        .set_serial_number(1)?
        .set_not_before_offset(0)?
        .set_not_after_offset(365 * 86400)?
        .set_subject_name(&name)?
        .set_issuer_name(&name)?
        .set_public_key(&pub_key)?
        .sign(&priv_key, None)?
        .build();

    // ── Create the PKCS#12 bundle ─────────────────────────────────────────────

    let password = "correct horse battery staple";
    let p12 = Pkcs12::create(password, "example.com", &priv_key, &cert, &[])?;
    let der = p12.to_der()?;
    println!("PKCS#12 bundle: {} bytes", der.len());

    // ── Parse it back ─────────────────────────────────────────────────────────

    let loaded = Pkcs12::from_der(&der)?;
    let (recovered_key, recovered_cert, ca_chain) = loaded.parse(password)?;

    println!(
        "Recovered key algorithm: Ed25519 = {}",
        recovered_key.is_a(c"ED25519")
    );
    if let Some(subject) = recovered_cert.subject_name().to_string() {
        println!("Recovered cert subject:  {subject}");
    }
    println!("CA chain length: {}", ca_chain.len());

    // Public keys must match.
    assert!(priv_key.public_eq(&recovered_key));
    assert_eq!(cert.to_der()?, recovered_cert.to_der()?);
    println!("Key and certificate match original: OK");

    // ── DER round-trip ────────────────────────────────────────────────────────

    let der2 = loaded.to_der()?;
    assert_eq!(der, der2);
    println!("DER round-trip: OK");

    Ok(())
}

pub fn get_params(&self, params: &mut Params<'_>) -> Result<(), ErrorStack>

Fill the values for a pre-prepared mutable Params query array.

Wraps EVP_PKEY_get_params. The array must already contain the keys of interest with null data pointers; OpenSSL writes the values in place.

Errors

pub fn public_key_to_der(&self) -> Result<Vec<u8>, ErrorStack>

where T: HasPublic,

DER-encode the public key (SubjectPublicKeyInfo format).

Zero-copy: writes directly into a caller-owned Vec<u8> — no OpenSSL heap allocation occurs.

Errors

Returns Err if serialisation fails.

impl Pkey<Private>

pub fn from_pem(pem: &[u8]) -> Result<Self, ErrorStack>

Load a private key from PEM bytes.

Pass passphrase = Some(cb) for encrypted PEM; None for unencrypted.

Errors

pub fn to_pem(&self) -> Result<Vec<u8>, ErrorStack>

Serialise the private key to PEM (PKCS#8 BEGIN PRIVATE KEY).

Errors

pub fn from_pem_in(ctx: &Arc<LibCtx>, pem: &[u8]) -> Result<Self, ErrorStack>

Load a private key from PEM bytes within a specific library context.

Uses PEM_read_bio_PrivateKey_ex so the key’s internal algorithm fetch uses ctx’s provider set. Necessary when the private key is later used for EVP operations inside an isolated (e.g. FIPS) context.

Errors

pub fn from_der(der: &[u8]) -> Result<Self, ErrorStack>

Load a private key from DER bytes (auto-detecting PKCS#8 / traditional).

Zero-copy: the EVP_PKEY is decoded from the caller’s slice without copying.

Errors

pub fn from_pem_passphrase( pem: &[u8], passphrase: &[u8], ) -> Result<Self, ErrorStack>

Load a private key from passphrase-encrypted PEM.

Passes passphrase directly to PEM_read_bio_PrivateKey via a pem_password_cb. Returns Err if the key cannot be decrypted or the PEM is malformed. For unencrypted PEM use from_pem.

Errors

pub fn to_pem_encrypted( &self, cipher: &CipherAlg, passphrase: &[u8], ) -> Result<Vec<u8>, ErrorStack>

Serialise the private key as passphrase-encrypted PKCS#8 PEM (BEGIN ENCRYPTED PRIVATE KEY).

cipher controls the wrapping algorithm (e.g. CipherAlg::fetch(c"AES-256-CBC", None)). The passphrase is passed directly to OpenSSL via kstr/klen.

Panics

Panics if passphrase is longer than i32::MAX bytes.

Errors

pub fn to_pkcs8_der(&self) -> Result<Vec<u8>, ErrorStack>

Serialise the private key as unencrypted PKCS#8 DER (PrivateKeyInfo / OneAsymmetricKey, RFC 5958).

Equivalent to writing unencrypted PEM and stripping the base64 wrapper, but avoids the encode/decode round-trip. To encrypt the output, use to_pem_encrypted instead.

Errors

impl Pkey<Public>

pub fn from_pem(pem: &[u8]) -> Result<Self, ErrorStack>

Load a public key from PEM (SubjectPublicKeyInfo or RSA public key).

Errors

pub fn from_pem_in(ctx: &Arc<LibCtx>, pem: &[u8]) -> Result<Self, ErrorStack>

Load a public key from PEM bytes within a specific library context.

Uses PEM_read_bio_PUBKEY_ex so the key’s internal algorithm fetch uses ctx’s provider set. Necessary when the public key is later used for EVP operations inside an isolated (e.g. FIPS) context.

Errors

pub fn from_der(der: &[u8]) -> Result<Self, ErrorStack>

Load a public key from DER (SubjectPublicKeyInfo).

Errors

pub fn to_pem(&self) -> Result<Vec<u8>, ErrorStack>

Serialise the public key to PEM.

Errors

impl Pkey<Private>

pub fn from_params( ctx: Option<&Arc<LibCtx>>, pkey_type: &CStr, params: &Params<'_>, ) -> Result<Self, ErrorStack>

Import a private key pair from an OSSL_PARAM array.

Equivalent to EVP_PKEY_fromdata with EVP_PKEY_KEYPAIR selection. Pass ctx = None to use the global default library context.

Errors

pub fn export(&self) -> Result<Params<'static>, ErrorStack>

Export all key parameters (private + public) as an owned OSSL_PARAM array.

Uses EVP_PKEY_KEYPAIR selection so both private and public material are included in the returned array.

Errors

impl Pkey<Public>

pub fn from_params( ctx: Option<&Arc<LibCtx>>, pkey_type: &CStr, params: &Params<'_>, ) -> Result<Self, ErrorStack>

Import a public key from an OSSL_PARAM array.

Equivalent to EVP_PKEY_fromdata with EVP_PKEY_PUBLIC_KEY selection. Pass ctx = None to use the global default library context.

Errors

pub fn export(&self) -> Result<Params<'static>, ErrorStack>

Export the public key parameters as an owned OSSL_PARAM array.

Uses EVP_PKEY_PUBLIC_KEY selection.

Errors

Trait Implementations

impl<T> Clone for Pkey<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Drop for Pkey<T>

fn drop(&mut self)

Executes the destructor for this type.

impl From<Pkey<Private>> for Pkey<Public>

fn from(k: Pkey<Private>) -> Self

Converts to this type from the input type.

impl<T> Send for Pkey<T>

impl<T> Sync for Pkey<T>