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

pkcs8/
lib.rs
