Struct KeyPair

pub struct KeyPair { /* private fields */ }

A key pair used to sign certificates and CSRs

Note that ring, the underlying library to handle RSA keys requires them to be in a special format, meaning that openssl genrsa doesn’t work. See ring’s documentation for how to generate RSA keys in the wanted format and conversion between the formats.

Implementations

impl KeyPair

pub fn generate() -> Result<KeyPair, Error>

Generate a new random PKCS_ECDSA_P256_SHA256 key pair

pub fn generate_for(alg: &'static SignatureAlgorithm) -> Result<KeyPair, Error>

Generate a new random key pair for the specified signature algorithm

If you’re not sure which algorithm to use, PKCS_ECDSA_P256_SHA256 is a good choice. If passed an RSA signature algorithm, it depends on the backend whether we return a generated key or an error for key generation being unavailable. Currently, only aws-lc-rs supports RSA key generation.

pub fn algorithm(&self) -> &'static SignatureAlgorithm

Returns the key pair’s signature algorithm

pub fn from_pem(pem_str: &str) -> Result<KeyPair, Error>

Parses the key pair from the ASCII PEM format

If aws_lc_rs feature is used, then the key must be a DER-encoded plaintext private key; as specified in PKCS #8/RFC 5958, SEC1/RFC 5915, or PKCS#1/RFC 3447; Appears as “PRIVATE KEY”, “RSA PRIVATE KEY”, or “EC PRIVATE KEY” in PEM files.

Otherwise if the ring feature is used, then the key must be a DER-encoded plaintext private key; as specified in PKCS #8/RFC 5958; Appears as “PRIVATE KEY” in PEM files.

pub fn from_remote( key_pair: Box<dyn RemoteKeyPair + Sync + Send>, ) -> Result<KeyPair, Error>

Obtains the key pair from a raw public key and a remote private key

pub fn from_pkcs8_pem_and_sign_algo( pem_str: &str, alg: &'static SignatureAlgorithm, ) -> Result<KeyPair, Error>

Obtains the key pair from a DER formatted key using the specified SignatureAlgorithm

The key must be a DER-encoded plaintext private key; as specified in PKCS #8/RFC 5958;

Appears as “PRIVATE KEY” in PEM files Same as from_pkcs8_pem_and_sign_algo.

pub fn from_pkcs8_der_and_sign_algo( pkcs8: &PrivatePkcs8KeyDer<'_>, alg: &'static SignatureAlgorithm, ) -> Result<KeyPair, Error>

Obtains the key pair from a DER formatted key using the specified SignatureAlgorithm

If you have a PrivatePkcs8KeyDer, you can usually rely on the TryFrom implementation to obtain a KeyPair – it will determine the correct SignatureAlgorithm for you. However, sometimes multiple signature algorithms fit for the same DER key. In those instances, you can use this function to precisely specify the SignatureAlgorithm.

rustls_pemfile::private_key() is often used to obtain a PrivateKeyDer from PEM input. If the obtained PrivateKeyDer is a Pkcs8 variant, you can use its contents as input for this function. Alternatively, if you already have a byte slice containing DER, it can trivially be converted into PrivatePkcs8KeyDer using the Into trait.

pub fn from_pem_and_sign_algo( pem_str: &str, alg: &'static SignatureAlgorithm, ) -> Result<KeyPair, Error>

Obtains the key pair from a PEM formatted key using the specified SignatureAlgorithm

If aws_lc_rs feature is used, then the key must be a DER-encoded plaintext private key; as specified in PKCS #8/RFC 5958, SEC1/RFC 5915, or PKCS#1/RFC 3447; Appears as “PRIVATE KEY”, “RSA PRIVATE KEY”, or “EC PRIVATE KEY” in PEM files.

Otherwise if the ring feature is used, then the key must be a DER-encoded plaintext private key; as specified in PKCS #8/RFC 5958; Appears as “PRIVATE KEY” in PEM files.

Same as from_pem_and_sign_algo.

pub fn from_der_and_sign_algo( key: &PrivateKeyDer<'_>, alg: &'static SignatureAlgorithm, ) -> Result<KeyPair, Error>

Obtains the key pair from a DER formatted key using the specified SignatureAlgorithm

Note that using the ring feature, this function only support PrivateKeyDer::Pkcs8 variant. Consider using the aws_lc_rs features to support PrivateKeyDer fully.

If you have a PrivateKeyDer, you can usually rely on the TryFrom implementation to obtain a KeyPair – it will determine the correct SignatureAlgorithm for you. However, sometimes multiple signature algorithms fit for the same DER key. In those instances, you can use this function to precisely specify the SignatureAlgorithm.

You can use rustls_pemfile::private_key to get the key input. If you have already a byte slice, just calling try_into() will convert it to a PrivateKeyDer.

pub fn public_key_raw(&self) -> &[u8]

Get the raw public key of this key pair

The key is in raw format, as how [ring::signature::KeyPair::public_key] would output, and how [ring::signature::UnparsedPublicKey::verify] would accept.

pub fn is_compatible(&self, signature_algorithm: &SignatureAlgorithm) -> bool

Check if this key pair can be used with the given signature algorithm

pub fn compatible_algs( &self, ) -> impl Iterator<Item = &'static SignatureAlgorithm>

Returns (possibly multiple) compatible SignatureAlgorithm’s that the key can be used with

pub fn public_key_der(&self) -> Vec<u8>

Return the key pair’s public key in DER format

The key is formatted according to the SubjectPublicKeyInfo struct of X.509. See RFC 5280 section 4.1.

pub fn public_key_pem(&self) -> String

Return the key pair’s public key in PEM format

The returned string can be interpreted with openssl pkey --inform PEM -pubout -pubin -text

pub fn serialize_der(&self) -> Vec<u8>

Serializes the key pair (including the private key) in PKCS#8 format in DER

Panics if called on a remote key pair.

pub fn serialized_der(&self) -> &[u8]

Returns a reference to the serialized key pair (including the private key) in PKCS#8 format in DER

Panics if called on a remote key pair.

pub fn as_remote(&self) -> Option<&(dyn RemoteKeyPair + Sync + Send)>

Access the remote key pair if it is a remote one

pub fn serialize_pem(&self) -> String

Serializes the key pair (including the private key) in PKCS#8 format in PEM

Trait Implementations

impl Debug for KeyPair

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl TryFrom<&[u8]> for KeyPair

type Error = Error

The type returned in the event of a conversion error.

fn try_from(key: &[u8]) -> Result<KeyPair, Error>

Performs the conversion.

impl TryFrom<&PrivateKeyDer<'_>> for KeyPair

type Error = Error

The type returned in the event of a conversion error.

fn try_from(key: &PrivateKeyDer<'_>) -> Result<KeyPair, Error>

Performs the conversion.

impl TryFrom<&PrivatePkcs8KeyDer<'_>> for KeyPair

type Error = Error

The type returned in the event of a conversion error.

fn try_from(key: &PrivatePkcs8KeyDer<'_>) -> Result<KeyPair, Error>

Performs the conversion.

impl TryFrom<Vec<u8>> for KeyPair

type Error = Error

The type returned in the event of a conversion error.

fn try_from(key: Vec<u8>) -> Result<KeyPair, Error>

Performs the conversion.