pkcs8: encryption support (#302)

Following up on #293 which added PKCS#8 decryption support, this
adds the corresponding support for encrypting `PrivateKeyInfo` as
`EncryptedPrivateKeyInfo`.

It provides a simple API which generates a random salt and IV using a
provided `CryptoRng`, then uses PBES2 with PBKDF2-SHA256 and
AES-256-CBC.

It also provides a paramaterized `encrypt_with_params` which allows for
supplying a `pbes2::Parameters` structure.

Author: tarcieri

.github/workflows/pkcs5.yml

@@ -39,7 +39,9 @@ jobs:
           target: ${{ matrix.target }}
           override: true
       - run: cargo build --target ${{ matrix.target }} --release
+      - run: cargo build --target ${{ matrix.target }} --release --features alloc
       - run: cargo build --target ${{ matrix.target }} --release --features pbes2
+      - run: cargo build --target ${{ matrix.target }} --release --features alloc,pbes2
 
   test:
     runs-on: ubuntu-latest
@@ -56,4 +58,6 @@ jobs:
           toolchain: ${{ matrix.rust }}
           override: true
       - run: cargo test --release
+      - run: cargo test --release --features alloc
+      - run: cargo test --release --features pbes2
       - run: cargo test --release --all-features

Cargo.lock

@@ -27,6 +27,7 @@ sha2 = { version = "0.9", optional = true, default-features = false }
 hex-literal = "0.3"
 
 [features]
+alloc = []
 pbes2 = ["aes", "block-modes", "hmac", "pbkdf2", "sha2"]
 
 [package.metadata.docs.rs]

pkcs5/Cargo.toml

@@ -25,19 +25,34 @@
 #![forbid(unsafe_code)]
 #![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
 
+#[cfg(all(feature = "alloc", feature = "pbes2"))]
+extern crate alloc;
+
+pub mod pbes1;
+pub mod pbes2;
+
 pub use der::{self, Error, ObjectIdentifier};
 pub use spki::AlgorithmIdentifier;
 
-use core::convert::{TryFrom, TryInto};
+use core::{
+    convert::{TryFrom, TryInto},
+    fmt,
+};
 use der::{sequence, Any, Encodable, Encoder, Length};
 
-pub mod pbes1;
-pub mod pbes2;
+#[cfg(all(feature = "alloc", feature = "pbes2"))]
+use alloc::vec::Vec;
 
 /// Cryptographic errors
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct CryptoError;
 
+impl fmt::Display for CryptoError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str("PKCS#5 cryptographic error")
+    }
+}
+
 /// Supported PKCS#5 password-based encryption schemes.
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[non_exhaustive]
@@ -55,18 +70,18 @@ pub enum EncryptionScheme<'a> {
 }
 
 impl<'a> EncryptionScheme<'a> {
-    /// Encrypt the given ciphertext in-place using a key derived from the
-    /// provided password and this scheme's parameters.
-    #[cfg(feature = "pbes2")]
+    /// Attempt to decrypt the given ciphertext, allocating and returning a
+    /// byte vector containing the plaintext.
+    #[cfg(all(feature = "alloc", feature = "pbes2"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
     #[cfg_attr(docsrs, doc(cfg(feature = "pbes2")))]
-    pub fn encrypt_in_place<'b>(
+    pub fn decrypt(
         &self,
         password: impl AsRef<[u8]>,
-        buffer: &'b mut [u8],
-        pos: usize,
-    ) -> Result<&'b [u8], CryptoError> {
+        ciphertext: &[u8],
+    ) -> Result<Vec<u8>, CryptoError> {
         match self {
-            Self::Pbes2(params) => params.encrypt_in_place(password, buffer, pos),
+            Self::Pbes2(params) => params.decrypt(password, ciphertext),
             _ => Err(CryptoError),
         }
     }
@@ -90,6 +105,38 @@ impl<'a> EncryptionScheme<'a> {
         }
     }
 
+    /// Encrypt the given plaintext, allocating and returning a vector
+    /// containing the ciphertext.
+    #[cfg(all(feature = "alloc", feature = "pbes2"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "pbes2")))]
+    pub fn encrypt(
+        &self,
+        password: impl AsRef<[u8]>,
+        plaintext: &[u8],
+    ) -> Result<Vec<u8>, CryptoError> {
+        match self {
+            Self::Pbes2(params) => params.encrypt(password, plaintext),
+            _ => Err(CryptoError),
+        }
+    }
+
+    /// Encrypt the given ciphertext in-place using a key derived from the
+    /// provided password and this scheme's parameters.
+    #[cfg(feature = "pbes2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "pbes2")))]
+    pub fn encrypt_in_place<'b>(
+        &self,
+        password: impl AsRef<[u8]>,
+        buffer: &'b mut [u8],
+        pos: usize,
+    ) -> Result<&'b [u8], CryptoError> {
+        match self {
+            Self::Pbes2(params) => params.encrypt_in_place(password, buffer, pos),
+            _ => Err(CryptoError),
+        }
+    }
+
     /// Get the [`ObjectIdentifier`] (a.k.a OID) for this algorithm.
     pub fn oid(&self) -> ObjectIdentifier {
         match self {

pkcs5/src/lib.rs

@@ -10,6 +10,9 @@ use core::convert::{TryFrom, TryInto};
 use der::{Any, Decodable, Encodable, Encoder, Error, ErrorKind, Length, Message, OctetString};
 use spki::AlgorithmParameters;
 
+#[cfg(all(feature = "alloc", feature = "pbes2"))]
+use alloc::vec::Vec;
+
 /// Password-Based Encryption Scheme 2 (PBES2) OID.
 ///
 /// <https://tools.ietf.org/html/rfc8018#section-6.2>
@@ -81,17 +84,20 @@ impl<'a> Parameters<'a> {
         Ok(Self { kdf, encryption })
     }
 
-    /// Encrypt the given ciphertext in-place using a key derived from the
-    /// provided password and this scheme's parameters.
-    #[cfg(feature = "pbes2")]
+    /// Attempt to decrypt the given ciphertext, allocating and returning a
+    /// byte vector containing the plaintext.
+    #[cfg(all(feature = "alloc", feature = "pbes2"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
     #[cfg_attr(docsrs, doc(cfg(feature = "pbes2")))]
-    pub fn encrypt_in_place<'b>(
+    pub fn decrypt(
         &self,
         password: impl AsRef<[u8]>,
-        buffer: &'b mut [u8],
-        pos: usize,
-    ) -> Result<&'b [u8], CryptoError> {
-        encryption::encrypt_in_place(self, password, buffer, pos)
+        ciphertext: &[u8],
+    ) -> Result<Vec<u8>, CryptoError> {
+        let mut buffer = ciphertext.to_vec();
+        let pt_len = self.decrypt_in_place(password, &mut buffer)?.len();
+        buffer.truncate(pt_len);
+        Ok(buffer)
     }
 
     /// Attempt to decrypt the given ciphertext in-place using a key derived
@@ -109,6 +115,43 @@ impl<'a> Parameters<'a> {
     ) -> Result<&'b [u8], CryptoError> {
         encryption::decrypt_in_place(self, password, buffer)
     }
+
+    /// Encrypt the given plaintext, allocating and returning a vector
+    /// containing the ciphertext.
+    #[cfg(all(feature = "alloc", feature = "pbes2"))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "alloc")))]
+    #[cfg_attr(docsrs, doc(cfg(feature = "pbes2")))]
+    pub fn encrypt(
+        &self,
+        password: impl AsRef<[u8]>,
+        plaintext: &[u8],
+    ) -> Result<Vec<u8>, CryptoError> {
+        // TODO(tarcieri): support non-AES ciphers?
+        let mut buffer = Vec::with_capacity(plaintext.len() + AES_BLOCK_SIZE);
+        buffer.extend_from_slice(plaintext);
+        buffer.extend_from_slice(&[0u8; AES_BLOCK_SIZE]);
+
+        let ct_len = self
+            .encrypt_in_place(password, &mut buffer, plaintext.len())?
+            .len();
+
+        buffer.truncate(ct_len);
+        Ok(buffer)
+    }
+
+    /// Encrypt the given plaintext in-place using a key derived from the
+    /// provided password and this scheme's parameters, writing the ciphertext
+    /// into the same buffer.
+    #[cfg(feature = "pbes2")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "pbes2")))]
+    pub fn encrypt_in_place<'b>(
+        &self,
+        password: impl AsRef<[u8]>,
+        buffer: &'b mut [u8],
+        pos: usize,
+    ) -> Result<&'b [u8], CryptoError> {
+        encryption::encrypt_in_place(self, password, buffer, pos)
+    }
 }
 
 impl<'a> TryFrom<Any<'a>> for Parameters<'a> {

pkcs5/src/pbes2.rs

@@ -18,14 +18,15 @@ der = { version = "0.2", features = ["oid"], path = "../der" }
 spki = { version = "0.2", path = "../spki" }
 
 base64ct = { version = "0.2", optional = true, features = ["alloc"], path = "../base64ct" }
+rand_core = { version = "0.6", optional = true, default-features = false }
 pkcs5 = { version = "0.1", optional = true, path = "../pkcs5" }
 zeroize = { version = "1", optional = true, default-features = false, features = ["alloc"] }
 
 [dev-dependencies]
 hex-literal = "0.3"
 
 [features]
-encryption = ["alloc", "pkcs5/pbes2"]
+encryption = ["alloc", "pkcs5/alloc", "pkcs5/pbes2", "rand_core"]
 std = ["alloc", "der/std"]
 alloc = ["der/alloc", "zeroize"]
 pem = ["alloc", "base64ct"]

pkcs8/Cargo.toml

@@ -33,6 +33,20 @@ use {
 pub struct EncryptedPrivateKeyDocument(Zeroizing<Vec<u8>>);
 
 impl EncryptedPrivateKeyDocument {
+    /// Attempt to decrypt this encrypted private key using the provided
+    /// password to derive an encryption key.
+    #[cfg(feature = "encryption")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))]
+    pub fn decrypt(&self, password: impl AsRef<[u8]>) -> Result<PrivateKeyDocument> {
+        self.encrypted_private_key_info().decrypt(password)
+    }
+
+    /// Parse the [`EncryptedPrivateKeyInfo`] contained in this [`EncryptedPrivateKeyDocument`].
+    pub fn encrypted_private_key_info(&self) -> EncryptedPrivateKeyInfo<'_> {
+        EncryptedPrivateKeyInfo::try_from(self.0.as_ref())
+            .expect("malformed EncryptedPrivateKeyDocument")
+    }
+
     /// Parse [`EncryptedPrivateKeyDocument`] from ASN.1 DER-encoded PKCS#8.
     pub fn from_der(bytes: &[u8]) -> Result<Self> {
         bytes.try_into()
@@ -92,20 +106,6 @@ impl EncryptedPrivateKeyDocument {
     pub fn write_pem_file(&self, path: impl AsRef<Path>) -> Result<()> {
         write_secret_file(path, self.to_pem().as_bytes())
     }
-
-    /// Parse the [`EncryptedPrivateKeyInfo`] contained in this [`EncryptedPrivateKeyDocument`].
-    pub fn encrypted_private_key_info(&self) -> EncryptedPrivateKeyInfo<'_> {
-        EncryptedPrivateKeyInfo::try_from(self.0.as_ref())
-            .expect("malformed EncryptedPrivateKeyDocument")
-    }
-
-    /// Attempt to decrypt this encrypted private key using the provided
-    /// password to derive an encryption key.
-    #[cfg(feature = "encryption")]
-    #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))]
-    pub fn decrypt(&self, password: impl AsRef<[u8]>) -> Result<PrivateKeyDocument> {
-        self.encrypted_private_key_info().decrypt(password)
-    }
 }
 
 impl AsRef<[u8]> for EncryptedPrivateKeyDocument {

pkcs8/src/document/encrypted_private_key.rs

@@ -9,6 +9,13 @@ use core::{
 use der::Encodable;
 use zeroize::{Zeroize, Zeroizing};
 
+#[cfg(feature = "encryption")]
+use {
+    crate::{EncryptedPrivateKeyDocument, EncryptedPrivateKeyInfo},
+    pkcs5::pbes2,
+    rand_core::{CryptoRng, RngCore},
+};
+
 #[cfg(feature = "pem")]
 use {crate::pem, alloc::string::String, core::str::FromStr};
 
@@ -25,6 +32,11 @@ use std::{fs, path::Path, str};
 pub struct PrivateKeyDocument(Zeroizing<Vec<u8>>);
 
 impl PrivateKeyDocument {
+    /// Parse the [`PrivateKeyInfo`] contained in this [`PrivateKeyDocument`]
+    pub fn private_key_info(&self) -> PrivateKeyInfo<'_> {
+        PrivateKeyInfo::try_from(self.0.as_ref()).expect("malformed PrivateKeyDocument")
+    }
+
     /// Parse [`PrivateKeyDocument`] from ASN.1 DER-encoded PKCS#8
     pub fn from_der(bytes: &[u8]) -> Result<Self> {
         bytes.try_into()
@@ -82,9 +94,48 @@ impl PrivateKeyDocument {
         write_secret_file(path, self.to_pem().as_bytes())
     }
 
-    /// Parse the [`PrivateKeyInfo`] contained in this [`PrivateKeyDocument`]
-    pub fn private_key_info(&self) -> PrivateKeyInfo<'_> {
-        PrivateKeyInfo::try_from(self.0.as_ref()).expect("malformed PrivateKeyDocument")
+    /// Encrypt this private key using a symmetric encryption key derived
+    /// from the provided password.
+    #[cfg(feature = "encryption")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))]
+    pub fn encrypt(
+        &self,
+        mut rng: impl CryptoRng + RngCore,
+        password: impl AsRef<[u8]>,
+    ) -> Result<EncryptedPrivateKeyDocument> {
+        let mut salt = [0u8; 16];
+        rng.fill_bytes(&mut salt);
+
+        let mut iv = [0u8; 16];
+        rng.fill_bytes(&mut iv);
+
+        let pbkdf2_iterations = 10_000;
+        let pbes2_params =
+            pbes2::Parameters::pbkdf2_sha256_aes256cbc(pbkdf2_iterations, &salt, &iv)
+                .map_err(|_| Error::Encode)?; // TODO(tarcieri): add `pkcs8::Error::Crypto`
+
+        self.encrypt_with_params(pbes2_params, password)
+    }
+
+    /// Encrypt this private key using a symmetric encryption key derived
+    /// from the provided password and [`pbes2::Parameters`].
+    #[cfg(feature = "encryption")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "encryption")))]
+    pub fn encrypt_with_params(
+        &self,
+        pbes2_params: pbes2::Parameters<'_>,
+        password: impl AsRef<[u8]>,
+    ) -> Result<EncryptedPrivateKeyDocument> {
+        pbes2_params
+            .encrypt(password, self.as_ref())
+            .map(|encrypted_data| {
+                EncryptedPrivateKeyInfo {
+                    encryption_algorithm: pbes2_params.into(),
+                    encrypted_data: &encrypted_data,
+                }
+                .into()
+            })
+            .map_err(|_| Error::Encode)
     }
 }
 

pkcs8/src/document/private_key.rs

@@ -24,6 +24,11 @@ use {crate::pem, alloc::string::String, core::str::FromStr};
 pub struct PublicKeyDocument(Vec<u8>);
 
 impl PublicKeyDocument {
+    /// Parse the [`SubjectPublicKeyInfo`] contained in this [`PublicKeyDocument`]
+    pub fn spki(&self) -> SubjectPublicKeyInfo<'_> {
+        SubjectPublicKeyInfo::try_from(self.0.as_slice()).expect("malformed PublicKeyDocument")
+    }
+
     /// Parse [`PublicKeyDocument`] from ASN.1 DER
     pub fn from_der(bytes: &[u8]) -> Result<Self> {
         bytes.try_into()
@@ -82,11 +87,6 @@ impl PublicKeyDocument {
         fs::write(path, self.to_pem().as_bytes())?;
         Ok(())
     }
-
-    /// Parse the [`SubjectPublicKeyInfo`] contained in this [`PublicKeyDocument`]
-    pub fn spki(&self) -> SubjectPublicKeyInfo<'_> {
-        SubjectPublicKeyInfo::try_from(self.0.as_slice()).expect("malformed PublicKeyDocument")
-    }
 }
 
 impl AsRef<[u8]> for PublicKeyDocument {