1 //! Pure Rust implementation of Public-Key Cryptography Standards (PKCS) #8: 2 //! Private-Key Information Syntax Specification ([RFC 5208]), with additional 3 //! support for PKCS#8v2 asymmetric key packages ([RFC 5958]) 4 //! 5 //! # About 6 //! This library provides generalized PKCS#8 support designed to work with a 7 //! number of different algorithms. It supports `no_std` platforms including 8 //! ones without a heap (albeit with reduced functionality). 9 //! 10 //! It supports decoding/encoding the following types: 11 //! 12 //! - [`EncryptedPrivateKeyInfo`]: (with `pkcs5` feature) encrypted key. 13 //! - [`PrivateKeyInfo`]: algorithm identifier and data representing a private key. 14 //! Optionally also includes public key data for asymmetric keys. 15 //! - [`SubjectPublicKeyInfo`]: algorithm identifier and data representing a public key 16 //! (re-exported from the [`spki`] crate) 17 //! 18 //! When the `alloc` feature is enabled, the following additional types are 19 //! available which provide more convenient decoding/encoding support: 20 //! 21 //! - [`EncryptedPrivateKeyDocument`]: (with `pkcs5` feature) heap-backed encrypted key. 22 //! - [`PrivateKeyDocument`]: heap-backed storage for serialized [`PrivateKeyInfo`]. 23 //! - [`PublicKeyDocument`]: heap-backed storage for serialized [`SubjectPublicKeyInfo`]. 24 //! 25 //! When the `pem` feature is enabled, it also supports decoding/encoding 26 //! documents from "PEM encoding" format as defined in RFC 7468. 27 //! 28 //! # Supported Algorithms 29 //! This crate has been written generically so it can be used to implement 30 //! PKCS#8 support for any algorithm. 31 //! 32 //! However, it's only tested against keys generated by OpenSSL for the 33 //! following algorithms: 34 //! 35 //! - ECC (`id-ecPublicKey`) 36 //! - Ed25519 (`Ed25519`) 37 //! - RSA (`rsaEncryption`) 38 //! 39 //! Please open an issue if you encounter trouble using it with other 40 //! algorithms. 41 //! 42 //! # Encrypted Private Key Support 43 //! [`EncryptedPrivateKeyInfo`] supports decoding/encoding encrypted PKCS#8 44 //! private keys and is gated under the `pkcs5` feature. The corresponding 45 //! [`EncryptedPrivateKeyDocument`] type provides heap-backed storage 46 //! (`alloc` feature required). 47 //! 48 //! When the `encryption` feature of this crate is enabled, it provides 49 //! [`EncryptedPrivateKeyInfo::decrypt`] and [`PrivateKeyInfo::encrypt`] 50 //! functions which are able to decrypt/encrypt keys using the following 51 //! algorithms: 52 //! 53 //! - [PKCS#5v2 Password Based Encryption Scheme 2 (RFC 8018)] 54 //! - Key derivation function: [scrypt] ([RFC 7914], also supports PBKDF2-HMAC-SHA256) 55 //! - Symmetric encryption: AES-128-CBC or AES-256-CBC (best available options for PKCS#5v2) 56 //! 57 //! # PKCS#1 support (optional) 58 //! When the `pkcs1` feature of this crate is enabled, this crate provides 59 //! a blanket impl of PKCS#8 support for types which impl the traits from the 60 //! [`pkcs1`] crate (e.g. `FromRsaPrivateKey`, `ToRsaPrivateKey`). 61 //! 62 //! # Minimum Supported Rust Version 63 //! 64 //! This crate requires **Rust 1.51** at a minimum. 65 //! 66 //! [RFC 5208]: https://tools.ietf.org/html/rfc5208 67 //! [RFC 5958]: https://tools.ietf.org/html/rfc5958 68 //! [RFC 7914]: https://datatracker.ietf.org/doc/html/rfc7914 69 //! [PKCS#5v2 Password Based Encryption Scheme 2 (RFC 8018)]: https://tools.ietf.org/html/rfc8018#section-6.2 70 //! [scrypt]: https://en.wikipedia.org/wiki/Scrypt 71 72 #![no_std] 73 #![cfg_attr(docsrs, feature(doc_cfg))] 74 #![doc( 75 html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg", 76 html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg", 77 html_root_url = "https://docs.rs/pkcs8/0.7.5" 78 )] 79 #![forbid(unsafe_code, clippy::unwrap_used)] 80 #![warn(missing_docs, rust_2018_idioms, unused_qualifications)] 81 82 #[cfg(feature = "alloc")] 83 extern crate alloc; 84 #[cfg(feature = "std")] 85 extern crate std; 86 87 mod attributes; 88 mod error; 89 mod private_key_info; 90 mod traits; 91 mod version; 92 93 #[cfg(feature = "alloc")] 94 mod document; 95 96 #[cfg(feature = "pkcs5")] 97 pub(crate) mod encrypted_private_key_info; 98 99 pub use crate::{ 100 attributes::Attributes, 101 error::{Error, Result}, 102 private_key_info::PrivateKeyInfo, 103 traits::{FromPrivateKey, FromPublicKey}, 104 version::Version, 105 }; 106 pub use der::{self, asn1::ObjectIdentifier}; 107 pub use spki::{AlgorithmIdentifier, SubjectPublicKeyInfo}; 108 109 #[cfg(feature = "alloc")] 110 pub use crate::{ 111 document::{private_key::PrivateKeyDocument, public_key::PublicKeyDocument}, 112 traits::{ToPrivateKey, ToPublicKey}, 113 }; 114 115 #[cfg(feature = "pem")] 116 #[cfg_attr(docsrs, doc(cfg(feature = "pem")))] 117 pub use pem_rfc7468::LineEnding; 118 119 #[cfg(feature = "pkcs5")] 120 pub use encrypted_private_key_info::EncryptedPrivateKeyInfo; 121 122 #[cfg(feature = "pkcs1")] 123 pub use pkcs1; 124 125 #[cfg(feature = "pkcs5")] 126 pub use pkcs5; 127 128 #[cfg(all(feature = "alloc", feature = "pkcs5"))] 129 pub use crate::document::encrypted_private_key::EncryptedPrivateKeyDocument; 130 131 #[cfg(feature = "pem")] 132 use pem_rfc7468 as pem; 133
