updated documentation (#26)

sheroz · Aug 5, 2023 · a6200f2 · a6200f2
1 parent f074cd1
commit a6200f2
Show file tree

Hide file tree

Showing 15 changed files with 83 additions and 53 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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<u8>`
 /// 
-/// 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<u8> {
 
 /// Returns decrypted result as `Vec<u8>`
 /// 
-/// 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
@@ -1,10 +1,12 @@
+//! Implements Cipher Feedback (CFB) mode
+
 use std::collections::VecDeque;
 
 use crate::{magma::Magma, CipherOperation, CipherMode};
 
 /// Returns encrypted result as `Vec<u8>`
 /// 
-/// 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<u8> {
 
 /// Returns decrypted result as `Vec<u8>`
 /// 
-/// 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
@@ -1,8 +1,10 @@
+//! Implements Counter Encryption (CTR) mode
+
 use crate::{magma::Magma, CipherOperation, CipherMode};
 
 /// Returns encrypted result as `Vec<u8>`
 /// 
-/// 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<u8> {
 
 /// Returns decrypted result as `Vec<u8>`
 /// 
-/// 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<u8> {
 
 /// Returns encrypted/decrypted result as `Vec<u8>`
 /// 
-/// 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
@@ -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<u8>`
 /// 
-/// 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<u8> {
 
 /// Returns decrypted result as `Vec<u8>`
 /// 
-/// 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<u8> {
 
 /// Returns encrypted/decrypted as `Vec<u8>`
 /// 
-/// 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
@@ -1,8 +1,10 @@
+//! Implements Electronic Codebook (ECB) mode
+
 use crate::{magma::Magma, CipherOperation, CipherMode};
 
 /// Returns encrypted result as `Vec<u8>`
 /// 
-/// 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<u8> {
 
 /// Returns decrypted result as `Vec<u8>`
 /// 
-/// 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<u8> {
 
 /// Returns encrypted/decrypted result as `Vec<u8>`
 /// 
-/// 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
@@ -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
@@ -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<u8> {
 
 /// Returns decrypted result as `Vec<u8>`
 /// 
-/// 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<u8> {
 
 /// Returns encrypted/decrypted result as `Vec<u8>`
 /// 
-/// 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
@@ -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
@@ -1,3 +1,5 @@
+//! Utility functions
+
 /// Returns splitted into `(u32, u32)` result
 /// 
 /// # Argument