77![ Rust Version] [ rustc-image ]
88[ ![ Project Chat] [ chat-image ]] [ chat-link ]
99
10- Pure Rust implementation of the [ Hash-based Message Authentication Code (HMAC)] [ 1 ] .
10+ Generic implementation of [ Hash-based Message Authentication Code (HMAC)] [ 1 ] .
1111
12- [ Documentation] [ docs-link ]
12+ To use it you will need a cryptographic hash function implementation which
13+ implements the [ ` digest ` ] crate traits. You can find compatible crates
14+ (e.g. [ ` sha2 ` ] ) in the [ ` RustCrypto/hashes ` ] repository.
1315
14- ## Minimum Supported Rust Version
16+ This crate provides four HMAC implementations: [ ` Hmac ` ] , [ ` HmacReset ` ] ,
17+ [ ` SimpleHmac ` ] , and [ ` SimpleHmacReset ` ] .
1518
16- Rust ** 1.81** or higher.
19+ The first two types are buffered wrappers around block-level
20+ [ ` block_api::HmacCore ` ] and [ ` block_api::HmacResetCore ` ] types respectively.
21+ Internally they uses efficient state representation, but work only with
22+ hash functions which expose block-level API and consume blocks eagerly
23+ (e.g. they will not work with the BLAKE2 family of hash functions).
1724
18- Minimum supported Rust version can be changed in the future, but it will be
19- done with a minor version bump.
25+ On the other hand, [ ` SimpleHmac ` ] and [ ` SimpleHmacReset ` ] are a bit less
26+ efficient, but work with all hash functions which implement
27+ the [ ` Digest ` ] trait.
2028
21- ## SemVer Policy
29+ [ ` Hmac ` ] and [ ` SimpleHmac ` ] do not support resetting MAC state (i.e. they
30+ do not implement the [ ` Reset ` ] and [ ` FixedOutputReset ` ] traits). Use
31+ [ ` HmacReset ` ] or [ ` SimpleHmacReset ` ] if you want to reuse MAC state.
2232
23- - All on-by-default features of this library are covered by SemVer
24- - MSRV is considered exempt from SemVer as noted above
33+ ## Examples
34+
35+ Let us demonstrate how to use HMAC using the SHA-256 hash function
36+ implemented in the [ ` sha2 ` ] crate.
37+
38+ In the following examples [ ` Hmac ` ] is interchangeable with [ ` SimpleHmac ` ] .
39+
40+ To get authentication code:
41+
42+ ``` rust
43+ use sha2 :: Sha256 ;
44+ use hmac :: {Hmac , KeyInit , Mac };
45+ use hex_literal :: hex;
46+
47+ // Create alias for HMAC-SHA256
48+ type HmacSha256 = Hmac <Sha256 >;
49+
50+ let mut mac = HmacSha256 :: new_from_slice (b " my secret and secure key"
51+ . expect (" HMAC can take key of any size"
52+ mac . update (b " input message"
53+
54+ // `result` has type `CtOutput` which is a thin wrapper around array of
55+ // bytes for providing constant time equality check
56+ let result = mac . finalize ();
57+ // To get underlying array use `into_bytes`, but be careful, since
58+ // incorrect use of the code value may permit timing attacks which defeats
59+ // the security provided by the `CtOutput`
60+ let code_bytes = result . into_bytes ();
61+ let expected = hex! ("
62+ 97d2a569059bbcd8ead4444ff99071f4
63+ c01d005bcefe0d3567e1be628e5fdcd9
64+ "
65+ assert_eq! (code_bytes [.. ], expected [.. ]);
66+ ```
67+
68+ To verify the message:
69+
70+ ``` rust
71+ use sha2 :: Sha256 ;
72+ use hmac :: {Hmac , KeyInit , Mac };
73+ use hex_literal :: hex;
74+
75+ type HmacSha256 = Hmac <Sha256 >;
76+
77+ let mut mac = HmacSha256 :: new_from_slice (b " my secret and secure key"
78+ . expect (" HMAC can take key of any size"
79+
80+ mac . update (b " input message"
81+
82+ let code_bytes = hex! ("
83+ 97d2a569059bbcd8ead4444ff99071f4
84+ c01d005bcefe0d3567e1be628e5fdcd9
85+ "
86+ // `verify_slice` will return `Ok(())` if code is correct, `Err(MacError)` otherwise
87+ mac . verify_slice (& code_bytes [.. ]). unwrap ();
88+ ```
89+
90+ ## Block and input sizes
91+
92+ Usually it is assumed that block size is larger than output size. Due to the
93+ generic nature of the implementation, we must handle cases when this assumption
94+ does not hold. This is done by truncating hash output to the hash
95+ block size if needed.
2596
2697## License
2798
@@ -47,10 +118,24 @@ dual licensed as above, without any additional terms or conditions.
47118[ build-image ] : https://github.com/RustCrypto/MACs/actions/workflows/hmac.yml/badge.svg
48119[ build-link ] : https://github.com/RustCrypto/MACs/actions/workflows/hmac.yml
49120[ license-image ] : https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
50- [ rustc-image ] : https://img.shields.io/badge/rustc-1.81 +-blue.svg
121+ [ rustc-image ] : https://img.shields.io/badge/rustc-1.85 +-blue.svg
51122[ chat-image ] : https://img.shields.io/badge/zulip-join_chat-blue.svg
52123[ chat-link ] : https://rustcrypto.zulipchat.com/#narrow/stream/260044-MACs
53124
54125[ // ] : # ( general links )
55126
56127[ 1 ] : https://en.wikipedia.org/wiki/HMAC
128+ [ `digest` ] : https://docs.rs/digest
129+ [ `sha2` ] : https://docs.rs/sha2
130+ [ `RustCrypto/hashes` ] : https://github.com/RustCrypto/hashes
131+
132+ [ // ] : # ( intra-crate links )
133+ [ `Reset` ] : https://docs.rs/digest/latest/digest/trait.Reset.html
134+ [ `Digest` ] : https://docs.rs/digest/latest/digest/trait.Digest.html
135+ [ `FixedOutputReset` ] : https://docs.rs/digest/latest/digest/trait.FixedOutputReset.html
136+ [ `Hmac` ] : https://docs.rs/hmac/latest/hmac/struct.Hmac.html
137+ [ `HmacReset` ] : https://docs.rs/hmac/latest/hmac/struct.HmacReset.html
138+ [ `SimpleHmac` ] : https://docs.rs/hmac/latest/hmac/struct.SimpleHmac.html
139+ [ `SimpleHmacReset` ] : https://docs.rs/hmac/latest/hmac/struct.SimpleHmacReset.html
140+ [ `block_api::HmacCore` ] : https://docs.rs/hmac/latest/hmac/block_api/struct.HmacCore.html
141+ [ `block_api::HmacResetCore` ] : https://docs.rs/hmac/latest/hmac/block_api/struct.HmacResetCore.html
0 commit comments