pkcs8: initial EncryptedPrivateKeyInfo support (#262)

Adds support for parsing PKCS#8 `EncryptedPrivateKeyInfo`.

Includes tests with DER and PEM-encoded encrypted private keys, using
semi-modern PKCS#5 v2 encryption algorithms (AES-CBC and HMAC-SHA-256).

Does not actually implement support for decrypting/encrypting private
keys, nor does it add a `document` type for heap-backed storage.
This is all punted on for now to add an initial type.

The plan is to open tracking issues for adding support, deciding on
which encryption algorithms we want to support, and then following up on
actual support in subsequent PRs, most likely after the next `cipher`
release.

Making all of this work required making the `parameters` field of
`spki::AlgorithmIdentifier` a bona fide `Any` type as the parameters for
encrypted keys include things like a salt/nonce.

Author: tarcieri

der/src/asn1/any.rs

@@ -47,11 +47,16 @@ impl<'a> Any<'a> {
         self.value.len()
     }
 
-    /// Is the value of this [`Any`] type empty?
+    /// Is the body of this [`Any`] type empty?
     pub fn is_empty(self) -> bool {
         self.value.is_empty()
     }
 
+    /// Is this value an ASN.1 NULL value?
+    pub fn is_null(self) -> bool {
+        Null::try_from(self).is_ok()
+    }
+
     /// Get the raw value for this [`Any`] type as a byte slice.
     pub fn as_bytes(self) -> &'a [u8] {
         self.value.as_bytes()
@@ -68,6 +73,7 @@ impl<'a> Any<'a> {
     }
 
     /// Attempt to decode an ASN.1 `NULL` value.
+    #[deprecated(since = "0.2.4", note = "Please use the `is_null` function instead")]
     pub fn null(self) -> Result<Null> {
         self.try_into()
     }

der/src/error.rs

@@ -71,7 +71,7 @@ impl From<ErrorKind> for Error {
     }
 }
 
-impl From<core::convert::Infallible> for Error {
+impl From<Infallible> for Error {
     fn from(_: Infallible) -> Error {
         unreachable!()
     }

der/src/lib.rs

@@ -315,7 +315,7 @@
     html_root_url = "https://docs.rs/der/0.2.3"
 )]
 #![forbid(unsafe_code)]
-#![warn(missing_docs, rust_2018_idioms)]
+#![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
 
 #[cfg(feature = "alloc")]
 extern crate alloc;

pkcs8/src/document.rs

@@ -16,7 +16,7 @@ use std::{fs, path::Path, str};
 #[cfg(feature = "pem")]
 use {crate::pem, alloc::string::String, core::str::FromStr};
 
-/// PKCS#8 private key document
+/// PKCS#8 private key document.
 ///
 /// This type provides storage for a PKCS#8 private key encoded as ASN.1 DER
 /// with the invariant that the contained-document is "well-formed", i.e. it
@@ -155,7 +155,7 @@ impl FromStr for PrivateKeyDocument {
     }
 }
 
-/// SPKI public key document
+/// SPKI public key document.
 ///
 /// This type provides storage for a SPKI public key encoded as ASN.1 DER with
 /// the invariant that the contained-document is "well-formed", i.e. it will

pkcs8/src/lib.rs

@@ -2,7 +2,6 @@
 //! Private-Key Information Syntax Specification (as defined in [RFC 5208]).
 //!
 //! # About
-//!
 //! This is a minimalistic library targeting `no_std` platforms and small code
 //! size. It supports decoding/encoding of the following types without the use
 //! of a heap:
@@ -21,7 +20,6 @@
 //! documents from "PEM encoding" format as defined in RFC 7468.
 //!
 //! # Supported Algorithms
-//!
 //! This crate has been tested against keys generated by OpenSSL for the
 //! following algorithms:
 //!
@@ -32,7 +30,11 @@
 //! It may work with other algorithms which use an optional OID for
 //! [`AlgorithmIdentifier`] parameters.
 //!
-//! Encrypted private keys are presently unsupported.
+//! # Encrypted Private Key Support
+//! [`EncryptedPrivateKeyInfo`] supports decoding/encoding encrypted PKCS#8
+//! private keys.
+//!
+//! However, support for actually decrypting/encrypting them remains TBD.
 //!
 //! # Minimum Supported Rust Version
 //!
@@ -68,11 +70,11 @@ mod pem;
 
 pub use crate::{
     error::{Error, Result},
-    private_key_info::PrivateKeyInfo,
+    private_key_info::{encrypted::EncryptedPrivateKeyInfo, PrivateKeyInfo},
     traits::{FromPrivateKey, FromPublicKey},
 };
 pub use der::{self, ObjectIdentifier};
-pub use spki::{AlgorithmIdentifier, AlgorithmParameters, SubjectPublicKeyInfo};
+pub use spki::{AlgorithmIdentifier, SubjectPublicKeyInfo};
 
 #[cfg(feature = "alloc")]
 pub use crate::{

pkcs8/src/private_key_info.rs

@@ -1,5 +1,7 @@
 //! PKCS#8 `PrivateKeyInfo`.
 
+pub(crate) mod encrypted;
+
 use crate::{AlgorithmIdentifier, Error, Result};
 use core::{convert::TryFrom, fmt};
 use der::{Decodable, Encodable, Message};
@@ -16,13 +18,12 @@ use {crate::pem, zeroize::Zeroizing};
 /// RFC 5208 designates `0` as the only valid version for PKCS#8 documents
 const VERSION: u8 = 0;
 
-/// PKCS#8 `PrivateKeyInfo`
+/// PKCS#8 `PrivateKeyInfo`.
 ///
 /// ASN.1 structure containing an [`AlgorithmIdentifier`] and private key
 /// data in an algorithm specific format.
 ///
-/// Described in RFC 5208 Section 5:
-/// <https://tools.ietf.org/html/rfc5208#section-5>
+/// Described in [RFC 5208 Section 5]:
 ///
 /// ```text
 /// PrivateKeyInfo ::= SEQUENCE {
@@ -39,13 +40,18 @@ const VERSION: u8 = 0;
 ///
 /// Attributes ::= SET OF Attribute
 /// ```
-#[derive(Copy, Clone)]
+///
+/// [RFC 5208 Section 5]: https://tools.ietf.org/html/rfc5208#section-5
+#[derive(Clone)]
 pub struct PrivateKeyInfo<'a> {
-    /// X.509 [`AlgorithmIdentifier`]
-    pub algorithm: AlgorithmIdentifier,
+    /// X.509 [`AlgorithmIdentifier`] for the private key type
+    pub algorithm: AlgorithmIdentifier<'a>,
 
     /// Private key data
     pub private_key: &'a [u8],
+    // TODO(tarcieri): support for `Attributes` (are they used in practice?)
+    // PKCS#9 describes the possible attributes: https://tools.ietf.org/html/rfc2985
+    // Workaround for stripping attributes: https://stackoverflow.com/a/48039151
 }
 
 impl<'a> PrivateKeyInfo<'a> {

pkcs8/src/private_key_info/encrypted.rs

@@ -0,0 +1,83 @@
+//! PKCS#8 `EncryptedPrivateKeyInfo`
+
+use crate::{AlgorithmIdentifier, Error, Result};
+use core::convert::TryFrom;
+use der::{Decodable, Encodable, Message};
+
+/// PKCS#8 `EncryptedPrivateKeyInfo`.
+///
+/// ASN.1 structure containing an [`AlgorithmIdentifier`] identifying a
+/// symmetric encryption scheme and encrypted private key data.
+///
+/// ## Encryption algorithm support
+///
+/// tl;dr: none yet!
+///
+/// This crate does not (yet) support decrypting/encrypting private key data.
+///
+/// [PKCS#5 v1.5] supports several password-based encryption algorithms,
+/// including `PBE-SHA1-3DES`.
+///
+/// [PKCS#5 v2] adds support for AES encryption with iterated PRFs
+/// such as `hmacWithSHA256`.
+///
+/// We may consider adding support for these in future releases of this crate.
+///
+/// ## Schema
+/// Structure described in [RFC 5208 Section 6]:
+///
+/// ```text
+/// EncryptedPrivateKeyInfo ::= SEQUENCE {
+///   encryptionAlgorithm  EncryptionAlgorithmIdentifier,
+///   encryptedData        EncryptedData }
+///
+/// EncryptionAlgorithmIdentifier ::= AlgorithmIdentifier
+///
+/// EncryptedData ::= OCTET STRING
+/// ```
+///
+/// [RFC 5208 Section 6]: https://tools.ietf.org/html/rfc5208#section-6
+/// [PKCS#5 v1.5]: https://tools.ietf.org/html/rfc2898
+/// [PKCS#5 v2]: https://tools.ietf.org/html/rfc8018
+#[derive(Copy, Clone)]
+pub struct EncryptedPrivateKeyInfo<'a> {
+    /// [`AlgorithmIdentifier`] for the symmetric encryption algorithm used to
+    /// encrypt the `encrypted_data` field.
+    pub encryption_algorithm: AlgorithmIdentifier<'a>,
+
+    /// Private key data
+    pub encrypted_data: &'a [u8],
+}
+
+impl<'a> TryFrom<&'a [u8]> for EncryptedPrivateKeyInfo<'a> {
+    type Error = Error;
+
+    fn try_from(bytes: &'a [u8]) -> Result<Self> {
+        Ok(Self::from_bytes(bytes)?)
+    }
+}
+
+impl<'a> TryFrom<der::Any<'a>> for EncryptedPrivateKeyInfo<'a> {
+    type Error = der::Error;
+
+    fn try_from(any: der::Any<'a>) -> der::Result<EncryptedPrivateKeyInfo<'a>> {
+        any.sequence(|decoder| {
+            Ok(Self {
+                encryption_algorithm: decoder.decode()?,
+                encrypted_data: decoder.octet_string()?.as_bytes(),
+            })
+        })
+    }
+}
+
+impl<'a> Message<'a> for EncryptedPrivateKeyInfo<'a> {
+    fn fields<F, T>(&self, f: F) -> der::Result<T>
+    where
+        F: FnOnce(&[&dyn Encodable]) -> der::Result<T>,
+    {
+        f(&[
+            &self.encryption_algorithm,
+            &der::OctetString::new(self.encrypted_data)?,
+        ])
+    }
+}

pkcs8/tests/encrypted_private_key.rs

@@ -0,0 +1,48 @@
+//! Encrypted PKCS#8 private key tests.
+
+use core::convert::TryFrom;
+use hex_literal::hex;
+use pkcs8::EncryptedPrivateKeyInfo;
+
+/// Ed25519 PKCS#8 encrypted private key encoded as ASN.1 DER.
+///
+/// Generated using:
+///
+/// ```
+/// $ openssl pkcs8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -topk8 -inform der -in ed25519-priv.der -outform der -out ed25519-priv-enc-v2.der
+/// ```
+const ED25519_DER_EXAMPLE: &[u8] = include_bytes!("examples/ed25519-priv-enc-v2.der");
+
+/// Ed25519 PKCS#8 encrypted private key encoded as PEM.
+///
+/// Generated using:
+///
+/// ```
+/// $ openssl pkcs8 -v2 aes-256-cbc -v2prf hmacWithSHA256 -topk8 -in ed25519-priv.pem -out ed25519-priv-enc-v2.pem
+/// ```
+#[cfg(feature = "pem")]
+#[allow(dead_code)] // TODO(tarcieri): support for PEM-encoded `EncryptedPrivateKeyInfo`
+const ED25519_PEM_EXAMPLE: &str = include_str!("examples/ed25519-priv-enc-v2.pem");
+
+/// Password used to encrypt the keys.
+#[allow(dead_code)] // TODO(tarcieri): decryption support
+const PASSWORD: &[u8] = b"hunter42"; // Bad password; don't actually use outside tests!
+
+#[test]
+fn parse_ed25519_der_encrypted() {
+    let pk = EncryptedPrivateKeyInfo::try_from(ED25519_DER_EXAMPLE).unwrap();
+
+    assert_eq!(
+        pk.encryption_algorithm.oid,
+        "1.2.840.113549.1.5.13".parse().unwrap()
+    ); // PBES2
+
+    // TODO(tarcieri): parse/extract params
+
+    // Extracted with:
+    // $  openssl asn1parse -in tests/examples/ed25519-priv-enc-v2.der -inform der
+    assert_eq!(
+        pk.encrypted_data,
+        &hex!("D0CD6C770F4BB87176422305C17401809E226674CE74185D221BFDAA95069890C8882FCE02B05D41BCBF54B035595BCD4154B32593708469B86AACF8815A7B2B")
+    );
+}

pkcs8/tests/examples/ed25519-priv-enc-v2.der

@@ -0,0 +1,6 @@
+-----BEGIN ENCRYPTED PRIVATE KEY-----
+MIGbMFcGCSqGSIb3DQEFDTBKMCkGCSqGSIb3DQEFDDAcBAjCBvGI26s6nAICCAAw
+DAYIKoZIhvcNAgkFADAdBglghkgBZQMEASoEENob0oKOl/afgIhlBz+LijQEQGCN
+nJgmF4dhcJj8u9lsTX3NFR5i29Mqhc9ku/tDpP5PgOi57xIL6X+wdCCdyvJ5hhDy
+2zTzE5+kJ7Plewa+4tI=
+-----END ENCRYPTED PRIVATE KEY-----