pkcs8/
lib.rs

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

pkcs8/
lib.rs
