dbl: seal the Dbl trait and tweak docs (#1198)

Author: newpavlov

dbl/CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 - Migrated from `generic-array` to `hybrid-array` ([#944])
 - Edition changed to 2024 and MSRV bumped to 1.85 ([#1149])
+- Seal the `Dbl` trait ([#1198])
 
 [#944]: https://github.com/RustCrypto/utils/pull/944
 [#1149]: https://github.com/RustCrypto/utils/pull/1149
+[#1198]: https://github.com/RustCrypto/utils/pull/1198

dbl/Cargo.toml

@@ -3,13 +3,14 @@ name = "dbl"
 version = "0.4.0-rc.2"
 authors = ["RustCrypto Developers"]
 license = "MIT OR Apache-2.0"
-description = "Double operation in Galois Field GF(2^128) as used by e.g. CMAC/PMAC"
 documentation = "https://docs.rs/dbl"
 repository = "https://github.com/RustCrypto/utils"
 keywords = ["crypto", "dbl", "gf", "galois"]
 edition = "2024"
 rust-version = "1.85"
 readme = "README.md"
+description = """Double operation in Galois Field `GF(2^128)` using the lexicographically first
+polynomial among the irreducible degree `n` polynomials having a minimum number of coefficients."""
 
 [dependencies]
 hybrid-array = "0.3"

dbl/README.md

@@ -1,4 +1,4 @@
-# [RustCrypto]: GF(2^128) "dbl" operation
+# [RustCrypto]: Double operation in `GF(2^n)`
 
 [![crate][crate-image]][crate-link]
 [![Docs][docs-image]][docs-link]
@@ -7,10 +7,9 @@
 ![Rust Version][rustc-image]
 [![Project Chat][chat-image]][chat-link]
 
-Double operation in Galois Field GF(2^128) as used by e.g. CMAC/PMAC.
-
-Also known as "multiply-by-x", the operation is performed in the finite field
-represented using the primitive polynomial x^128 + x^7 + x^2 + x + 1.
+Double operation (a.k.a. "multiply-by-x") in Galois Field `GF(2^n)` using
+the lexicographically first polynomial among the irreducible degree `n` polynomials
+having a minimum number of coefficients.
 
 ## License
 

dbl/src/lib.rs

@@ -13,11 +13,15 @@ const C64: u64 = 0b1_1011;
 const C128: u64 = 0b1000_0111;
 const C256: u64 = 0b100_0010_0101;
 
-/// Double and inverse double over GF(2^n).
+mod sealed {
+    pub trait Sealed {}
+}
+
+/// Double and inverse double over `GF(2^n)` with the lexicographically first polynomial
+/// among the irreducible degree `n` polynomials having a minimum number of coefficients.
 ///
-/// This trait is implemented for 64, 128 and 256 bit block sizes. Big-endian
-/// order is used.
-pub trait Dbl {
+/// This trait is implemented using big-endian byte order for 64, 128 and 256 bit block sizes.
+pub trait Dbl: sealed::Sealed {
     /// Double block. (alternatively: multiply block by x)
     ///
     /// If most significant bit of the block equals to zero will return
@@ -59,6 +63,8 @@ impl Dbl for Array<u8, U8> {
     }
 }
 
+impl sealed::Sealed for Array<u8, U8> {}
+
 impl Dbl for Array<u8, U16> {
     #[inline]
     fn dbl(self) -> Self {
@@ -104,6 +110,8 @@ impl Dbl for Array<u8, U16> {
     }
 }
 
+impl sealed::Sealed for Array<u8, U16> {}
+
 impl Dbl for Array<u8, U32> {
     #[inline]
     fn dbl(self) -> Self {
@@ -169,3 +177,5 @@ impl Dbl for Array<u8, U32> {
         res
     }
 }
+
+impl sealed::Sealed for Array<u8, U32> {}