Enum Cipher 

pub enum Cipher {
    XChaCha20Poly1305,
    ChaCha20Poly1305,
    Aes256Gcm,
    Aes128Gcm,
    Aes256GcmSiv,
}

A symmetric authenticated cipher.

Every one here is an AEAD: it authenticates as well as encrypts, so there is no way to decrypt without checking integrity first. A plain cipher with no tag is not offered, because using one correctly requires bolting a MAC on in exactly the right order and getting it wrong is silent.

Variants

XChaCha20Poly1305

XChaCha20-Poly1305. The default, and the one to use.

Its 192-bit nonce is large enough that a random nonce per message has no meaningful collision risk, so there is no counter to keep and no state to synchronise between processes.

ChaCha20Poly1305

ChaCha20-Poly1305, as used by TLS.

A 96-bit nonce, which is small enough that random nonces have a real birthday bound — safe for a few billion messages under one key, and a reason to prefer the X variant when you are not constrained by a peer.

Aes256Gcm

AES-256-GCM. For interoperating with something that requires it, or where hardware AES makes it measurably faster.

The same 96-bit nonce caveat as ChaCha20Poly1305, and a harsher failure: repeating a nonce under GCM leaks the authentication key, not just the plaintext relationship.

Aes128Gcm

AES-128-GCM. A shorter key, derived from the same 256-bit key material.

Aes256GcmSiv

AES-256-GCM-SIV — nonce-misuse resistant.

Repeating a nonce here reveals only that two plaintexts were equal, rather than breaking the cipher. Worth choosing when nonces come from somewhere you do not fully control.

Implementations

impl Cipher

pub const ALL: [Cipher; 5]

Every cipher, for a diagnostic listing and for tests.

pub fn id(self) -> &'static str

The short identifier written into a payload.

pub fn from_id(id: &str) -> Option<Self>

The cipher a payload names.

v1 is accepted as an alias for XChaCha20-Poly1305: it is what the first release wrote, before payloads named their algorithm, and those payloads still have to open.

pub fn key_len(self) -> usize

The key length this cipher needs, in bytes.

pub fn nonce_len(self) -> usize

The nonce length this cipher needs, in bytes.

pub fn is_nonce_misuse_resistant(self) -> bool

Whether repeating a nonce is survivable.

pub fn encrypt( self, key: &Key, nonce: &[u8], aad: &[u8], plain: &[u8], ) -> Result<Vec<u8>>

Encrypt plain, authenticating aad alongside it.

pub fn decrypt( self, key: &Key, nonce: &[u8], aad: &[u8], sealed: &[u8], ) -> Result<Vec<u8>>

Decrypt, verifying aad.

Every failure is the same error: a caller can do nothing useful with the difference between “the tag was wrong” and “the length was wrong”, and telling them apart is how padding-oracle attacks start.

pub fn nonce(self) -> Vec<u8>

A fresh nonce of the right length for this cipher.

Trait Implementations

impl Clone for Cipher

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Copy for Cipher

impl Debug for Cipher

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Cipher

fn default() -> Self

Returns the “default value” for a type.

impl Display for Cipher

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Cipher

impl FromStr for Cipher

type Err = Error

The associated error which can be returned from parsing.

fn from_str(value: &str) -> Result<Self>

Parses a string s to return a value of this type.

impl PartialEq for Cipher

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Cipher