11//! Provides simplified abstracted APIs over classes of cryptographic primitives, such as Hash, KDF, etc.
22
3- <<<<<<< HEAD
4- use crate :: errors:: * ;
5- =======
63use crate :: errors:: { AeadError , HashError , KDFError , KEMError , MACError , RNGError , SignatureError } ;
7- >>>>>>> 3 d44362 ( Added ascon_cmd. rs)
84use crate :: key_material:: KeyMaterialTrait ;
95use core:: fmt:: { Debug , Display } ;
106use core:: marker:: Sized ;
@@ -26,258 +22,6 @@ pub trait Algorithm {
2622 const MAX_SECURITY_STRENGTH : SecurityStrength ;
2723}
2824
29- <<<<<<< HEAD
30- /// Some algorithms have an assigned OID.
31- pub trait AlgorithmOID {
32- /// The OID in component form -- each u32 is one OID component.
33- const OID : & ' static [ u32 ] ;
34- /// The OID in its DER-encoded form.
35- const OID_DER : & ' static [ u8 ] ;
36- }
37-
38- // todo -- split all the SymmetricCipher traits into Encryptor and Decryptor
39- /// The basic one-shot encrypt and decrypt that all types of symmetric ciphers must implement.
40- /// These are meant to be simple , easy to use , secure , and fool-proof APIs , but they may result in
41- /// ciphertexts that are incompatible with other implementations as ciphers in more complex modes, such
42- /// as AEADs or stream ciphers may need to stick extra data either at the beginning or end of the ciphertext.
43- /// See the documentation of the underlying implementation for more details.
44- pub trait SymmetricCipher < const KEY_LEN : usize , const INIT_DATA_LEN : usize > : Algorithm {
45- #[ cfg ( feature = "std" ) ]
46- /// A one-shot API to encrypt some plaintext with the given key.
47- /// This function returns the ciphertext as a `Vec<u8>`, and therefore is only available when compiling with std.
48- /// Returns a tuple containing the initialization data and the ciphertext.
49- /// This is not available if building for no_std.
50- fn encrypt (
51- key : & KeyMaterial < KEY_LEN > ,
52- plaintext : & [ u8 ] ,
53- ) -> Result < ( [ u8 ; INIT_DATA_LEN ] , Vec < u8 > ) , SymmetricCipherError > ;
54- /// A one-shot API to encrypt some plaintext with the given key.
55- /// This function takes a reference to the output buffer for the ciphertext, and is therefore available in no_std.
56- /// See the documentation for the underlying implementation for details on providing a ciphertext buffer of sufficient size;
57- /// typically the ciphertext is the same length as the plaintext, but some ciphers may have an expansion factor or require
58- /// extra space for a nonce or tag.
59- /// Returns a tuple containing the initialization data and the number of bytes written to the ciphertext buffer.
60- fn encrypt_out (
61- key : & KeyMaterial < KEY_LEN > ,
62- plaintext : & [ u8 ] ,
63- ciphertext : & mut [ u8 ] ,
64- ) -> Result < ( [ u8 ; INIT_DATA_LEN ] , usize ) , SymmetricCipherError > ;
65- #[ cfg ( feature = "std" ) ]
66- /// A one-shot API to decrypt some ciphertext with the given key.
67- /// This function returns the ciphertext as a `Vec<u8>`, and therefore is only available when compiling with std.
68- /// This is not available if building for no_std.
69- fn decrypt (
70- key : & KeyMaterial < KEY_LEN > ,
71- init_data : [ u8 ; INIT_DATA_LEN ] ,
72- ciphertext : & [ u8 ] ,
73- ) -> Result < Vec < u8 > , SymmetricCipherError > ;
74- /// A one-shot API to decrypt some ciphertext with the given key.
75- /// This function takes a reference to the output buffer for the plaintext, and is therefore available in no_std.
76- /// See the documentation for the underlying implementation for details on providing a plaintext buffer of sufficient size;
77- /// typically the ciphertext is the same length as the plaintext, but some ciphers may have an expansion factor or require
78- /// extra space for a nonce or tag.
79- /// Returns a tuple containing the initialization data and the number of bytes written to the plaintext buffer.
80- fn decrypt_out (
81- key : & KeyMaterial < KEY_LEN > ,
82- init_data : [ u8 ; INIT_DATA_LEN ] ,
83- ciphertext : & [ u8 ] ,
84- plaintext : & mut [ u8 ] ,
85- ) -> Result < usize , SymmetricCipherError > ;
86- }
87-
88- /// The basic functions of a block cipher.
89- /// This trait allows for a block cipher to generate initialization data , such as an Initialization Vector ( IV ) or Counter ( CTR )
90- /// which is not technically part of the ciphertext, but must be transmitted along with the ciphertext in order for the
91- /// recipient to perform successful decryption. The length of the initialization data is specified by the implementing struct
92- /// via the `INIT_DATA_LEN` constant.
93- /// In order for these one-shot APIs to be usable securely in all contexts, the init data will be generated
94- /// securely by the block cipher implementation and returned along with the ciphertext, and there is no API for the
95- /// user to provide the init data. If you require this functionality, see the documentation for the underlying implementation.
96- pub trait BlockCipher <const KEY_LEN : usize , const INIT_DATA_LEN : usize , const BLOCK_LEN : usize >:
97- SymmetricCipher <KEY_LEN , INIT_DATA_LEN > + Sized
98- {
99- /// Constructor that begins a flow of the streaming API for encrypting one block at a time.
100- /// Allows for the implementation to return init data such as an IV which is generated prior to encrypting the first block.
101- fn do_encrypt_init(
102- key: & KeyMaterial <KEY_LEN >,
103- ) -> Result <( Self , [ u8 ; INIT_DATA_LEN ] ) , SymmetricCipherError >;
104- /// Encrypts a single block of plaintext.
105- fn do_encrypt_block(
106- & mut self ,
107- plaintext: & [ u8 ; BLOCK_LEN ] ,
108- ) -> Result <[ u8 ; BLOCK_LEN ] , SymmetricCipherError >;
109- /// Encrypts a single block of plaintext and writes the ciphertext to the provided buffer.
110- fn do_encrypt_block_out(
111- & mut self ,
112- plaintext: & [ u8 ; BLOCK_LEN ] ,
113- ciphertext: & mut [ u8 ; BLOCK_LEN ] ,
114- ) -> Result <usize , SymmetricCipherError >;
115- /// Encrypts the final block of plaintext.
116- fn do_encrypt_final(
117- & mut self ,
118- plaintext: & [ u8 ; BLOCK_LEN ] ,
119- ) -> Result <[ u8 ; BLOCK_LEN ] , SymmetricCipherError >;
120- /// Encrypts the final block of plaintext and writes the ciphertext to the provided buffer.
121- fn do_encrypt_final_out(
122- & mut self ,
123- plaintext: & [ u8 ; BLOCK_LEN ] ,
124- ciphertext: & mut [ u8 ; BLOCK_LEN ] ,
125- ) -> Result <usize , SymmetricCipherError >;
126- /// Constructor that begins a flow of the streaming API for decryption one block at a time.
127- fn do_decrypt_init(
128- key: & KeyMaterial <KEY_LEN >,
129- init_data: & [ u8 ; INIT_DATA_LEN ] ,
130- ) -> Result <Self , SymmetricCipherError >;
131- /// Decrypts a single block of ciphertext.
132- fn do_decrypt_block(
133- & mut self ,
134- ciphertext: & [ u8 ; BLOCK_LEN ] ,
135- ) -> Result <[ u8 ; BLOCK_LEN ] , SymmetricCipherError >;
136- /// Decrypts a single block of ciphertext and writes the plaintext to the provided buffer.
137- fn do_decrypt_block_out(
138- & mut self ,
139- ciphertext: & [ u8 ; BLOCK_LEN ] ,
140- plaintext: & mut [ u8 ; BLOCK_LEN ] ,
141- ) -> Result <usize , SymmetricCipherError >;
142- /// Decrypts the final block of ciphertext.
143- /// This is the decryption counterpart to [`BlockCipher::do_encrypt_final`] and is where an
144- /// implementation validates and strips any padding (or otherwise finalizes the flow).
145- fn do_decrypt_final(
146- & mut self ,
147- ciphertext: & [ u8 ; BLOCK_LEN ] ,
148- ) -> Result <[ u8 ; BLOCK_LEN ] , SymmetricCipherError >;
149- /// Decrypts the final block of ciphertext and writes the plaintext to the provided buffer.
150- fn do_decrypt_final_out(
151- & mut self ,
152- ciphertext: & [ u8 ; BLOCK_LEN ] ,
153- plaintext: & mut [ u8 ; BLOCK_LEN ] ,
154- ) -> Result <usize , SymmetricCipherError >;
155- }
156-
157- /// The basic functions of an Authenticated Encryption with Addititional Data cipher.
158- pub trait AEADCipher <const KEY_LEN : usize , const NONCE_LEN : usize , const TAG_LEN : usize >:
159- SymmetricCipher <KEY_LEN , NONCE_LEN > + Sized
160- {
161- #[ cfg( feature = "std") ]
162- /// A one-shot API to encrypt some plaintext with the given key.
163- /// A distinguishing feature of AEAD ciphers is the ability to provide additional authenticated data (AAD)
164- /// that is not encrypted but is protected by the authentication tag; ie it can be sent along with the ciphertext
165- /// and any tampering with it will result in the decryption operation failing the tag check.
166- /// This function returns the ciphertext as a `Vec<u8>`, and therefore is only available when compiling with std.
167- /// Returns a tuple containing a generated nonce, the ciphertext and the tag.
168- fn aead_encrypt(
169- key: & KeyMaterial <KEY_LEN >,
170- aad: & [ u8 ] ,
171- plaintext: & [ u8 ] ,
172- ) -> Result <( [ u8 ; NONCE_LEN ] , Vec <u8 >, [ u8 ; TAG_LEN ] ) , SymmetricCipherError >;
173- /// A one-shot API to encrypt some plaintext with the given key.
174- /// A distinguishing feature of AEAD ciphers is the ability to provide additional authenticated data (AAD)
175- /// that is not encrypted but is protected by the authentication tag; ie it can be sent along with the ciphertext
176- /// and any tampering with it will result in the decryption operation failing the tag check.
177- /// Returns a tuple containing the randomly-generated nonce, number of bytes written to the ciphertext buffer, and the tag.
178- /// If you need a deterministic mode where you feed in the nonce, use the streaming API of [`BlockCipher`]
179- /// or [`StreamCipher`] as appropriate and feed the nonce into the IV field.
180- fn aead_encrypt_out(
181- key: & KeyMaterial <KEY_LEN >,
182- aad: & [ u8 ] ,
183- plaintext: & [ u8 ] ,
184- ciphertext: & mut [ u8 ] ,
185- ) -> Result <( [ u8 ; NONCE_LEN ] , usize , [ u8 ; TAG_LEN ] ) , SymmetricCipherError >;
186- /// All AEAD ciphers will also be either a [`BlockCipher`] or a [`StreamCipher`], and so will already
187- /// have a streaming API.
188- /// This allows you to finish either style of streaming API flow with AEAD specific do_final()
189- /// that computes and returns the authentication tag.
190- fn do_aead_encrypt_final( self ) -> Result <[ u8 ; TAG_LEN ] , SymmetricCipherError >;
191- #[ cfg( feature = "std") ]
192- /// A one-shot API to decrypt some ciphertext with the given key.
193- /// This function returns the ciphertext as a `Vec<u8>`, and therefore is only available when compiling with std.
194- fn aead_decrypt(
195- key: & KeyMaterial <KEY_LEN >,
196- nonce: & [ u8 ; NONCE_LEN ] ,
197- aad: & [ u8 ] ,
198- ciphertext: & [ u8 ] ,
199- tag: & [ u8 ; TAG_LEN ] ,
200- ) -> Result <Vec <u8 >, SymmetricCipherError >;
201- /// A one-shot API to decrypt some ciphertext with the given key.
202- /// This function takes a reference to the output buffer for the plaintext, and is therefore available in no_std.
203- /// See the documentation for the underlying implementation for details on providing a plaintext buffer of sufficient size;
204- /// typically the ciphertext is the same length as the plaintext, but some ciphers may have an expansion factor or require
205- /// extra space for a nonce or tag.
206- /// Returns the number of bytes written to the plaintext buffer.
207- fn aead_decrypt_out(
208- key: & KeyMaterial <KEY_LEN >,
209- nonce: & [ u8 ; NONCE_LEN ] ,
210- aad: & [ u8 ] ,
211- ciphertext: & [ u8 ] ,
212- tag: & [ u8 ; TAG_LEN ] ,
213- plaintext: & mut [ u8 ] ,
214- ) -> Result <usize , SymmetricCipherError >;
215- /// All AEAD ciphers will also be either a [`BlockCipher`] or a [`StreamCipher`], and so will already
216- /// have a streaming API.
217- /// This allows you to finish either style of streaming API flow with AEAD specific do_final()
218- /// that computes and returns the authentication tag.
219- fn do_aead_decrypt_final( self , tag: & [ u8 ; TAG_LEN ] ) -> Result <( ) , SymmetricCipherError >;
220- }
221-
222- /// The basic functions of a stream cipher, which differ from those of a block cipher only in that
223- /// a stream cipher is assumed to have no underlying block size tied to the implementation, and so the caller gets to specify
224- /// the block size for the streaming APIs.
225- pub trait StreamCipher <const KEY_LEN : usize , const INIT_DATA_LEN : usize >:
226- SymmetricCipher <KEY_LEN , INIT_DATA_LEN > + Sized
227- {
228- /// Constructor that begins a flow of the streaming API for encrypting one block at a time.
229- /// Allows for the implementation to return init data such as an IV which is generated prior to encrypting the first block.
230- fn do_stream_encrypt_init(
231- key: & KeyMaterial <KEY_LEN >,
232- ) -> Result <( Self , [ u8 ; INIT_DATA_LEN ] ) , SymmetricCipherError >;
233- /// Encrypts a single block of plaintext.
234- fn do_stream_encrypt_block<const BLOCK_LEN : usize >(
235- & mut self ,
236- plaintext: & [ u8 ; BLOCK_LEN ] ,
237- ) -> Result <[ u8 ; BLOCK_LEN ] , SymmetricCipherError >;
238- /// Encrypts a single block of plaintext and writes the ciphertext to the provided buffer.
239- fn do_stream_encrypt_block_out<const BLOCK_LEN : usize >(
240- & mut self ,
241- plaintext: & [ u8 ; BLOCK_LEN ] ,
242- ciphertext: & mut [ u8 ; BLOCK_LEN ] ,
243- ) -> Result <usize , SymmetricCipherError >;
244- /// Encrypts the final block of plaintext.
245- fn do_stream_encrypt_final<const BLOCK_LEN : usize >(
246- & mut self ,
247- plaintext: & [ u8 ; BLOCK_LEN ] ,
248- ) -> Result <[ u8 ; BLOCK_LEN ] , SymmetricCipherError >;
249- /// Encrypts the final block of plaintext and writes the ciphertext to the provided buffer.
250- fn do_stream_encrypt_final_out<const BLOCK_LEN : usize >(
251- & mut self ,
252- plaintext: & [ u8 ; BLOCK_LEN ] ,
253- ciphertext: & mut [ u8 ; BLOCK_LEN ] ,
254- ) -> Result <usize , SymmetricCipherError >;
255- /// Constructor that begins a flow of the streaming API for decryption one block at a time.
256- fn do_stream_decrypt_init(
257- key: & KeyMaterial <KEY_LEN >,
258- init_data: & [ u8 ; INIT_DATA_LEN ] ,
259- ) -> Result <Self , SymmetricCipherError >;
260- /// Decrypts a single block of ciphertext.
261- fn do_stream_decrypt_block<const BLOCK_LEN : usize >(
262- & mut self ,
263- ciphertext: & [ u8 ; BLOCK_LEN ] ,
264- ) -> Result <[ u8 ; BLOCK_LEN ] , SymmetricCipherError >;
265- /// Decrypts a single block of ciphertext and writes the plaintext to the provided buffer.
266- fn do_stream_decrypt_block_out<const BLOCK_LEN : usize >(
267- & mut self ,
268- ciphertext: & [ u8 ; BLOCK_LEN ] ,
269- plaintext: & mut [ u8 ; BLOCK_LEN ] ,
270- ) -> Result <usize , SymmetricCipherError >;
271- }
272-
273- /// A hash function is a cryptographic primitive that takes an input of any length and produces a fixed-size output.
274- /// Formally : `H : { 0 , 1 } ^* -> { 0 , 1 } ^n`.
275- /// A cryptographic hash function will typically satisfy several security properties, including:
276- /// * Collision resistance: finding two inputs that yield the same output is computationally difficult.
277- /// * Preimage resistance: from a given output, finding an input that generates it is computationally difficult.
278- /// * Second preimage resistance: given an input, finding another input that yields the same output is computationally difficult.
279- pub trait Hash : Algorithm + Default {
280- =======
28125/// An Authenticated Encryption with Associated Data (AEAD) cipher.
28226///
28327/// An AEAD cipher simultaneously provides confidentiality for plaintext and integrity/authenticity
@@ -345,7 +89,6 @@ pub trait AeadCipher {
34589}
34690
34791pub trait Hash : Default {
348- >>>>>>> 3 d44362 ( Added ascon_cmd. rs)
34992 /// The size of the internal block in bits -- needed by functions such as HMAC to compute security parameters.
35093 fn block_bitlen ( & self ) -> usize ;
35194
0 commit comments