Struct Cipher 

pub struct Cipher { /* private fields */ }

A symmetric cipher

Implementations

impl Cipher

pub fn new(name: &str, direction: CipherDirection) -> Result<Cipher>

Create a new cipher object in the specified direction

Examples

let aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();

pub fn algo_name(&self) -> Result<String>

Return the name of this algorithm which may or may not exactly match what was provided to new()

Examples

let cipher = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
assert_eq!(cipher.algo_name().unwrap(), "AES-128/GCM(16)");

pub fn direction(&self) -> Result<CipherDirection>

Return the direction this cipher object is operating in

Examples

let cipher = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
assert_eq!(cipher.direction().unwrap(), botan::CipherDirection::Encrypt);

pub fn valid_nonce_length(&self, l: usize) -> Result<bool>

Query if a particular nonce size is valid for this cipher

Examples

let aes_cbc = botan::Cipher::new("AES-128/CBC", botan::CipherDirection::Encrypt).unwrap();
assert_eq!(aes_cbc.valid_nonce_length(16), Ok(true));
assert_eq!(aes_cbc.valid_nonce_length(1), Ok(false));

pub fn tag_length(&self) -> usize

For an AEAD, return the tag length of the cipher

Examples

let aes_cbc = botan::Cipher::new("AES-128/CBC", botan::CipherDirection::Encrypt).unwrap();
assert_eq!(aes_cbc.tag_length(), 0);
let aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
assert_eq!(aes_gcm.tag_length(), 16);

pub fn update_granularity(&self) -> usize

Return the minimum input size that must be provided

pub fn ideal_update_granularity(&self) -> Option<usize>

Return the ideal input size for best performance

This function returns None if the C++ API does not support this

pub fn default_nonce_length(&self) -> usize

Return the default nonce length for the cipher. Some ciphers only support a single nonce size. Others support variable sizes, but some particular size (typically 96 bits) is handled particularly efficiently.

Examples

let aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
assert_eq!(aes_gcm.default_nonce_length(), 12);

pub fn key_spec(&self) -> Result<KeySpec>

Return information about the key lengths supported by this object

pub fn set_key(&mut self, key: &[u8]) -> Result<()>

Set the key for the cipher

Examples

let mut aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
aes_gcm.set_key(&vec![0; 16]).unwrap();

pub fn set_associated_data(&mut self, ad: &[u8]) -> Result<()>

Set the associated data for the cipher. This only works for AEAD modes. The key must already be set to set the AD.

Examples

let mut aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
aes_gcm.set_key(&vec![0; 16]).unwrap();
aes_gcm.set_associated_data(&[1,2,3]).unwrap();

pub fn process(&mut self, nonce: &[u8], msg: &[u8]) -> Result<Vec<u8>>

Encrypt or decrypt a message with the provided nonce. The key must already have been set.

Examples

let mut aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
aes_gcm.set_key(&vec![0; 16]).unwrap();
let nonce = vec![0; aes_gcm.default_nonce_length()];
let msg = vec![0; 48];
let ctext = aes_gcm.process(&nonce, &msg).unwrap();
assert_eq!(ctext.len(), msg.len() + aes_gcm.tag_length());

pub fn start(&mut self, nonce: &[u8]) -> Result<()>

start processing a message

Examples

let mut aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
aes_gcm.set_key(&vec![0; 16]).unwrap();
let nonce = vec![0; aes_gcm.default_nonce_length()];
let msg = vec![0; 48];
aes_gcm.start(&nonce).unwrap();
let ctext = aes_gcm.finish(&msg).unwrap();
assert_eq!(ctext.len(), msg.len() + aes_gcm.tag_length());

pub fn update(&mut self, msg: &[u8]) -> Result<Vec<u8>>

incremental update

Examples

let mut aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
aes_gcm.set_key(&vec![0; 16]).unwrap();
let nonce = vec![0; aes_gcm.default_nonce_length()];
let msg = vec![0; 96];
aes_gcm.start(&nonce).unwrap();
let mut ctext = vec![];
ctext.extend_from_slice(&aes_gcm.update(&msg[..64]).unwrap());
ctext.extend_from_slice(&aes_gcm.finish(&msg[64..]).unwrap());
assert_eq!(ctext.len(), msg.len() + aes_gcm.tag_length());

pub fn update_into(&mut self, msg: &[u8], output: &mut [u8]) -> Result<usize>

incremental update writing into the given buffer

The length of output has to be at least msg.len(). Returns the number of bytes written to output.

Examples

let mut aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
aes_gcm.set_key(&vec![0; 16]).unwrap();
let nonce = vec![0; aes_gcm.default_nonce_length()];
let msg = vec![0; 96];
aes_gcm.start(&nonce).unwrap();
let mut ctext = vec![0; msg.len() + aes_gcm.tag_length()];
let mut written = 0;
written += aes_gcm.update_into(&msg[..64], &mut ctext[written..]).unwrap();
written += aes_gcm.finish_into(&msg[64..], &mut ctext[written..]).unwrap();
assert_eq!(written, msg.len() + aes_gcm.tag_length());

pub fn finish(&mut self, msg: &[u8]) -> Result<Vec<u8>>

finish function

Examples

let mut aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
aes_gcm.set_key(&vec![0; 16]).unwrap();
let nonce = vec![0; aes_gcm.default_nonce_length()];
let msg = vec![0; 48];
aes_gcm.start(&nonce).unwrap();
let ctext = aes_gcm.finish(&msg).unwrap();
assert_eq!(ctext.len(), msg.len() + aes_gcm.tag_length());

pub fn finish_into(&mut self, msg: &[u8], output: &mut [u8]) -> Result<usize>

finish function writing into the given buffer

The length of output has to be at least msg.len() - self.tag_length() for decryption, and msg.len() + self.tag_length() for encryption. Returns the number of bytes written to output.

Examples

let mut aes_gcm = botan::Cipher::new("AES-128/GCM", botan::CipherDirection::Encrypt).unwrap();
aes_gcm.set_key(&vec![0; 16]).unwrap();
let nonce = vec![0; aes_gcm.default_nonce_length()];
let msg = vec![0; 96];
aes_gcm.start(&nonce).unwrap();
let mut ctext = vec![0; msg.len() + aes_gcm.tag_length()];
let written = aes_gcm.finish_into(&msg, &mut ctext[..]).unwrap();
assert_eq!(written, msg.len() + aes_gcm.tag_length());

pub fn clear(&mut self) -> Result<()>

Clear all state associated with the key

Trait Implementations

impl Debug for Cipher

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

Formats the value using the given formatter.

impl Drop for Cipher

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Cipher

impl Sync for Cipher