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