[−][src]Module orion::hazardous::aead::streaming
Streaming AEAD based on XChaCha20Poly1305.
About:
This implementation is based on and compatible with the "secretstream" API of libsodium.
Parameters:
secret_key
: The secret key.nonce
: The nonce value.ad
: Additional data to authenticate (this is not encrypted and can beNone
).plaintext
: The data to be encrypted.ciphertext
: The encrypted data with, a Poly1305 tag and aStreamTag
indicating its function.dst_out
: Destination array that will hold theciphertext
/plaintext
after encryption/decryption.tag
: Indicates the type of message. Thetag
is a part of the output when encrypting. It is encrypted and authenticated.
Errors:
An error will be returned if:
- The length of
dst_out
is less thanplaintext
+ABYTES
when callingseal_chunk()
. - The length of
dst_out
is less thanciphertext
-ABYTES
when callingopen_chunk()
. - The length of the
ciphertext
is less thanABYTES
. - The received mac does not match the calculated mac when calling
open_chunk()
. This can indicate a dropped or reordered message within the stream. - More than
2^32-3 * 64
bytes of data are processed when sealing/opening a single chunk. ABYTES
+plaintext.len()
overflows when encrypting.
Panics:
A panic will occur if:
- 64 + (
ciphertext.len()
-ABYTES
) overflowsu64::max_value()
when decrypting.
Security:
- It is critical for security that a given nonce is not re-used with a given key.
- The nonce can be randomly generated using a CSPRNG.
Nonce::generate()
can be used for this. - To securely generate a strong key, use
SecretKey::generate()
. - The lengths of the messages are not hidden, only their contents.
- It is recommended to use
StreamTag::FINISH
as the tag for the last message. This allows the decrypting side to detect if messages at the end of the stream are lost.
Example:
use orion::hazardous::aead::streaming::*; let secret_key = SecretKey::generate(); let nonce = Nonce::generate(); let ad = "Additional data".as_bytes(); let message = "Data to protect".as_bytes(); // Length of the above message is 15 and then we accommodate 17 // for the mac and tag. let mut dst_out_ct = [0u8; 15 + ABYTES]; let mut dst_out_pt = [0u8; 15]; let mut ctx_enc = StreamXChaCha20Poly1305::new(&secret_key, &nonce); // Encrypt and place tag + ciphertext + mac in dst_out_ct ctx_enc.seal_chunk(message, Some(ad), &mut dst_out_ct, StreamTag::MESSAGE)?; let mut ctx_dec = StreamXChaCha20Poly1305::new(&secret_key, &nonce); // Decrypt and save the tag the message was encrypted with. let tag = ctx_dec.open_chunk(&dst_out_ct, Some(ad), &mut dst_out_pt)?; assert_eq!(tag, StreamTag::MESSAGE); assert_eq!(dst_out_pt.as_ref(), message);
Re-exports
pub use crate::hazardous::stream::chacha20::SecretKey; |
pub use crate::hazardous::stream::xchacha20::Nonce; |
Structs
StreamXChaCha20Poly1305 | Streaming XChaCha20Poly1305 state. |
Enums
StreamTag | Tag that indicates the type of message. |
Constants
ABYTES | Size of additional data appended to each message. |
TAG_SIZE | The size of a StreamTag. |