diff options
author | Lars Wirzenius <liw@liw.fi> | 2021-12-31 09:00:21 +0200 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2021-12-31 12:10:10 +0200 |
commit | acf1ba3f8f1492b961c9a6eb09eb93e882f5eb3f (patch) | |
tree | 1ce0288f878cac71990bb01f358d6035f1626c92 /src/cipher.rs | |
parent | 686e87981db210fa443404c8473dfe7a3f39b241 (diff) | |
download | obnam2-acf1ba3f8f1492b961c9a6eb09eb93e882f5eb3f.tar.gz |
docs: add documentation comments to crate
Also, make it an error for a public symbol to not be documented.
Sponsored-by: author
Diffstat (limited to 'src/cipher.rs')
-rw-r--r-- | src/cipher.rs | 27 |
1 files changed, 27 insertions, 0 deletions
diff --git a/src/cipher.rs b/src/cipher.rs index 04b2944..ee7fb8f 100644 --- a/src/cipher.rs +++ b/src/cipher.rs @@ -1,3 +1,5 @@ +//! Encryption cipher algorithms. + use crate::chunk::DataChunk; use crate::chunkmeta::ChunkMeta; use crate::passwords::Passwords; @@ -10,30 +12,43 @@ use std::str::FromStr; const CHUNK_V1: &[u8] = b"0001"; +/// An encrypted chunk. +/// +/// This consists of encrypted ciphertext, and un-encrypted (or +/// cleartext) additional associated data, which could be the metadata +/// of the chunk, and be used to, for example, find chunks. +/// +/// Encrypted chunks are the only chunks that can be uploaded to the +/// server. pub struct EncryptedChunk { ciphertext: Vec<u8>, aad: Vec<u8>, } impl EncryptedChunk { + /// Create an encrypted chunk. fn new(ciphertext: Vec<u8>, aad: Vec<u8>) -> Self { Self { ciphertext, aad } } + /// Return the encrypted data. pub fn ciphertext(&self) -> &[u8] { &self.ciphertext } + /// Return the cleartext associated additional data. pub fn aad(&self) -> &[u8] { &self.aad } } +/// An engine for encrypting and decrypting chunks. pub struct CipherEngine { cipher: Aes256Gcm, } impl CipherEngine { + /// Create a new cipher engine using cleartext passwords. pub fn new(pass: &Passwords) -> Self { let key = GenericArray::from_slice(pass.encryption_key()); Self { @@ -41,6 +56,7 @@ impl CipherEngine { } } + /// Encrypt a chunk. pub fn encrypt_chunk(&self, chunk: &DataChunk) -> Result<EncryptedChunk, CipherError> { // Payload with metadata as associated data, to be encrypted. // @@ -70,6 +86,7 @@ impl CipherEngine { Ok(EncryptedChunk::new(vec, aad)) } + /// Decrypt a chunk. pub fn decrypt_chunk(&self, bytes: &[u8], meta: &[u8]) -> Result<DataChunk, CipherError> { // Does encrypted chunk start with the right version? if !bytes.starts_with(CHUNK_V1) { @@ -109,26 +126,36 @@ fn push_bytes(vec: &mut Vec<u8>, bytes: &[u8]) { } } +/// Possible errors when encrypting or decrypting chunks. #[derive(Debug, thiserror::Error)] pub enum CipherError { + /// Encryption failed. #[error("failed to encrypt with AES-GEM: {0}")] EncryptError(aes_gcm::Error), + /// The encrypted chunk has an unsupported version or is + /// corrupted. #[error("encrypted chunk does not start with correct version")] UnknownChunkVersion, + /// The encrypted chunk lacks a complete nonce value, and is + /// probably corrupted. #[error("encrypted chunk does not have a complete nonce")] NoNonce, + /// Decryption failed. #[error("failed to decrypt with AES-GEM: {0}")] DecryptError(aes_gcm::Error), + /// The decryption succeeded, by data isn't valid YAML. #[error("failed to parse decrypted data as a DataChunk: {0}")] Parse(serde_yaml::Error), + /// Error parsing UTF8 data. #[error(transparent)] Utf8Error(#[from] std::str::Utf8Error), + /// Error parsing JSON data. #[error("failed to parse JSON: {0}")] JsonParse(#[from] serde_json::Error), } |