1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163
//! [`ChaCha20Poly1305`] ([RFC 8439][1]) is an //! [Authenticated Encryption with Associated Data (AEAD)][2] //! cipher amenable to fast, constant-time implementations in software, based on //! the [ChaCha20][3] stream cipher and [Poly1305][4] universal hash function. //! //! This crate also contains an implementation of [`XChaCha20Poly1305`] - //! a variant of ChaCha20Poly1305 with an extended 192-bit (24-byte) nonce. //! //! ## Security Warning //! //! No security audits of this crate have ever been performed, and it has not been //! thoroughly assessed to ensure its operation is constant-time on common CPU //! architectures. //! //! Where possible the implementation uses constant-time hardware intrinsics, //! or otherwise falls back to an implementation which contains no secret-dependent //! branches or table lookups, however it's possible LLVM may insert such //! operations in certain scenarios. //! //! # Usage //! //! ``` //! use chacha20poly1305::ChaCha20Poly1305; // Or `XChaCha20Poly1305` //! use aead::{Aead, NewAead, generic_array::GenericArray}; //! //! let key = GenericArray::clone_from_slice(b"an example very very secret key."); // 32-bytes //! let aead = ChaCha20Poly1305::new(key); //! //! let nonce = GenericArray::from_slice(b"unique nonce"); // 12-bytes; unique per message //! let ciphertext = aead.encrypt(nonce, b"plaintext message".as_ref()).expect("encryption failure!"); //! let plaintext = aead.decrypt(nonce, ciphertext.as_ref()).expect("decryption failure!"); //! assert_eq!(&plaintext, b"plaintext message"); //! ``` //! //! ## In-place Usage (eliminates `alloc` requirement) //! //! This crate has an optional `alloc` feature which can be disabled in e.g. //! microcontroller environments that don't have a heap. //! //! The [`Aead::encrypt_in_place`][5] and [`Aead::decrypt_in_place`][6] //! methods accept any type that impls the [`aead::Buffer`][7] trait which //! contains the plaintext for encryption or ciphertext for decryption. //! //! Note that if you enable the `heapless` feature of this crate, //! you will receive an impl of `aead::Buffer` for [`heapless::Vec`][8] //! (re-exported from the `aead` crate as `aead::heapless::Vec`), //! which can then be passed as the `buffer` parameter to the in-place encrypt //! and decrypt methods: //! //! ``` //! use chacha20poly1305::ChaCha20Poly1305; // Or `XChaCha20Poly1305` //! use aead::{Aead, NewAead}; //! use aead::generic_array::{GenericArray, typenum::U128}; //! use aead::heapless::Vec; //! //! let key = GenericArray::clone_from_slice(b"an example very very secret key."); //! let aead = ChaCha20Poly1305::new(key); //! //! let nonce = GenericArray::from_slice(b"unique nonce"); // 128-bits; unique per message //! //! let mut buffer: Vec<u8, U128> = Vec::new(); //! buffer.extend_from_slice(b"plaintext message"); //! //! // Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext //! aead.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!"); //! //! // `buffer` now contains the message ciphertext //! assert_ne!(&buffer, b"plaintext message"); //! //! // Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext //! aead.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!"); //! assert_eq!(&buffer, b"plaintext message"); //! ``` //! //! [1]: https://tools.ietf.org/html/rfc8439 //! [2]: https://en.wikipedia.org/wiki/Authenticated_encryption //! [3]: https://github.com/RustCrypto/stream-ciphers/tree/master/chacha20 //! [4]: https://github.com/RustCrypto/universal-hashes/tree/master/poly1305 //! [5]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.encrypt_in_place //! [6]: https://docs.rs/aead/latest/aead/trait.Aead.html#method.decrypt_in_place //! [7]: https://docs.rs/aead/latest/aead/trait.Buffer.html //! [8]: https://docs.rs/heapless/latest/heapless/struct.Vec.html #![no_std] #![doc(html_logo_url = "https://raw.githubusercontent.com/RustCrypto/meta/master/logo_small.png")] #![warn(missing_docs, rust_2018_idioms, intra_doc_link_resolution_failure)] mod cipher; #[cfg(feature = "xchacha20poly1305")] mod xchacha20poly1305; pub use aead; #[cfg(feature = "xchacha20poly1305")] pub use xchacha20poly1305::XChaCha20Poly1305; use self::cipher::Cipher; use aead::generic_array::{ typenum::{U0, U12, U16, U32}, GenericArray, }; use aead::{Aead, Error, NewAead}; use chacha20::{stream_cipher::NewStreamCipher, ChaCha20}; use zeroize::Zeroize; /// Poly1305 tags pub type Tag = GenericArray<u8, U16>; /// ChaCha20Poly1305 Authenticated Encryption with Additional Data (AEAD). /// /// The [`Aead`] and [`NewAead`] traits provide the primary API for using this /// construction. /// /// See the [toplevel documentation](https://docs.rs/chacha20poly1305) for /// a usage example. #[derive(Clone)] pub struct ChaCha20Poly1305 { /// Secret key key: GenericArray<u8, U32>, } impl NewAead for ChaCha20Poly1305 { type KeySize = U32; fn new(key: GenericArray<u8, U32>) -> Self { ChaCha20Poly1305 { key } } } impl Aead for ChaCha20Poly1305 { type NonceSize = U12; type TagSize = U16; type CiphertextOverhead = U0; fn encrypt_in_place_detached( &self, nonce: &GenericArray<u8, Self::NonceSize>, associated_data: &[u8], buffer: &mut [u8], ) -> Result<Tag, Error> { Cipher::new(ChaCha20::new(&self.key, nonce)) .encrypt_in_place_detached(associated_data, buffer) } fn decrypt_in_place_detached( &self, nonce: &GenericArray<u8, Self::NonceSize>, associated_data: &[u8], buffer: &mut [u8], tag: &Tag, ) -> Result<(), Error> { Cipher::new(ChaCha20::new(&self.key, nonce)).decrypt_in_place_detached( associated_data, buffer, tag, ) } } impl Drop for ChaCha20Poly1305 { fn drop(&mut self) { self.key.as_mut_slice().zeroize(); } }