pkcs8 - Rust (2024)

RustCrypto: PKCS#8 (Private Keys)

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 pairsof private and public keys.

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

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

PKCS#8 private keys can optionally be encrypted under a password usingkey derivation algorithms like PBKDF2 and scrypt, and encrypted withciphers 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 ofenabling PKCS#8 support for any algorithm.

That said, it has been tested for interoperability against keys generated byOpenSSL 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 particularalgorithm, including the ones listed above or other algorithms.

Minimum Supported Rust Version

This crate requires Rust 1.65 at a minimum.

We may change the MSRV in the future, but it will be accompanied by a minorversion bump.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT license

at your option.

Contribution

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

About this crate

This library provides generalized PKCS#8 support designed to work with anumber of different algorithms. It supports no_std platforms includingones 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/encodingdocuments from “PEM encoding” format as defined in RFC 7468.

Encrypted Private Key Support

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

When the encryption feature of this crate is enabled, it providesEncryptedPrivateKeyInfo::decrypt and PrivateKeyInfo::encryptfunctions which are able to decrypt/encrypt keys using the followingalgorithms:

• PKCS#5v2 Password Based Encryption Scheme 2 (RFC 8018)
  • Key derivation functions:
    • scrypt (RFC 7914)
    • PBKDF2 (RFC 8018)
      • SHA-2 based PRF with HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, or HMAC-SHA512
      • SHA-1 based PRF with HMAC-SHA1, when the sha1 feature of this crate is enabled.
  • Symmetric encryption: AES-128-CBC, AES-192-CBC, or AES-256-CBC(best available options for PKCS#5v2)

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

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

⚠️ WARNING ⚠️

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

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

New keys should use AES instead.