pkcs8/
lib.rs

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")]
74extern crate alloc;
75#[cfg(feature = "std")]
76extern crate std;
77
78mod error;
79mod private_key_info;
80mod traits;
81mod version;
82
83#[cfg(feature = "pkcs5")]
84pub(crate) mod encrypted_private_key_info;
85
86pub use crate::{
87    error::{Error, Result},
88    private_key_info::PrivateKeyInfo,
89    traits::DecodePrivateKey,
90    version::Version,
91};
92pub use der::{self, asn1::ObjectIdentifier, oid::AssociatedOid};
93pub use spki::{
94    self, AlgorithmIdentifierRef, DecodePublicKey, SubjectPublicKeyInfo, SubjectPublicKeyInfoRef,
95};
96
97#[cfg(feature = "alloc")]
98pub use {
99    crate::traits::EncodePrivateKey,
100    der::{Document, SecretDocument},
101    spki::EncodePublicKey,
102};
103
104#[cfg(feature = "pem")]
105pub use der::pem::LineEnding;
106
107#[cfg(feature = "pkcs5")]
108pub use {encrypted_private_key_info::EncryptedPrivateKeyInfo, pkcs5};
109
110#[cfg(feature = "rand_core")]
111pub use rand_core;
pkcs8/lib.rs

pkcs8/
lib.rs
