1 // Copyright 2023 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #[cfg(feature = "alloc")] 16 extern crate alloc; 17 #[cfg(feature = "alloc")] 18 use alloc::vec::Vec; 19 20 /// An implementation of AES-GCM-SIV. 21 /// 22 /// An AesGcmSiv impl may be used for encryption and decryption. 23 pub trait AesGcmSiv: Aead<Nonce = [u8; 12]> {} 24 25 /// An implementation of AES-GCM. 26 /// 27 /// An AesGcm impl may be used for encryption and decryption. 28 pub trait AesGcm: Aead<Nonce = [u8; 12]> {} 29 30 /// Error returned on unsuccessful AEAD operation. 31 #[derive(Debug)] 32 pub struct AeadError; 33 34 /// Initializes an AEAD 35 pub trait AeadInit<K: crate::aes::AesKey> { 36 /// Instantiates a new instance of the AEAD from key material. new(key: &K) -> Self37 fn new(key: &K) -> Self; 38 } 39 40 /// Authenticated Encryption with Associated Data (AEAD) algorithm, where `N` is the size of the 41 /// Nonce. Encrypts and decrypts buffers in-place. 42 pub trait Aead { 43 /// The size of the authentication tag, this is appended to the message on the encrypt operation 44 /// and truncated from the plaintext after decrypting. 45 const TAG_SIZE: usize; 46 47 /// The cryptographic nonce used by the AEAD. The nonce must be unique for all messages with 48 /// the same key. This is critically important - nonce reuse may completely undermine the 49 /// security of the AEAD. Nonces may be predictable and public, so long as they are unique. 50 type Nonce: AsRef<[u8]>; 51 52 /// The type of the tag, which should always be [u8; Self::TAG_SIZE]. 53 type Tag: AsRef<[u8]>; 54 55 /// Encrypt the given buffer containing a plaintext message. On success returns the encrypted 56 /// `msg` and appended auth tag, which will result in a Vec which is `Self::TAG_SIZE` bytes 57 /// greater than the initial message. 58 #[cfg(feature = "alloc")] encrypt(&self, msg: &[u8], aad: &[u8], nonce: &Self::Nonce) -> Result<Vec<u8>, AeadError>59 fn encrypt(&self, msg: &[u8], aad: &[u8], nonce: &Self::Nonce) -> Result<Vec<u8>, AeadError>; 60 61 /// Encrypt the given buffer containing a plaintext message in-place, and returns the tag in the 62 /// result value. encrypt_detached( &self, msg: &mut [u8], aad: &[u8], nonce: &Self::Nonce, ) -> Result<Self::Tag, AeadError>63 fn encrypt_detached( 64 &self, 65 msg: &mut [u8], 66 aad: &[u8], 67 nonce: &Self::Nonce, 68 ) -> Result<Self::Tag, AeadError>; 69 70 /// Decrypt the message, returning the decrypted plaintext or an error in the event the 71 /// provided authentication tag does not match the given ciphertext. On success the returned 72 /// Vec will only contain the plaintext and so will be `Self::TAG_SIZE` bytes less than the 73 /// initial message. 74 #[cfg(feature = "alloc")] decrypt(&self, msg: &[u8], aad: &[u8], nonce: &Self::Nonce) -> Result<Vec<u8>, AeadError>75 fn decrypt(&self, msg: &[u8], aad: &[u8], nonce: &Self::Nonce) -> Result<Vec<u8>, AeadError>; 76 77 /// Decrypt the message in-place, returning an error and leaving the input `msg` unchanged in 78 /// the event the provided authentication tag does not match the given ciphertext. decrypt_detached( &self, msg: &mut [u8], aad: &[u8], nonce: &Self::Nonce, tag: &Self::Tag, ) -> Result<(), AeadError>79 fn decrypt_detached( 80 &self, 81 msg: &mut [u8], 82 aad: &[u8], 83 nonce: &Self::Nonce, 84 tag: &Self::Tag, 85 ) -> Result<(), AeadError>; 86 } 87