diff --git a/CHANGELOG.md b/CHANGELOG.md index 6df7657..7288583 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,15 +2,15 @@ All notable changes to this project will be documented in this file. -## 0.7.0 (2023-08-05) +## 0.7.1 (2023-08-05) -### Added +- Updated documentation -- Support for streaming -- File encryption sample +## 0.7.0 (2023-08-05) -## 0.6.3 (2023-07-27) +- Added support for streaming +- Added file encryption sample -### Updated +## 0.6.3 (2023-07-27) - Updated documentation diff --git a/cipher_magma/CHANGELOG.md b/cipher_magma/CHANGELOG.md index 6d35ca2..7288583 100644 --- a/cipher_magma/CHANGELOG.md +++ b/cipher_magma/CHANGELOG.md @@ -2,6 +2,15 @@ All notable changes to this project will be documented in this file. +## 0.7.1 (2023-08-05) + +- Updated documentation + +## 0.7.0 (2023-08-05) + +- Added support for streaming +- Added file encryption sample + ## 0.6.3 (2023-07-27) -* Updated documentation +- Updated documentation diff --git a/cipher_magma/Cargo.toml b/cipher_magma/Cargo.toml index 760a657..da16248 100644 --- a/cipher_magma/Cargo.toml +++ b/cipher_magma/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "cipher_magma" -version = "0.7.0" +version = "0.7.1" edition = "2021" authors = ["Sheroz Khaydarov"] description = "Block Cipher Magma (GOST R 34.12-2015, former GOST 28147-89)" diff --git a/cipher_magma/src/lib.rs b/cipher_magma/src/lib.rs index 4367ade..f76bd8c 100644 --- a/cipher_magma/src/lib.rs +++ b/cipher_magma/src/lib.rs @@ -1,3 +1,19 @@ +//! Block Cipher "Magma" +//! +//! Implemented and tested according to specifications: +//! 1. [RFC 8891](https://datatracker.ietf.org/doc/html/rfc8891.html) a.k.a **GOST R 34.12-2015** +//! 2. [RFC 5830](https://datatracker.ietf.org/doc/html/rfc5830) a.k.a **GOST 28147-89** +//! 3. Block Cipher Modes: [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) +//! +//! [Cipher Modes](https://tc26.ru/standard/gost/GOST_R_3413-2015.pdf) +//! * **ECB** - Electronic Codebook Mode +//! * **CTR** - Counter Encryption Mode +//! * **CTR-ACPKM** - Counter Encryption Mode as per [RFC8645](https://www.rfc-editor.org/rfc/rfc8645.html), [P 1323565.1.017— 2018](https://standartgost.ru/g/%D0%A0_1323565.1.017-2018) +//! * **OFB** - Output Feedback Mode +//! * **CBC** - Cipher Block Chaining Mode +//! * **CFB** - Cipher Feedback Mode +//! * **MAC** - Message Authentication Code Generation Mode + pub mod magma; // re-export the magma core diff --git a/cipher_magma/src/magma.rs b/cipher_magma/src/magma.rs index 1f302c3..a7ca72b 100644 --- a/cipher_magma/src/magma.rs +++ b/cipher_magma/src/magma.rs @@ -1,8 +1,8 @@ -//! **Block Cipher "Magma"** +//! Block Cipher "Magma" //! //! Implemented and tested according to specifications: -//! 1. [RFC 8891](https://datatracker.ietf.org/doc/html/rfc8891.html) a.k.a GOST R 34.12-2015 -//! 2. [RFC 5830](https://datatracker.ietf.org/doc/html/rfc5830) a.k.a GOST 28147-89 +//! 1. [RFC 8891](https://datatracker.ietf.org/doc/html/rfc8891.html) a.k.a **GOST R 34.12-2015** +//! 2. [RFC 5830](https://datatracker.ietf.org/doc/html/rfc5830) a.k.a **GOST 28147-89** //! 3. Block Cipher Modes: [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) //! //! [Cipher Modes](https://tc26.ru/standard/gost/GOST_R_3413-2015.pdf) @@ -14,19 +14,6 @@ //! * **CFB** - Cipher Feedback Mode //! * **MAC** - Message Authentication Code Generation Mode -/* - RFC 5831: GOST R 34.11-94 - hash function: - https://datatracker.ietf.org/doc/rfc5831/ - https://datatracker.ietf.org/doc/html/rfc4357 - https://en.wikipedia.org/wiki/GOST_(hash_function) - - GOST R 34.11-94 - GOST 34.311-95 - GOST hash function - GOST 28147-89 IMIT -*/ - pub mod cipher_mode; pub mod cipher_operation; pub mod utils; diff --git a/cipher_magma/src/magma/cipher_mode.rs b/cipher_magma/src/magma/cipher_mode.rs index cb9c8d1..7dcc5e3 100644 --- a/cipher_magma/src/magma/cipher_mode.rs +++ b/cipher_magma/src/magma/cipher_mode.rs @@ -1,3 +1,15 @@ +//! Cipher Mode +//! +//! [Cipher Modes](https://tc26.ru/standard/gost/GOST_R_3413-2015.pdf) +//! +//! * **ECB** - Electronic Codebook Mode +//! * **CTR** - Counter Encryption Mode +//! * **CTR-ACPKM** - Counter Encryption Mode as per [RFC8645](https://www.rfc-editor.org/rfc/rfc8645.html), [P 1323565.1.017— 2018](https://standartgost.ru/g/%D0%A0_1323565.1.017-2018) +//! * **OFB** - Output Feedback Mode +//! * **CBC** - Cipher Block Chaining Mode +//! * **CFB** - Cipher Feedback Mode +//! * **MAC** - Message Authentication Code Generation Mode + pub mod ecb; pub mod ctr; pub mod ctr_acpkm; @@ -6,17 +18,7 @@ pub mod cbc; pub mod cfb; pub mod mac; -/// **Cipher Mode** -/// -/// [Cipher Modes](https://tc26.ru/standard/gost/GOST_R_3413-2015.pdf) -/// -/// * **ECB** - Electronic Codebook Mode -/// * **CTR** - Counter Encryption Mode -/// * **CTR-ACPKM** - Counter Encryption Mode as per [RFC8645](https://www.rfc-editor.org/rfc/rfc8645.html), [P 1323565.1.017— 2018](https://standartgost.ru/g/%D0%A0_1323565.1.017-2018) -/// * **OFB** - Output Feedback Mode -/// * **CBC** - Cipher Block Chaining Mode -/// * **CFB** - Cipher Feedback Mode -/// * **MAC** - Message Authentication Code Generation Mode +/// Cipher Mode #[derive(PartialEq, Clone)] pub enum CipherMode { /// Electronic Codebook (ECB) Mode diff --git a/cipher_magma/src/magma/cipher_mode/cbc.rs b/cipher_magma/src/magma/cipher_mode/cbc.rs index 0e7a188..12b5748 100644 --- a/cipher_magma/src/magma/cipher_mode/cbc.rs +++ b/cipher_magma/src/magma/cipher_mode/cbc.rs @@ -1,10 +1,12 @@ +//! Implements Cipher Block Chaining (CBC) mode + use std::collections::VecDeque; use crate::{magma::Magma, CipherOperation, CipherMode}; /// Returns encrypted result as `Vec` /// -/// Implements buffer encrypting in Cipher Block Chaining (CBC) Mode +/// Implements buffer encrypting in Cipher Block Chaining (CBC) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// @@ -42,7 +44,7 @@ pub fn encrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns decrypted result as `Vec` /// -/// Implements buffer decrypting in Cipher Block Chaining (CBC) Mode +/// Implements buffer decrypting in Cipher Block Chaining (CBC) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// diff --git a/cipher_magma/src/magma/cipher_mode/cfb.rs b/cipher_magma/src/magma/cipher_mode/cfb.rs index ec31e0a..a07b253 100644 --- a/cipher_magma/src/magma/cipher_mode/cfb.rs +++ b/cipher_magma/src/magma/cipher_mode/cfb.rs @@ -1,10 +1,12 @@ +//! Implements Cipher Feedback (CFB) mode + use std::collections::VecDeque; use crate::{magma::Magma, CipherOperation, CipherMode}; /// Returns encrypted result as `Vec` /// -/// Implements buffer encrypting in Cipher Feedback (CFB) Mode +/// Implements buffer encrypting in Cipher Feedback (CFB) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// @@ -41,7 +43,7 @@ pub fn encrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns decrypted result as `Vec` /// -/// Implements buffer encrypting in Cipher Feedback (CFB) Mode +/// Implements buffer encrypting in Cipher Feedback (CFB) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// diff --git a/cipher_magma/src/magma/cipher_mode/ctr.rs b/cipher_magma/src/magma/cipher_mode/ctr.rs index 553fd6f..adf9d2e 100644 --- a/cipher_magma/src/magma/cipher_mode/ctr.rs +++ b/cipher_magma/src/magma/cipher_mode/ctr.rs @@ -1,8 +1,10 @@ +//! Implements Counter Encryption (CTR) mode + use crate::{magma::Magma, CipherOperation, CipherMode}; /// Returns encrypted result as `Vec` /// -/// Implements buffer encrypting in Counter Encryption (CTR) Mode +/// Implements buffer encrypting in Counter Encryption (CTR) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// @@ -14,7 +16,7 @@ pub fn encrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns decrypted result as `Vec` /// -/// Implements buffer decrypting in Counter Encryption (CTR) Mode +/// Implements buffer decrypting in Counter Encryption (CTR) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// @@ -26,7 +28,7 @@ pub fn decrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns encrypted/decrypted result as `Vec` /// -/// Implements Counter Encryption (CTR) Mode +/// Implements the core Counter Encryption (CTR) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// diff --git a/cipher_magma/src/magma/cipher_mode/ctr_acpkm.rs b/cipher_magma/src/magma/cipher_mode/ctr_acpkm.rs index 64a08ef..43ec7ce 100644 --- a/cipher_magma/src/magma/cipher_mode/ctr_acpkm.rs +++ b/cipher_magma/src/magma/cipher_mode/ctr_acpkm.rs @@ -1,9 +1,11 @@ +//! Implements Counter Encryption (CTR_ACPKM) mode + use crate::magma::{Magma, CipherOperation}; use crate::magma::cipher_mode::CipherMode; /// Returns encrypted result as `Vec` /// -/// Implements buffer encrypting in Counter Encryption (CTR_ACPKM) Mode +/// Implements buffer encrypting in Counter Encryption (CTR_ACPKM) mode /// /// [RFC8645](https://www.rfc-editor.org/rfc/rfc8645.html#section-6.2.2) /// @@ -16,7 +18,7 @@ pub fn encrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns decrypted result as `Vec` /// -/// Implements buffer decrypting in Counter Encryption (CTR_ACPKM) Mode +/// Implements buffer decrypting in Counter Encryption (CTR_ACPKM) mode /// /// [RFC8645](https://www.rfc-editor.org/rfc/rfc8645.html#section-6.2.2) /// @@ -29,7 +31,7 @@ pub fn decrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns encrypted/decrypted as `Vec` /// -/// Implements Counter Encryption (CTR_ACPKM) Mode +/// Implements the core of Counter Encryption (CTR_ACPKM) mode /// /// [RFC8645](https://www.rfc-editor.org/rfc/rfc8645.html#section-6.2.2) /// diff --git a/cipher_magma/src/magma/cipher_mode/ecb.rs b/cipher_magma/src/magma/cipher_mode/ecb.rs index f0147e9..e5fd475 100644 --- a/cipher_magma/src/magma/cipher_mode/ecb.rs +++ b/cipher_magma/src/magma/cipher_mode/ecb.rs @@ -1,8 +1,10 @@ +//! Implements Electronic Codebook (ECB) mode + use crate::{magma::Magma, CipherOperation, CipherMode}; /// Returns encrypted result as `Vec` /// -/// Implements buffer encrypting in Electronic Codebook (ECB) Mode +/// Implements buffer encrypting in Electronic Codebook (ECB) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// @@ -16,7 +18,7 @@ pub fn encrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns decrypted result as `Vec` /// -/// Implements buffer decrypting in Electronic Codebook (ECB) Mode +/// Implements buffer decrypting in Electronic Codebook (ECB) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// @@ -30,7 +32,7 @@ pub fn decrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns encrypted/decrypted result as `Vec` /// -/// Implements Electronic Codebook (ECB) Mode +/// Implements the core of Electronic Codebook (ECB) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// diff --git a/cipher_magma/src/magma/cipher_mode/mac.rs b/cipher_magma/src/magma/cipher_mode/mac.rs index d3523d4..c38fd83 100644 --- a/cipher_magma/src/magma/cipher_mode/mac.rs +++ b/cipher_magma/src/magma/cipher_mode/mac.rs @@ -1,9 +1,11 @@ +//! Implements Message Authentication Code (MAC) + use crate::{ magma::{utils, Magma}, CipherMode, CipherOperation, }; -/// Returns the Message Authentication Code (MAC) value +/// Returns the Message Authentication Code (MAC) /// /// # Arguments /// * core - a mutable reference to `Magma` @@ -72,7 +74,7 @@ pub fn update(core: &mut Magma, msg_buf: &[u8]) { core.context.feedback.block = Some(feedback); } -/// Finalizes the current context and returns the Message Authentication Code (MAC) value +/// Finalizes the current context and returns the Message Authentication Code (MAC) /// /// # Arguments /// * core - a mutable reference to `Magma` diff --git a/cipher_magma/src/magma/cipher_mode/ofb.rs b/cipher_magma/src/magma/cipher_mode/ofb.rs index 9576679..bcb9da7 100644 --- a/cipher_magma/src/magma/cipher_mode/ofb.rs +++ b/cipher_magma/src/magma/cipher_mode/ofb.rs @@ -1,3 +1,5 @@ +//! Implements Output Feedback (OFB) mode + use std::collections::VecDeque; use crate::{magma::Magma, CipherOperation, CipherMode}; @@ -16,7 +18,7 @@ pub fn encrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns decrypted result as `Vec` /// -/// Implements buffer decrypting in Output Feedback (OFB) Mode +/// Implements buffer decrypting in Output Feedback (OFB) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// @@ -28,7 +30,7 @@ pub fn decrypt(core: &mut Magma, buf: &[u8]) -> Vec { /// Returns encrypted/decrypted result as `Vec` /// -/// Implements Output Feedback (OFB) Mode +/// Implements the core of Output Feedback (OFB) mode /// /// [GOST R 34.13-2015](https://www.tc26.ru/standard/gost/GOST_R_3413-2015.pdf) /// diff --git a/cipher_magma/src/magma/cipher_operation.rs b/cipher_magma/src/magma/cipher_operation.rs index 0006a6f..015077e 100644 --- a/cipher_magma/src/magma/cipher_operation.rs +++ b/cipher_magma/src/magma/cipher_operation.rs @@ -1,4 +1,4 @@ -/// **Cipher operation** +//! Cipher operation #[derive(PartialEq, Clone)] pub enum CipherOperation { /// Encrypting operation diff --git a/cipher_magma/src/magma/utils.rs b/cipher_magma/src/magma/utils.rs index 72ee7b0..9cb9598 100644 --- a/cipher_magma/src/magma/utils.rs +++ b/cipher_magma/src/magma/utils.rs @@ -1,3 +1,5 @@ +//! Utility functions + /// Returns splitted into `(u32, u32)` result /// /// # Argument