dpe-rs/src/crypto.rs - open-dice - Git at Google

 // Copyright 2024 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
 // use this file except in compliance with the License. You may obtain a copy of
 // the License at
 //
 //     https://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing, software
 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 // License for the specific language governing permissions and limitations under
 // the License.

 //! Defines the Crypto trait and related types.

 use crate::byte_array_wrapper;
 use crate::constants::*;
 use crate::error::DpeResult;
 use crate::memory::{Message, SizedMessage};
 use zeroize::ZeroizeOnDrop;

 byte_array_wrapper!(MacKey, HASH_SIZE, "MAC key");
 byte_array_wrapper!(EncryptionKey, ENCRYPTION_KEY_SIZE, "encryption key");
 byte_array_wrapper!(DhPublicKey, DH_PUBLIC_KEY_SIZE, "DH public key");
 byte_array_wrapper!(DhPrivateKey, DH_PRIVATE_KEY_SIZE, "DH private key");
 byte_array_wrapper!(Hash, HASH_SIZE, "hash");
 byte_array_wrapper!(
     SigningPublicKey,
     SIGNING_PUBLIC_KEY_SIZE,
     "signing public key"
 );
 byte_array_wrapper!(
     SigningPrivateKey,
     SIGNING_PRIVATE_KEY_SIZE,
     "signing private key"
 );
 byte_array_wrapper!(
     SealingPublicKey,
     SEALING_PUBLIC_KEY_SIZE,
     "sealing public key"
 );
 byte_array_wrapper!(
     SealingPrivateKey,
     SEALING_PRIVATE_KEY_SIZE,
     "sealing private key"
 );

 /// A session handshake message.
 pub(crate) type HandshakeMessage = SizedMessage<MAX_HANDSHAKE_MESSAGE_SIZE>;
 /// A session handshake payload.
 pub(crate) type HandshakePayload = SizedMessage<MAX_HANDSHAKE_PAYLOAD_SIZE>;
 /// A signature.
 pub(crate) type Signature = SizedMessage<MAX_SIGNATURE_SIZE>;

 /// A trait for committing previously staged changes.
 pub(crate) trait Commit {
     /// Commits a previously staged changes. When used with session cipher
     /// state, the staged changes are typically counter increments that result
     /// from encrypt or decrypt operations.
     fn commit(&mut self);
 }

 /// A trait for maintaining a counter.
 pub(crate) trait Counter {
     /// Returns the current counter value.
     fn n(&self) -> u64;
     /// Sets the counter value to `n`.
     fn set_n(&mut self, n: u64);
 }

 /// Provides cryptographic operations for encrypted sessions.
 pub(crate) trait SessionCrypto {
     /// A type to represent session cipher states. These are owned by and opaque
     /// to the caller in `new_session_handshake` and `derive_session_handshake`.
     type SessionCipherState: Commit + Counter;

     /// Performs a session responder handshake for a new session.
     ///
     /// # Parameters
     ///
     /// * `static_dh_key`: The DPE session identity, which the client is
     /// expected to already know.
     /// * `initiator_handshake`: The handshake message received from the client.
     /// * `payload`: The payload to include in the `responder_handshake`.
     /// * `responder_handshake`: Receives the handshake message to be sent back
     /// to the client.
     /// * `decrypt_cipher_state`: Receives cipher state for decrypting incoming
     /// session messages. This is intended to be passed to
     /// [`SessionCrypto::session_decrypt`].
     /// * `encrypt_cipher_state`: Receives cipher state for encrypting outgoing
     /// session messages. This is intended to be passed to
     /// [`SessionCrypto::session_encrypt`].
     /// * `psk_seed`: Receives a PSK seed that can be used to construct a PSK to
     /// be used when deriving a session (see
     /// [`SessionCrypto::derive_session_handshake`]).
     ///
     /// # Errors
     ///
     /// This method allows implementers to return an error but it is expected to
     /// be infallible.
     #[allow(clippy::too_many_arguments)]
     fn new_session_handshake(
         static_dh_key: &DhPrivateKey,
         initiator_handshake: &HandshakeMessage,
         payload: &HandshakePayload,
         responder_handshake: &mut HandshakeMessage,
         decrypt_cipher_state: &mut Self::SessionCipherState,
         encrypt_cipher_state: &mut Self::SessionCipherState,
         psk_seed: &mut Hash,
     ) -> DpeResult<()>;

     /// Performs a session responder handshake for a derived session. In
     /// contrast to a new session handshake, a derived session does not use a
     /// static key, but a pre-shared key (PSK) derived from an existing session.
     ///
     /// # Parameters
     ///
     /// * `psk`: A PSK derived from an existing session.
     /// * `initiator_handshake`: The handshake message received from the client.
     /// * `payload`: The payload to include in the `responder_handshake`.
     /// * `responder_handshake`: Receives the handshake message to be sent back
     /// to the client.
     /// * `decrypt_cipher_state`: Receives cipher state for decrypting incoming
     /// session messages. This is intended to be passed to
     /// [`SessionCrypto::session_decrypt`].
     /// * `encrypt_cipher_state`: Receives cipher state for encrypting outgoing
     /// session messages. This is intended to be passed to
     /// [`SessionCrypto::session_encrypt`].
     /// * `psk_seed`: Receives a PSK seed that can be used to construct a PSK to
     /// be used when deriving another session.
     ///
     /// # Errors
     ///
     /// This method allows implementers to return an error but it is expected to
     /// be infallible.
     #[allow(clippy::too_many_arguments)]
     fn derive_session_handshake(
         psk: &Hash,
         initiator_handshake: &HandshakeMessage,
         payload: &HandshakePayload,
         responder_handshake: &mut HandshakeMessage,
         decrypt_cipher_state: &mut Self::SessionCipherState,
         encrypt_cipher_state: &mut Self::SessionCipherState,
         psk_seed: &mut Hash,
     ) -> DpeResult<()>;

     /// Derives a PSK from session state: `psk_seed`, `decrypt_cipher_state`,
     /// and `encrypt_cipher_state`. The returned PSK is appropriate as an
     /// argument to [`derive_session_handshake`].
     ///
     /// # Errors
     ///
     /// This method allows implementers to return an error but it is expected to
     /// be infallible.
     ///
     /// [`derive_session_handshake`]: #method.derive_session_handshake
     fn derive_psk_from_session(
         psk_seed: &Hash,
         decrypt_cipher_state: &Self::SessionCipherState,
         encrypt_cipher_state: &Self::SessionCipherState,
     ) -> DpeResult<Hash>;

     /// Encrypts an outgoing session message with the given `cipher_state`. The
     /// `in_place_buffer` both provides the plaintext message and receives the
     /// corresponding ciphertext.
     ///
     /// # Errors
     ///
     /// This method fails with an OutOfMemory error if the encryption overhead
     /// does not fit in the buffer.
     fn session_encrypt(
         cipher_state: &mut Self::SessionCipherState,
         in_place_buffer: &mut Message,
     ) -> DpeResult<()>;

     /// Decrypts an incoming session message with the given `cipher_state`. The
     /// `in_place_buffer` both provides the ciphertext message and receives the
     /// corresponding plaintext.
     ///
     /// # Errors
     ///
     /// This method fails with an InvalidArgument error if the ciphertext cannot
     /// be decrypted (e.g. if tag authentication fails).
     fn session_decrypt(
         cipher_state: &mut Self::SessionCipherState,
         in_place_buffer: &mut Message,
     ) -> DpeResult<()>;
 }

 /// Provides cryptographic operations. These operations are specifically for DPE
 /// concepts, defined by a DPE profile, and to be invoked by a DPE instance.
 pub(crate) trait Crypto {
     /// An associated [`SessionCrypto`] type.
     type S: SessionCrypto;

     /// Returns a hash of `input`.
     ///
     /// # Errors
     ///
     /// This method is infallible.
     fn hash(input: &[u8]) -> Hash;

     /// Returns a hash over all items in `iter`, in order.
     ///
     /// # Errors
     ///
     /// This method is infallible.
     fn hash_iter<'a>(iter: impl Iterator<Item = &'a [u8]>) -> Hash;

     /// Runs a key derivation function (KDF) to derive a key the length of the
     /// `derived_key` buffer. The inputs are interpreted as documented by the
     /// [HKDF](<https://datatracker.ietf.org/doc/html/rfc5869>) scheme. The
     /// implementation doesn't need to be HKDF specifically but needs to work
     /// with HKDF-style inputs.
     ///
     /// # Parameters
     ///
     /// * `kdf_ikm`: input keying material
     /// * `kdf_info`: HKDF-style info (optional)
     /// * `kdf_salt`: HKDF-style salt (optional)
     /// * `derived_key`: Receives the derived key
     ///
     /// # Errors
     ///
     /// Fails with an `InternalError` if `derived_key` is too large.
     fn kdf(
         kdf_ikm: &[u8],
         kdf_info: &[u8],
         kdf_salt: &[u8],
         derived_key: &mut [u8],
     ) -> DpeResult<()>;

     /// Derives an asymmetric key pair for signing from a given `seed`.
     ///
     /// # Errors
     ///
     /// This method allows implementers to return an error but it is expected to
     /// be infallible.
     fn signing_keypair_from_seed(
         seed: &Hash,
     ) -> DpeResult<(SigningPublicKey, SigningPrivateKey)>;

     /// Derives an asymmetric key pair for sealing from a given `seed`.
     ///
     /// # Errors
     ///
     /// This method allows implementers to return an error but it is expected to
     /// be infallible.
     fn sealing_keypair_from_seed(
         seed: &Hash,
     ) -> DpeResult<(SealingPublicKey, SealingPrivateKey)>;

     /// Computes a MAC over `data` using the given `key`.
     ///
     /// # Errors
     ///
     /// This method allows implementers to return an error but it is expected to
     /// be infallible.
     fn mac(key: &MacKey, data: &[u8]) -> DpeResult<Hash>;

     /// Generates a signature over `tbs` using the given `key`.
     ///
     /// # Errors
     ///
     /// This method allows implementers to return an error but it is expected to
     /// be infallible.
     fn sign(key: &SigningPrivateKey, tbs: &[u8]) -> DpeResult<Signature>;

     /// Encrypts data using the given `key` in a way that it can be decrypted by
     /// the `unseal` method with the same `key`. The `in_place_buffer` both
     /// provides the plaintext input and receives the ciphertext output.
     ///
     /// # Errors
     ///
     /// Fails with OutOfMemory if the ciphertext, including overhead, does not
     /// fit in the buffer.
     fn seal(
         key: &EncryptionKey,
         in_place_buffer: &mut Message,
     ) -> DpeResult<()>;

     /// Decrypts and authenticates data previously generated by the `seal`
     /// method using the given 'key'. The `in_place_buffer` both provides the
     /// ciphertext input and receives the plaintext output.
     ///
     /// # Errors
     ///
     /// Fails with InvalidArgument if authenticated decryption fails.
     fn unseal(
         key: &EncryptionKey,
         in_place_buffer: &mut Message,
     ) -> DpeResult<()>;

     /// Encrypts data using an asymmetric scheme and the given `public_key` in
     /// a way that it can be decrypted by the `unseal_asymmetric` method given
     /// the corresponding private key. While this method is useful for testing,
     /// a DPE does not use this during normal operation. The `in_place_buffer`
     /// both provides the plaintext input and receives the ciphertext output.
     ///
     /// # Errors
     ///
     /// Fails with OutOfMemory if the ciphertext, including overhead, does not
     /// fit in the buffer.
     fn seal_asymmetric(
         public_key: &SealingPublicKey,
         in_place_buffer: &mut Message,
     ) -> DpeResult<()>;

     /// Decrypts data using an asymmetric scheme and the give `key`. The
     /// `in_place_buffer` both provides the ciphertext input and receives the
     /// plaintext output.
     ///
     /// # Errors
     ///
     /// Fails with InvalidArgument if the ciphertext cannot be decrypted.
     fn unseal_asymmetric(
         key: &SealingPrivateKey,
         in_place_buffer: &mut Message,
     ) -> DpeResult<()>;
 }

 #[cfg(test)]
 pub(crate) mod test {
     use super::*;
     use crate::cbor::{
         cbor_decoder_from_message, cbor_encoder_from_message,
         encode_bytes_prefix, DecoderExt,
     };
     use crate::error::ErrCode;
     use crate::memory::SmallMessage;
     use crate::noise::test::SessionCryptoForTesting;
     use aes_gcm_siv::{AeadInPlace, Aes256GcmSiv, KeyInit};
     use ed25519_dalek::Signer;
     use hkdf::Hkdf;
     use hmac::{Hmac, Mac};
     use hpke::{
         aead::AeadTag, aead::AesGcm256, kdf::HkdfSha512, kem::Kem,
         kem::X25519HkdfSha256, Deserializable, OpModeR, OpModeS, Serializable,
     };
     use log::{debug, error};
     use rand_chacha::ChaCha12Rng;
     use rand_core::SeedableRng;
     use sha2::{Digest, Sha512};

     pub(crate) type HmacSha512 = Hmac<Sha512>;

     impl From<aes_gcm_siv::Error> for ErrCode {
         fn from(err: aes_gcm_siv::Error) -> Self {
             error!("Decrypt error: {:?}", err);
             ErrCode::InvalidArgument
         }
     }

     impl From<hpke::HpkeError> for ErrCode {
         fn from(err: hpke::HpkeError) -> Self {
             error!("Hpke error: {:?}", err);
             ErrCode::InvalidArgument
         }
     }

     #[derive(Clone, Default, Debug, Eq, PartialEq, Hash)]
     pub(crate) struct CryptoForTesting {
         pub(crate) noise: SessionCryptoForTesting,
     }

     impl Crypto for CryptoForTesting {
         type S = SessionCryptoForTesting;

         fn hash(input: &[u8]) -> Hash {
             Hash::from_slice(Sha512::digest(input).as_slice()).unwrap()
         }

         fn hash_iter<'a>(iter: impl Iterator<Item = &'a [u8]>) -> Hash {
             let mut hasher = Sha512::new();
             for input in iter {
                 hasher.update(input);
             }
             Hash::from_slice(hasher.finalize().as_slice()).unwrap()
         }

         fn kdf(
             kdf_ikm: &[u8],
             kdf_info: &[u8],
             kdf_salt: &[u8],
             derived_key: &mut [u8],
         ) -> DpeResult<()> {
             Hkdf::<Sha512>::new(Some(kdf_salt), kdf_ikm)
                 .expand(kdf_info, derived_key)
                 .unwrap();
             Ok(())
         }

         fn signing_keypair_from_seed(
             seed: &Hash,
         ) -> DpeResult<(SigningPublicKey, SigningPrivateKey)> {
             let mut key_bytes: ed25519_dalek::SecretKey = Default::default();
             key_bytes.copy_from_slice(&seed.as_slice()[..32]);
             let sk = ed25519_dalek::SigningKey::from_bytes(&key_bytes);
             Ok((
                 SigningPublicKey::from_array(sk.verifying_key().as_bytes()),
                 SigningPrivateKey::from_array(sk.as_bytes()),
             ))
         }

         fn sealing_keypair_from_seed(
             seed: &Hash,
         ) -> DpeResult<(SealingPublicKey, SealingPrivateKey)> {
             let (private_key, public_key) =
                 <X25519HkdfSha256 as Kem>::derive_keypair(seed.as_slice());
             Ok((
                 SealingPublicKey::from_slice(public_key.to_bytes().as_slice())?,
                 SealingPrivateKey::from_slice(
                     private_key.to_bytes().as_slice(),
                 )?,
             ))
         }

         fn mac(key: &MacKey, data: &[u8]) -> DpeResult<Hash> {
             let mut hmac =
                 <HmacSha512 as Mac>::new_from_slice(key.as_slice()).unwrap();
             hmac.update(data);
             Ok(Hash::from_slice(hmac.finalize().into_bytes().as_slice())
                 .unwrap())
         }

         fn sign(key: &SigningPrivateKey, tbs: &[u8]) -> DpeResult<Signature> {
             let sk = ed25519_dalek::SigningKey::from_bytes(key.as_array());
             let sig = sk.sign(tbs).to_bytes();
             Ok(Signature::from_slice(&sig).unwrap())
         }

         fn seal(
             key: &EncryptionKey,
             in_place_buffer: &mut Message,
         ) -> DpeResult<()> {
             const TAG_LENGTH: usize = 16;
             let cipher = Aes256GcmSiv::new(key.as_slice().into());
             let nonce = Default::default();
             // Make space to append the tag.
             let required_buffer_size = in_place_buffer.len() + TAG_LENGTH;
             in_place_buffer
                 .vec
                 .resize_default(required_buffer_size)
                 .map_err(|_| ErrCode::OutOfMemory)
                 .unwrap();
             cipher
                 .encrypt_in_place(&nonce, &[], &mut in_place_buffer.vec)
                 .unwrap();
             Ok(())
         }

         fn unseal(
             key: &EncryptionKey,
             in_place_buffer: &mut Message,
         ) -> DpeResult<()> {
             const TAG_LENGTH: usize = 16;
             let cipher = Aes256GcmSiv::new(key.as_slice().into());
             let nonce = Default::default();
             cipher.decrypt_in_place(&nonce, &[], &mut in_place_buffer.vec)?;
             let plaintext_len = in_place_buffer.len() - TAG_LENGTH;
             in_place_buffer.vec.truncate(plaintext_len);
             Ok(())
         }

         fn seal_asymmetric(
             public_key: &SealingPublicKey,
             in_place_buffer: &mut Message,
         ) -> DpeResult<()> {
             let mut rng = <ChaCha12Rng as SeedableRng>::from_seed([0xFF; 32]);
             let kem_public_key =
                 <X25519HkdfSha256 as Kem>::PublicKey::from_bytes(
                     public_key.as_slice(),
                 )?;
             let (encapped_key, aead_tag) =
                 hpke::single_shot_seal_in_place_detached::<
                     AesGcm256,
                     HkdfSha512,
                     X25519HkdfSha256,
                     _,
                 >(
                     &OpModeS::Base,
                     &kem_public_key,
                     &[],
                     in_place_buffer.vec.as_mut(),
                     &[],
                     &mut rng,
                 )?;
             let mut prefix = SmallMessage::new();
             let mut encoder = cbor_encoder_from_message(&mut prefix);
             let _ = encoder.bytes(encapped_key.to_bytes().as_slice())?;
             let _ = encoder.bytes(aead_tag.to_bytes().as_slice())?;
             encode_bytes_prefix(&mut prefix, in_place_buffer.len())?;
             debug!(
                 "seal_asymmetric: h={}, d={}",
                 prefix.len(),
                 in_place_buffer.len()
             );
             in_place_buffer.insert_prefix(prefix.as_slice())?;
             Ok(())
         }

         fn unseal_asymmetric(
             private_key: &SealingPrivateKey,
             in_place_buffer: &mut Message,
         ) -> DpeResult<()> {
             let mut decoder = cbor_decoder_from_message(in_place_buffer);
             let encapped_key =
                 <X25519HkdfSha256 as Kem>::EncappedKey::from_bytes(
                     decoder.bytes()?,
                 )?;
             let tag = AeadTag::from_bytes(decoder.bytes()?)?;
             // Leave only the ciphertext in in_place_buffer.
             let sealed_data_position = decoder.decode_bytes_prefix()?;
             debug!(
                 "unseal_asymmetric: h={}, d={}",
                 sealed_data_position,
                 in_place_buffer.len() - sealed_data_position
             );
             in_place_buffer.remove_prefix(sealed_data_position)?;
             let kem_private_key =
                 <X25519HkdfSha256 as Kem>::PrivateKey::from_bytes(
                     private_key.as_slice(),
                 )?;
             hpke::single_shot_open_in_place_detached::<
                 AesGcm256,
                 HkdfSha512,
                 X25519HkdfSha256,
             >(
                 &OpModeR::Base,
                 &kem_private_key,
                 &encapped_key,
                 &[],
                 in_place_buffer.vec.as_mut(),
                 &[],
                 &tag,
             )?;
             Ok(())
         }
     }
 }
	// Copyright 2024 Google LLC
	//
	// Licensed under the Apache License, Version 2.0 (the "License"); you may not
	// use this file except in compliance with the License. You may obtain a copy of
	// the License at
	//
	// https://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing, software
	// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	// License for the specific language governing permissions and limitations under
	// the License.

	//! Defines the Crypto trait and related types.

	use crate::byte_array_wrapper;
	use crate::constants::*;
	use crate::error::DpeResult;
	use crate::memory::{Message, SizedMessage};
	use zeroize::ZeroizeOnDrop;

	byte_array_wrapper!(MacKey, HASH_SIZE, "MAC key");
	byte_array_wrapper!(EncryptionKey, ENCRYPTION_KEY_SIZE, "encryption key");
	byte_array_wrapper!(DhPublicKey, DH_PUBLIC_KEY_SIZE, "DH public key");
	byte_array_wrapper!(DhPrivateKey, DH_PRIVATE_KEY_SIZE, "DH private key");
	byte_array_wrapper!(Hash, HASH_SIZE, "hash");
	byte_array_wrapper!(
	SigningPublicKey,
	SIGNING_PUBLIC_KEY_SIZE,
	"signing public key"
	);
	byte_array_wrapper!(
	SigningPrivateKey,
	SIGNING_PRIVATE_KEY_SIZE,
	"signing private key"
	);
	byte_array_wrapper!(
	SealingPublicKey,
	SEALING_PUBLIC_KEY_SIZE,
	"sealing public key"
	);
	byte_array_wrapper!(
	SealingPrivateKey,
	SEALING_PRIVATE_KEY_SIZE,
	"sealing private key"
	);

	/// A session handshake message.
	pub(crate) type HandshakeMessage = SizedMessage<MAX_HANDSHAKE_MESSAGE_SIZE>;
	/// A session handshake payload.
	pub(crate) type HandshakePayload = SizedMessage<MAX_HANDSHAKE_PAYLOAD_SIZE>;
	/// A signature.
	pub(crate) type Signature = SizedMessage<MAX_SIGNATURE_SIZE>;

	/// A trait for committing previously staged changes.
	pub(crate) trait Commit {
	/// Commits a previously staged changes. When used with session cipher
	/// state, the staged changes are typically counter increments that result
	/// from encrypt or decrypt operations.
	fn commit(&mut self);
	}

	/// A trait for maintaining a counter.
	pub(crate) trait Counter {
	/// Returns the current counter value.
	fn n(&self) -> u64;
	/// Sets the counter value to `n`.
	fn set_n(&mut self, n: u64);
	}

	/// Provides cryptographic operations for encrypted sessions.
	pub(crate) trait SessionCrypto {
	/// A type to represent session cipher states. These are owned by and opaque
	/// to the caller in `new_session_handshake` and `derive_session_handshake`.
	type SessionCipherState: Commit + Counter;

	/// Performs a session responder handshake for a new session.
	///
	/// # Parameters
	///
	/// * `static_dh_key`: The DPE session identity, which the client is
	/// expected to already know.
	/// * `initiator_handshake`: The handshake message received from the client.
	/// * `payload`: The payload to include in the `responder_handshake`.
	/// * `responder_handshake`: Receives the handshake message to be sent back
	/// to the client.
	/// * `decrypt_cipher_state`: Receives cipher state for decrypting incoming
	/// session messages. This is intended to be passed to
	/// [`SessionCrypto::session_decrypt`].
	/// * `encrypt_cipher_state`: Receives cipher state for encrypting outgoing
	/// session messages. This is intended to be passed to
	/// [`SessionCrypto::session_encrypt`].
	/// * `psk_seed`: Receives a PSK seed that can be used to construct a PSK to
	/// be used when deriving a session (see
	/// [`SessionCrypto::derive_session_handshake`]).
	///
	/// # Errors
	///
	/// This method allows implementers to return an error but it is expected to
	/// be infallible.
	#[allow(clippy::too_many_arguments)]
	fn new_session_handshake(
	static_dh_key: &DhPrivateKey,
	initiator_handshake: &HandshakeMessage,
	payload: &HandshakePayload,
	responder_handshake: &mut HandshakeMessage,
	decrypt_cipher_state: &mut Self::SessionCipherState,
	encrypt_cipher_state: &mut Self::SessionCipherState,
	psk_seed: &mut Hash,
	) -> DpeResult<()>;

	/// Performs a session responder handshake for a derived session. In
	/// contrast to a new session handshake, a derived session does not use a
	/// static key, but a pre-shared key (PSK) derived from an existing session.
	///
	/// # Parameters
	///
	/// * `psk`: A PSK derived from an existing session.
	/// * `initiator_handshake`: The handshake message received from the client.
	/// * `payload`: The payload to include in the `responder_handshake`.
	/// * `responder_handshake`: Receives the handshake message to be sent back
	/// to the client.
	/// * `decrypt_cipher_state`: Receives cipher state for decrypting incoming
	/// session messages. This is intended to be passed to
	/// [`SessionCrypto::session_decrypt`].
	/// * `encrypt_cipher_state`: Receives cipher state for encrypting outgoing
	/// session messages. This is intended to be passed to
	/// [`SessionCrypto::session_encrypt`].
	/// * `psk_seed`: Receives a PSK seed that can be used to construct a PSK to
	/// be used when deriving another session.
	///
	/// # Errors
	///
	/// This method allows implementers to return an error but it is expected to
	/// be infallible.
	#[allow(clippy::too_many_arguments)]
	fn derive_session_handshake(
	psk: &Hash,
	initiator_handshake: &HandshakeMessage,
	payload: &HandshakePayload,
	responder_handshake: &mut HandshakeMessage,
	decrypt_cipher_state: &mut Self::SessionCipherState,
	encrypt_cipher_state: &mut Self::SessionCipherState,
	psk_seed: &mut Hash,
	) -> DpeResult<()>;

	/// Derives a PSK from session state: `psk_seed`, `decrypt_cipher_state`,
	/// and `encrypt_cipher_state`. The returned PSK is appropriate as an
	/// argument to [`derive_session_handshake`].
	///
	/// # Errors
	///
	/// This method allows implementers to return an error but it is expected to
	/// be infallible.
	///
	/// [`derive_session_handshake`]: #method.derive_session_handshake
	fn derive_psk_from_session(
	psk_seed: &Hash,
	decrypt_cipher_state: &Self::SessionCipherState,
	encrypt_cipher_state: &Self::SessionCipherState,
	) -> DpeResult<Hash>;

	/// Encrypts an outgoing session message with the given `cipher_state`. The
	/// `in_place_buffer` both provides the plaintext message and receives the
	/// corresponding ciphertext.
	///
	/// # Errors
	///
	/// This method fails with an OutOfMemory error if the encryption overhead
	/// does not fit in the buffer.
	fn session_encrypt(
	cipher_state: &mut Self::SessionCipherState,
	in_place_buffer: &mut Message,
	) -> DpeResult<()>;

	/// Decrypts an incoming session message with the given `cipher_state`. The
	/// `in_place_buffer` both provides the ciphertext message and receives the
	/// corresponding plaintext.
	///
	/// # Errors
	///
	/// This method fails with an InvalidArgument error if the ciphertext cannot
	/// be decrypted (e.g. if tag authentication fails).
	fn session_decrypt(
	cipher_state: &mut Self::SessionCipherState,
	in_place_buffer: &mut Message,
	) -> DpeResult<()>;
	}

	/// Provides cryptographic operations. These operations are specifically for DPE
	/// concepts, defined by a DPE profile, and to be invoked by a DPE instance.
	pub(crate) trait Crypto {
	/// An associated [`SessionCrypto`] type.
	type S: SessionCrypto;

	/// Returns a hash of `input`.
	///
	/// # Errors
	///
	/// This method is infallible.
	fn hash(input: &[u8]) -> Hash;

	/// Returns a hash over all items in `iter`, in order.
	///
	/// # Errors
	///
	/// This method is infallible.
	fn hash_iter<'a>(iter: impl Iterator<Item = &'a [u8]>) -> Hash;

	/// Runs a key derivation function (KDF) to derive a key the length of the
	/// `derived_key` buffer. The inputs are interpreted as documented by the
	/// [HKDF](<https://datatracker.ietf.org/doc/html/rfc5869>) scheme. The
	/// implementation doesn't need to be HKDF specifically but needs to work
	/// with HKDF-style inputs.
	///
	/// # Parameters
	///
	/// * `kdf_ikm`: input keying material
	/// * `kdf_info`: HKDF-style info (optional)
	/// * `kdf_salt`: HKDF-style salt (optional)
	/// * `derived_key`: Receives the derived key
	///
	/// # Errors
	///
	/// Fails with an `InternalError` if `derived_key` is too large.
	fn kdf(
	kdf_ikm: &[u8],
	kdf_info: &[u8],
	kdf_salt: &[u8],
	derived_key: &mut [u8],
	) -> DpeResult<()>;

	/// Derives an asymmetric key pair for signing from a given `seed`.
	///
	/// # Errors
	///
	/// This method allows implementers to return an error but it is expected to
	/// be infallible.
	fn signing_keypair_from_seed(
	seed: &Hash,
	) -> DpeResult<(SigningPublicKey, SigningPrivateKey)>;

	/// Derives an asymmetric key pair for sealing from a given `seed`.
	///
	/// # Errors
	///
	/// This method allows implementers to return an error but it is expected to
	/// be infallible.
	fn sealing_keypair_from_seed(
	seed: &Hash,
	) -> DpeResult<(SealingPublicKey, SealingPrivateKey)>;

	/// Computes a MAC over `data` using the given `key`.
	///
	/// # Errors
	///
	/// This method allows implementers to return an error but it is expected to
	/// be infallible.
	fn mac(key: &MacKey, data: &[u8]) -> DpeResult<Hash>;

	/// Generates a signature over `tbs` using the given `key`.
	///
	/// # Errors
	///
	/// This method allows implementers to return an error but it is expected to
	/// be infallible.
	fn sign(key: &SigningPrivateKey, tbs: &[u8]) -> DpeResult<Signature>;

	/// Encrypts data using the given `key` in a way that it can be decrypted by
	/// the `unseal` method with the same `key`. The `in_place_buffer` both
	/// provides the plaintext input and receives the ciphertext output.
	///
	/// # Errors
	///
	/// Fails with OutOfMemory if the ciphertext, including overhead, does not
	/// fit in the buffer.
	fn seal(
	key: &EncryptionKey,
	in_place_buffer: &mut Message,
	) -> DpeResult<()>;

	/// Decrypts and authenticates data previously generated by the `seal`
	/// method using the given 'key'. The `in_place_buffer` both provides the
	/// ciphertext input and receives the plaintext output.
	///
	/// # Errors
	///
	/// Fails with InvalidArgument if authenticated decryption fails.
	fn unseal(
	key: &EncryptionKey,
	in_place_buffer: &mut Message,
	) -> DpeResult<()>;

	/// Encrypts data using an asymmetric scheme and the given `public_key` in
	/// a way that it can be decrypted by the `unseal_asymmetric` method given
	/// the corresponding private key. While this method is useful for testing,
	/// a DPE does not use this during normal operation. The `in_place_buffer`
	/// both provides the plaintext input and receives the ciphertext output.
	///
	/// # Errors
	///
	/// Fails with OutOfMemory if the ciphertext, including overhead, does not
	/// fit in the buffer.
	fn seal_asymmetric(
	public_key: &SealingPublicKey,
	in_place_buffer: &mut Message,
	) -> DpeResult<()>;

	/// Decrypts data using an asymmetric scheme and the give `key`. The
	/// `in_place_buffer` both provides the ciphertext input and receives the
	/// plaintext output.
	///
	/// # Errors
	///
	/// Fails with InvalidArgument if the ciphertext cannot be decrypted.
	fn unseal_asymmetric(
	key: &SealingPrivateKey,
	in_place_buffer: &mut Message,
	) -> DpeResult<()>;
	}

	#[cfg(test)]
	pub(crate) mod test {
	use super::*;
	use crate::cbor::{
	cbor_decoder_from_message, cbor_encoder_from_message,
	encode_bytes_prefix, DecoderExt,
	};
	use crate::error::ErrCode;
	use crate::memory::SmallMessage;
	use crate::noise::test::SessionCryptoForTesting;
	use aes_gcm_siv::{AeadInPlace, Aes256GcmSiv, KeyInit};
	use ed25519_dalek::Signer;
	use hkdf::Hkdf;
	use hmac::{Hmac, Mac};
	use hpke::{
	aead::AeadTag, aead::AesGcm256, kdf::HkdfSha512, kem::Kem,
	kem::X25519HkdfSha256, Deserializable, OpModeR, OpModeS, Serializable,
	};
	use log::{debug, error};
	use rand_chacha::ChaCha12Rng;
	use rand_core::SeedableRng;
	use sha2::{Digest, Sha512};

	pub(crate) type HmacSha512 = Hmac<Sha512>;

	impl From<aes_gcm_siv::Error> for ErrCode {
	fn from(err: aes_gcm_siv::Error) -> Self {
	error!("Decrypt error: {:?}", err);
	ErrCode::InvalidArgument
	}
	}

	impl From<hpke::HpkeError> for ErrCode {
	fn from(err: hpke::HpkeError) -> Self {
	error!("Hpke error: {:?}", err);
	ErrCode::InvalidArgument
	}
	}

	#[derive(Clone, Default, Debug, Eq, PartialEq, Hash)]
	pub(crate) struct CryptoForTesting {
	pub(crate) noise: SessionCryptoForTesting,
	}

	impl Crypto for CryptoForTesting {
	type S = SessionCryptoForTesting;

	fn hash(input: &[u8]) -> Hash {
	Hash::from_slice(Sha512::digest(input).as_slice()).unwrap()
	}

	fn hash_iter<'a>(iter: impl Iterator<Item = &'a [u8]>) -> Hash {
	let mut hasher = Sha512::new();
	for input in iter {
	hasher.update(input);
	}
	Hash::from_slice(hasher.finalize().as_slice()).unwrap()
	}

	fn kdf(
	kdf_ikm: &[u8],
	kdf_info: &[u8],
	kdf_salt: &[u8],
	derived_key: &mut [u8],
	) -> DpeResult<()> {
	Hkdf::<Sha512>::new(Some(kdf_salt), kdf_ikm)
	.expand(kdf_info, derived_key)
	.unwrap();
	Ok(())
	}

	fn signing_keypair_from_seed(
	seed: &Hash,
	) -> DpeResult<(SigningPublicKey, SigningPrivateKey)> {
	let mut key_bytes: ed25519_dalek::SecretKey = Default::default();
	key_bytes.copy_from_slice(&seed.as_slice()[..32]);
	let sk = ed25519_dalek::SigningKey::from_bytes(&key_bytes);
	Ok((
	SigningPublicKey::from_array(sk.verifying_key().as_bytes()),
	SigningPrivateKey::from_array(sk.as_bytes()),
	))
	}

	fn sealing_keypair_from_seed(
	seed: &Hash,
	) -> DpeResult<(SealingPublicKey, SealingPrivateKey)> {
	let (private_key, public_key) =
	<X25519HkdfSha256 as Kem>::derive_keypair(seed.as_slice());
	Ok((
	SealingPublicKey::from_slice(public_key.to_bytes().as_slice())?,
	SealingPrivateKey::from_slice(
	private_key.to_bytes().as_slice(),
	)?,
	))
	}

	fn mac(key: &MacKey, data: &[u8]) -> DpeResult<Hash> {
	let mut hmac =
	<HmacSha512 as Mac>::new_from_slice(key.as_slice()).unwrap();
	hmac.update(data);
	Ok(Hash::from_slice(hmac.finalize().into_bytes().as_slice())
	.unwrap())
	}

	fn sign(key: &SigningPrivateKey, tbs: &[u8]) -> DpeResult<Signature> {
	let sk = ed25519_dalek::SigningKey::from_bytes(key.as_array());
	let sig = sk.sign(tbs).to_bytes();
	Ok(Signature::from_slice(&sig).unwrap())
	}

	fn seal(
	key: &EncryptionKey,
	in_place_buffer: &mut Message,
	) -> DpeResult<()> {
	const TAG_LENGTH: usize = 16;
	let cipher = Aes256GcmSiv::new(key.as_slice().into());
	let nonce = Default::default();
	// Make space to append the tag.
	let required_buffer_size = in_place_buffer.len() + TAG_LENGTH;
	in_place_buffer
	.vec
	.resize_default(required_buffer_size)
	.map_err(\|_\| ErrCode::OutOfMemory)
	.unwrap();
	cipher
	.encrypt_in_place(&nonce, &[], &mut in_place_buffer.vec)
	.unwrap();
	Ok(())
	}

	fn unseal(
	key: &EncryptionKey,
	in_place_buffer: &mut Message,
	) -> DpeResult<()> {
	const TAG_LENGTH: usize = 16;
	let cipher = Aes256GcmSiv::new(key.as_slice().into());
	let nonce = Default::default();
	cipher.decrypt_in_place(&nonce, &[], &mut in_place_buffer.vec)?;
	let plaintext_len = in_place_buffer.len() - TAG_LENGTH;
	in_place_buffer.vec.truncate(plaintext_len);
	Ok(())
	}

	fn seal_asymmetric(
	public_key: &SealingPublicKey,
	in_place_buffer: &mut Message,
	) -> DpeResult<()> {
	let mut rng = <ChaCha12Rng as SeedableRng>::from_seed([0xFF; 32]);
	let kem_public_key =
	<X25519HkdfSha256 as Kem>::PublicKey::from_bytes(
	public_key.as_slice(),
	)?;
	let (encapped_key, aead_tag) =
	hpke::single_shot_seal_in_place_detached::<
	AesGcm256,
	HkdfSha512,
	X25519HkdfSha256,
	_,
	>(
	&OpModeS::Base,
	&kem_public_key,
	&[],
	in_place_buffer.vec.as_mut(),
	&[],
	&mut rng,
	)?;
	let mut prefix = SmallMessage::new();
	let mut encoder = cbor_encoder_from_message(&mut prefix);
	let _ = encoder.bytes(encapped_key.to_bytes().as_slice())?;
	let _ = encoder.bytes(aead_tag.to_bytes().as_slice())?;
	encode_bytes_prefix(&mut prefix, in_place_buffer.len())?;
	debug!(
	"seal_asymmetric: h={}, d={}",
	prefix.len(),
	in_place_buffer.len()
	);
	in_place_buffer.insert_prefix(prefix.as_slice())?;
	Ok(())
	}

	fn unseal_asymmetric(
	private_key: &SealingPrivateKey,
	in_place_buffer: &mut Message,
	) -> DpeResult<()> {
	let mut decoder = cbor_decoder_from_message(in_place_buffer);
	let encapped_key =
	<X25519HkdfSha256 as Kem>::EncappedKey::from_bytes(
	decoder.bytes()?,
	)?;
	let tag = AeadTag::from_bytes(decoder.bytes()?)?;
	// Leave only the ciphertext in in_place_buffer.
	let sealed_data_position = decoder.decode_bytes_prefix()?;
	debug!(
	"unseal_asymmetric: h={}, d={}",
	sealed_data_position,
	in_place_buffer.len() - sealed_data_position
	);
	in_place_buffer.remove_prefix(sealed_data_position)?;
	let kem_private_key =
	<X25519HkdfSha256 as Kem>::PrivateKey::from_bytes(
	private_key.as_slice(),
	)?;
	hpke::single_shot_open_in_place_detached::<
	AesGcm256,
	HkdfSha512,
	X25519HkdfSha256,
	>(
	&OpModeR::Base,
	&kem_private_key,
	&encapped_key,
	&[],
	in_place_buffer.vec.as_mut(),
	&[],
	&tag,
	)?;
	Ok(())
	}
	}
	}