1 #![no_std] 2 #![cfg_attr(docsrs, feature(doc_cfg))] 3 #![doc = include_str!("../README.md")] 4 #![doc( 5 html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg", 6 html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo.svg", 7 html_root_url = "https://docs.rs/pkcs8/0.9.0-pre" 8 )] 9 #![forbid(unsafe_code, clippy::unwrap_used)] 10 #![warn(missing_docs, rust_2018_idioms, unused_qualifications)] 11 12 //! ## About this crate 13 //! This library provides generalized PKCS#8 support designed to work with a 14 //! number of different algorithms. It supports `no_std` platforms including 15 //! ones without a heap (albeit with reduced functionality). 16 //! 17 //! It supports decoding/encoding the following types: 18 //! 19 //! - [`EncryptedPrivateKeyInfo`]: (with `pkcs5` feature) encrypted key. 20 //! - [`PrivateKeyInfo`]: algorithm identifier and data representing a private key. 21 //! Optionally also includes public key data for asymmetric keys. 22 //! - [`SubjectPublicKeyInfo`]: algorithm identifier and data representing a public key 23 //! (re-exported from the [`spki`] crate) 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 //! ## Encrypted Private Key Support 29 //! [`EncryptedPrivateKeyInfo`] supports decoding/encoding encrypted PKCS#8 30 //! private keys and is gated under the `pkcs5` feature. 31 //! 32 //! When the `encryption` feature of this crate is enabled, it provides 33 //! [`EncryptedPrivateKeyInfo::decrypt`] and [`PrivateKeyInfo::encrypt`] 34 //! functions which are able to decrypt/encrypt keys using the following 35 //! algorithms: 36 //! 37 //! - [PKCS#5v2 Password Based Encryption Scheme 2 (RFC 8018)] 38 //! - Key derivation functions: 39 //! - [scrypt] ([RFC 7914]) 40 //! - PBKDF2 ([RFC 8018](https://datatracker.ietf.org/doc/html/rfc8018#section-5.2)) 41 //! - SHA-2 based PRF with HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, or HMAC-SHA512 42 //! - SHA-1 based PRF with HMAC-SHA1, when the `sha1` feature of this crate is enabled. 43 //! - Symmetric encryption: AES-128-CBC, AES-192-CBC, or AES-256-CBC 44 //! (best available options for PKCS#5v2) 45 //! 46 //! ## Legacy DES-CBC and DES-EDE3-CBC (3DES) support (optional) 47 //! When the `des-insecure` and/or `3des` features are enabled this crate provides support for 48 //! private keys encrypted with with DES-CBC and DES-EDE3-CBC (3DES or Triple DES) symmetric 49 //! encryption, respectively. 50 //! 51 //! ⚠️ WARNING ⚠️ 52 //! 53 //! DES support (gated behind the `des-insecure` feature) is implemented to 54 //! allow for decryption of legacy PKCS#8 files only. 55 //! 56 //! Such PKCS#8 documents should be considered *INSECURE* due to the short 57 //! 56-bit key size of DES. 58 //! 59 //! New keys should use AES instead. 60 //! 61 //! [RFC 5208]: https://tools.ietf.org/html/rfc5208 62 //! [RFC 5958]: https://tools.ietf.org/html/rfc5958 63 //! [RFC 7914]: https://datatracker.ietf.org/doc/html/rfc7914 64 //! [PKCS#5v2 Password Based Encryption Scheme 2 (RFC 8018)]: https://tools.ietf.org/html/rfc8018#section-6.2 65 //! [scrypt]: https://en.wikipedia.org/wiki/Scrypt 66 67 /// Local Android change: Use std to allow building as a dylib. 68 #[cfg(android_dylib)] 69 extern crate std; 70 71 #[cfg(feature = "pem")] 72 extern crate alloc; 73 #[cfg(feature = "std")] 74 extern crate std; 75 76 mod error; 77 mod private_key_info; 78 mod traits; 79 mod version; 80 81 #[cfg(feature = "pkcs5")] 82 pub(crate) mod encrypted_private_key_info; 83 84 pub use crate::{ 85 error::{Error, Result}, 86 private_key_info::PrivateKeyInfo, 87 traits::DecodePrivateKey, 88 version::Version, 89 }; 90 pub use der::{self, asn1::ObjectIdentifier, oid::AssociatedOid}; 91 pub use spki::{self, AlgorithmIdentifier, DecodePublicKey, SubjectPublicKeyInfo}; 92 93 #[cfg(feature = "alloc")] 94 pub use { 95 crate::traits::EncodePrivateKey, 96 der::{Document, SecretDocument}, 97 spki::EncodePublicKey, 98 }; 99 100 #[cfg(feature = "pem")] 101 #[cfg_attr(docsrs, doc(cfg(feature = "pem")))] 102 pub use der::pem::LineEnding; 103 104 #[cfg(feature = "pkcs5")] 105 pub use {encrypted_private_key_info::EncryptedPrivateKeyInfo, pkcs5}; 106 107 #[cfg(feature = "rand_core")] 108 pub use rand_core; 109
