Skip to main content

Crate pkcs8

Crate pkcs8 

Source
Expand description

§RustCrypto: PKCS#8 (Private Keys)

crate Docs Build Status Apache2/MIT licensed Rust Version Project Chat

Pure Rust implementation of Public-Key Cryptography Standards (PKCS) #8: Private-Key Information Syntax Specification (RFC 5208).

Documentation

§About PKCS#8

PKCS#8 is a format for cryptographic private keys, often containing pairs of private and public keys.

You can identify a PKCS#8 private key encoded as PEM (i.e. text) by the following:

-----BEGIN PRIVATE KEY-----

PKCS#8 private keys can optionally be encrypted under a password using key derivation algorithms like PBKDF2 and scrypt, and encrypted with ciphers like AES-CBC. When a PKCS#8 private key has been encrypted, it starts with the following:

-----BEGIN ENCRYPTED PRIVATE KEY-----

PKCS#8 private keys can also be serialized in an ASN.1-based binary format. The PEM text encoding is a Base64 representation of this format.

§Supported Algorithms

This crate is implemented in an algorithm-agnostic manner with the goal of enabling PKCS#8 support for any algorithm.

That said, it has been tested for interoperability against keys generated by OpenSSL for the following algorithms:

  • ECC (id-ecPublicKey)
  • Ed25519 (id-Ed25519)
  • RSA (id-rsaEncryption)
  • X25519 (id-X25519)

Please open an issue if you encounter trouble using it with a particular algorithm, including the ones listed above or other algorithms.

§Minimum Supported Rust Version (MSRV) Policy

MSRV increases are not considered breaking changes and can happen in patch releases.

The crate MSRV accounts for all supported targets and crate feature combinations, excluding explicitly unstable features.

§License

Licensed under either of:

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§About this crate

This library provides generalized PKCS#8 support designed to work with a number of different algorithms. It supports no_std platforms including ones without a heap (albeit with reduced functionality).

It supports decoding/encoding the following types:

  • [EncryptedPrivateKeyInfo]: (with pkcs5 feature) encrypted key.
  • PrivateKeyInfo: algorithm identifier and data representing a private key. Optionally also includes public key data for asymmetric keys.
  • SubjectPublicKeyInfo: algorithm identifier and data representing a public key (re-exported from the spki crate)

When the pem feature is enabled, it also supports decoding/encoding documents from “PEM encoding” format as defined in RFC 7468.

§Encrypted Private Key Support

[EncryptedPrivateKeyInfo] supports decoding/encoding encrypted PKCS#8 private keys and is gated under the pkcs5 feature.

When the encryption feature of this crate is enabled, it provides [EncryptedPrivateKeyInfo::decrypt] and [PrivateKeyInfo::encrypt] functions which are able to decrypt/encrypt keys using the following algorithms:

§Legacy DES-CBC and DES-EDE3-CBC (3DES) support (optional)

When the des-insecure and/or 3des features are enabled this crate provides support for private keys encrypted with DES-CBC and DES-EDE3-CBC (3DES or Triple DES) symmetric encryption, respectively.

Security Warning

DES support (gated behind the des-insecure feature) is implemented to allow for decryption of legacy PKCS#8 files only.

Such PKCS#8 documents should be considered INSECURE due to the short 56-bit key size of DES.

New keys should use AES instead.

Re-exports§

pub use der;
pub use spki;

Modules§

error 🔒
Error types
private_key_info 🔒
PKCS#8 PrivateKeyInfo.
traits 🔒
Traits for parsing objects from PKCS#8 encoded documents
version 🔒
PKCS#8 version identifier.

Structs§

Document
ASN.1 DER-encoded document.
ObjectIdentifier
Object identifier (OID).
PrivateKeyInfo
PKCS#8 PrivateKeyInfo.
SecretDocument
Secret Document type.
SubjectPublicKeyInfo
X.509 SubjectPublicKeyInfo (SPKI) as defined in RFC 5280 § 4.1.2.7.

Enums§

Error
Error type
KeyError
Key-related errors.
LineEnding
Line endings: variants of newline characters that can be used with Base64.
Version
Version identifier for PKCS#8 documents.

Traits§

AssociatedOid
A trait which associates an OID with a type.
DecodePrivateKey
Parse a private key object from a PKCS#8 encoded document.
DecodePublicKey
Parse a public key object from an encoded SPKI document.
EncodePrivateKey
Serialize a private key object to a PKCS#8 encoded document.
EncodePublicKey
Serialize a public key object to a SPKI-encoded document.

Type Aliases§

AlgorithmIdentifierRef
AlgorithmIdentifier reference which has AnyRef parameters.
PrivateKeyInfoOwned
PrivateKeyInfo with Any algorithm parameters, and Box<[u8]> key.
PrivateKeyInfoRef
PrivateKeyInfo with AnyRef algorithm parameters, and &[u8] key.
Result
Result type
SubjectPublicKeyInfoRef
SubjectPublicKeyInfo with AnyRef algorithm parameters, and BitStringRef params.