1//! The message digest context.
2//!
3//! # Examples
4//!
5//! Compute the SHA256 checksum of data
6//!
7//! ```
8//! use openssl::md::Md;
9//! use openssl::md_ctx::MdCtx;
10//!
11//! let mut ctx = MdCtx::new().unwrap();
12//! ctx.digest_init(Md::sha256()).unwrap();
13//! ctx.digest_update(b"Some Crypto Text").unwrap();
14//! let mut digest = [0; 32];
15//! ctx.digest_final(&mut digest).unwrap();
16//!
17//! assert_eq!(
18//!     digest,
19//!     *b"\x60\x78\x56\x38\x8a\xca\x5c\x51\x83\xc4\xd1\x4d\xc8\xf9\xcc\xf2\
20//!        \xa5\x21\xb3\x10\x93\x72\xfa\xd6\x7c\x55\xf5\xc9\xe3\xd1\x83\x19",
21//! );
22//! ```
23//!
24//! Sign and verify data with RSA and SHA256
25//!
26//! ```
27//! use openssl::md::Md;
28//! use openssl::md_ctx::MdCtx;
29//! use openssl::pkey::PKey;
30//! use openssl::rsa::Rsa;
31//!
32//! // Generate a random RSA key.
33//! let key = Rsa::generate(4096).unwrap();
34//! let key = PKey::from_rsa(key).unwrap();
35//!
36//! let text = b"Some Crypto Text";
37//!
38//! // Create the signature.
39//! let mut ctx = MdCtx::new().unwrap();
40//! ctx.digest_sign_init(Some(Md::sha256()), &key).unwrap();
41//! ctx.digest_sign_update(text).unwrap();
42//! let mut signature = vec![];
43//! ctx.digest_sign_final_to_vec(&mut signature).unwrap();
44//!
45//! // Verify the signature.
46//! let mut ctx = MdCtx::new().unwrap();
47//! ctx.digest_verify_init(Some(Md::sha256()), &key).unwrap();
48//! ctx.digest_verify_update(text).unwrap();
49//! let valid = ctx.digest_verify_final(&signature).unwrap();
50//! assert!(valid);
51//! ```
52//!
53
54#![cfg_attr(
55    not(boringssl),
56    doc = r#"\
57Compute and verify an HMAC-SHA256
58
59```
60use openssl::md::Md;
61use openssl::md_ctx::MdCtx;
62use openssl::memcmp;
63use openssl::pkey::PKey;
64
65// Create a key with the HMAC secret.
66let key = PKey::hmac(b"my secret").unwrap();
67
68let text = b"Some Crypto Text";
69
70// Compute the HMAC.
71let mut ctx = MdCtx::new().unwrap();
72ctx.digest_sign_init(Some(Md::sha256()), &key).unwrap();
73ctx.digest_sign_update(text).unwrap();
74let mut hmac = vec![];
75ctx.digest_sign_final_to_vec(&mut hmac).unwrap();
76
77// Verify the HMAC. You can't use MdCtx to do this; instead use a constant time equality check.
78# let target = hmac.clone();
79let valid = memcmp::eq(&hmac, &target);
80assert!(valid);
81```"#
82)]
83
84use crate::error::ErrorStack;
85use crate::md::MdRef;
86use crate::pkey::{HasPrivate, HasPublic, PKeyRef};
87use crate::pkey_ctx::PkeyCtxRef;
88use crate::{cvt, cvt_n, cvt_p};
89use cfg_if::cfg_if;
90use foreign_types::{ForeignType, ForeignTypeRef};
91use openssl_macros::corresponds;
92use std::convert::TryFrom;
93use std::ptr;
94
95cfg_if! {
96    if #[cfg(any(ossl110, boringssl))] {
97        use ffi::{EVP_MD_CTX_free, EVP_MD_CTX_new};
98    } else {
99        use ffi::{EVP_MD_CTX_create as EVP_MD_CTX_new, EVP_MD_CTX_destroy as EVP_MD_CTX_free};
100    }
101}
102
103foreign_type_and_impl_send_sync! {
104    type CType = ffi::EVP_MD_CTX;
105    fn drop = EVP_MD_CTX_free;
106
107    pub struct MdCtx;
108    /// A reference to an [`MdCtx`].
109    pub struct MdCtxRef;
110}
111
112impl MdCtx {
113    /// Creates a new context.
114    #[corresponds(EVP_MD_CTX_new)]
115    #[inline]
116    pub fn new() -> Result<Self, ErrorStack> {
117        ffi::init();
118
119        unsafe {
120            let ptr = cvt_p(EVP_MD_CTX_new())?;
121            Ok(MdCtx::from_ptr(ptr))
122        }
123    }
124}
125
126impl MdCtxRef {
127    /// Initializes the context to compute the digest of data.
128    #[corresponds(EVP_DigestInit_ex)]
129    #[inline]
130    pub fn digest_init(&mut self, digest: &MdRef) -> Result<(), ErrorStack> {
131        unsafe {
132            cvt(ffi::EVP_DigestInit_ex(
133                self.as_ptr(),
134                digest.as_ptr(),
135                ptr::null_mut(),
136            ))?;
137        }
138
139        Ok(())
140    }
141
142    /// Initializes the context to compute the signature of data.
143    ///
144    /// A reference to the context's inner `PkeyCtx` is returned, allowing signature settings to be configured.
145    #[corresponds(EVP_DigestSignInit)]
146    #[inline]
147    pub fn digest_sign_init<'a, T>(
148        &'a mut self,
149        digest: Option<&MdRef>,
150        pkey: &PKeyRef<T>,
151    ) -> Result<&'a mut PkeyCtxRef<T>, ErrorStack>
152    where
153        T: HasPrivate,
154    {
155        unsafe {
156            let mut p = ptr::null_mut();
157            cvt(ffi::EVP_DigestSignInit(
158                self.as_ptr(),
159                &mut p,
160                digest.map_or(ptr::null(), |p| p.as_ptr()),
161                ptr::null_mut(),
162                pkey.as_ptr(),
163            ))?;
164            Ok(PkeyCtxRef::from_ptr_mut(p))
165        }
166    }
167
168    /// Initializes the context to verify the signature of data.
169    ///
170    /// A reference to the context's inner `PkeyCtx` is returned, allowing signature settings to be configured.
171    #[corresponds(EVP_DigestVerifyInit)]
172    #[inline]
173    pub fn digest_verify_init<'a, T>(
174        &'a mut self,
175        digest: Option<&MdRef>,
176        pkey: &PKeyRef<T>,
177    ) -> Result<&'a mut PkeyCtxRef<T>, ErrorStack>
178    where
179        T: HasPublic,
180    {
181        unsafe {
182            let mut p = ptr::null_mut();
183            cvt(ffi::EVP_DigestVerifyInit(
184                self.as_ptr(),
185                &mut p,
186                digest.map_or(ptr::null(), |p| p.as_ptr()),
187                ptr::null_mut(),
188                pkey.as_ptr(),
189            ))?;
190            Ok(PkeyCtxRef::from_ptr_mut(p))
191        }
192    }
193
194    /// Updates the context with more data.
195    #[corresponds(EVP_DigestUpdate)]
196    #[inline]
197    pub fn digest_update(&mut self, data: &[u8]) -> Result<(), ErrorStack> {
198        unsafe {
199            cvt(ffi::EVP_DigestUpdate(
200                self.as_ptr(),
201                data.as_ptr() as *const _,
202                data.len(),
203            ))?;
204        }
205
206        Ok(())
207    }
208
209    /// Updates the context with more data.
210    #[corresponds(EVP_DigestSignUpdate)]
211    #[inline]
212    pub fn digest_sign_update(&mut self, data: &[u8]) -> Result<(), ErrorStack> {
213        unsafe {
214            cvt(ffi::EVP_DigestSignUpdate(
215                self.as_ptr(),
216                data.as_ptr() as *const _,
217                data.len(),
218            ))?;
219        }
220
221        Ok(())
222    }
223
224    /// Updates the context with more data.
225    #[corresponds(EVP_DigestVerifyUpdate)]
226    #[inline]
227    pub fn digest_verify_update(&mut self, data: &[u8]) -> Result<(), ErrorStack> {
228        unsafe {
229            cvt(ffi::EVP_DigestVerifyUpdate(
230                self.as_ptr(),
231                data.as_ptr() as *const _,
232                data.len(),
233            ))?;
234        }
235
236        Ok(())
237    }
238
239    /// Copies the computed digest into the buffer, returning the number of bytes written.
240    #[corresponds(EVP_DigestFinal)]
241    #[inline]
242    pub fn digest_final(&mut self, out: &mut [u8]) -> Result<usize, ErrorStack> {
243        let mut len = u32::try_from(out.len()).unwrap_or(u32::MAX);
244
245        unsafe {
246            cvt(ffi::EVP_DigestFinal(
247                self.as_ptr(),
248                out.as_mut_ptr(),
249                &mut len,
250            ))?;
251        }
252
253        Ok(len as usize)
254    }
255
256    /// Copies the computed digest into the buffer.
257    ///
258    /// Requires OpenSSL 1.1.1 or newer.
259    #[corresponds(EVP_DigestFinalXOF)]
260    #[inline]
261    #[cfg(ossl111)]
262    pub fn digest_final_xof(&mut self, out: &mut [u8]) -> Result<(), ErrorStack> {
263        unsafe {
264            cvt(ffi::EVP_DigestFinalXOF(
265                self.as_ptr(),
266                out.as_mut_ptr(),
267                out.len(),
268            ))?;
269        }
270
271        Ok(())
272    }
273
274    /// Signs the computed digest.
275    ///
276    /// If `out` is set to `None`, an upper bound on the number of bytes required for the output buffer will be
277    /// returned.
278    #[corresponds(EVP_DigestSignFinal)]
279    #[inline]
280    pub fn digest_sign_final(&mut self, out: Option<&mut [u8]>) -> Result<usize, ErrorStack> {
281        let mut len = out.as_ref().map_or(0, |b| b.len());
282
283        unsafe {
284            cvt(ffi::EVP_DigestSignFinal(
285                self.as_ptr(),
286                out.map_or(ptr::null_mut(), |b| b.as_mut_ptr()),
287                &mut len,
288            ))?;
289        }
290
291        Ok(len)
292    }
293
294    /// Like [`Self::digest_sign_final`] but appends the signature to a [`Vec`].
295    pub fn digest_sign_final_to_vec(&mut self, out: &mut Vec<u8>) -> Result<usize, ErrorStack> {
296        let base = out.len();
297        let len = self.digest_sign_final(None)?;
298        out.resize(base + len, 0);
299        let len = self.digest_sign_final(Some(&mut out[base..]))?;
300        out.truncate(base + len);
301        Ok(len)
302    }
303
304    /// Verifies the provided signature.
305    ///
306    /// Returns `Ok(true)` if the signature is valid, `Ok(false)` if the signature is invalid, and `Err` if an error
307    /// occurred.
308    #[corresponds(EVP_DigestVerifyFinal)]
309    #[inline]
310    pub fn digest_verify_final(&mut self, signature: &[u8]) -> Result<bool, ErrorStack> {
311        unsafe {
312            let r = cvt_n(ffi::EVP_DigestVerifyFinal(
313                self.as_ptr(),
314                signature.as_ptr() as *mut _,
315                signature.len(),
316            ))?;
317            Ok(r == 1)
318        }
319    }
320
321    /// Computes the signature of the data in `from`.
322    ///
323    /// If `to` is set to `None`, an upper bound on the number of bytes required for the output buffer will be
324    /// returned.
325    ///
326    /// Requires OpenSSL 1.1.1 or newer.
327    #[corresponds(EVP_DigestSign)]
328    #[cfg(ossl111)]
329    #[inline]
330    pub fn digest_sign(&mut self, from: &[u8], to: Option<&mut [u8]>) -> Result<usize, ErrorStack> {
331        let mut len = to.as_ref().map_or(0, |b| b.len());
332
333        unsafe {
334            cvt(ffi::EVP_DigestSign(
335                self.as_ptr(),
336                to.map_or(ptr::null_mut(), |b| b.as_mut_ptr()),
337                &mut len,
338                from.as_ptr(),
339                from.len(),
340            ))?;
341        }
342
343        Ok(len)
344    }
345
346    /// Like [`Self::digest_sign`] but appends the signature to a [`Vec`].
347    #[cfg(ossl111)]
348    pub fn digest_sign_to_vec(
349        &mut self,
350        from: &[u8],
351        to: &mut Vec<u8>,
352    ) -> Result<usize, ErrorStack> {
353        let base = to.len();
354        let len = self.digest_sign(from, None)?;
355        to.resize(base + len, 0);
356        let len = self.digest_sign(from, Some(&mut to[base..]))?;
357        to.truncate(base + len);
358        Ok(len)
359    }
360
361    /// Verifies the signature of the data in `data`.
362    ///
363    /// Returns `Ok(true)` if the signature is valid, `Ok(false)` if the signature is invalid, and `Err` if an error
364    /// occurred.
365    ///
366    /// Requires OpenSSL 1.1.1 or newer.
367    #[corresponds(EVP_DigestVerify)]
368    #[cfg(ossl111)]
369    #[inline]
370    pub fn digest_verify(&mut self, data: &[u8], signature: &[u8]) -> Result<bool, ErrorStack> {
371        unsafe {
372            let r = cvt(ffi::EVP_DigestVerify(
373                self.as_ptr(),
374                signature.as_ptr(),
375                signature.len(),
376                data.as_ptr(),
377                data.len(),
378            ))?;
379            Ok(r == 1)
380        }
381    }
382
383    /// Returns the size of the message digest, i.e. the size of the hash
384    #[corresponds(EVP_MD_CTX_size)]
385    #[inline]
386    pub fn size(&self) -> usize {
387        unsafe { ffi::EVP_MD_CTX_size(self.as_ptr()) as usize }
388    }
389
390    /// Resets the underlying EVP_MD_CTX instance
391    #[corresponds(EVP_MD_CTX_reset)]
392    #[cfg(ossl111)]
393    #[inline]
394    pub fn reset(&mut self) -> Result<(), ErrorStack> {
395        unsafe {
396            let _ = cvt(ffi::EVP_MD_CTX_reset(self.as_ptr()))?;
397            Ok(())
398        }
399    }
400}
401
402#[cfg(test)]
403mod test {
404    use super::*;
405    use crate::md::Md;
406    use crate::pkey::PKey;
407    use crate::rsa::Rsa;
408
409    #[test]
410    fn verify_fail() {
411        let key1 = Rsa::generate(4096).unwrap();
412        let key1 = PKey::from_rsa(key1).unwrap();
413
414        let md = Md::sha256();
415        let data = b"Some Crypto Text";
416
417        let mut ctx = MdCtx::new().unwrap();
418        ctx.digest_sign_init(Some(md), &key1).unwrap();
419        ctx.digest_sign_update(data).unwrap();
420        let mut signature = vec![];
421        ctx.digest_sign_final_to_vec(&mut signature).unwrap();
422
423        let bad_data = b"Some Crypto text";
424
425        ctx.digest_verify_init(Some(md), &key1).unwrap();
426        ctx.digest_verify_update(bad_data).unwrap();
427        let valid = ctx.digest_verify_final(&signature).unwrap();
428        assert!(!valid);
429    }
430
431    #[test]
432    fn verify_success() {
433        let key1 = Rsa::generate(2048).unwrap();
434        let key1 = PKey::from_rsa(key1).unwrap();
435
436        let md = Md::sha256();
437        let data = b"Some Crypto Text";
438
439        let mut ctx = MdCtx::new().unwrap();
440        ctx.digest_sign_init(Some(md), &key1).unwrap();
441        ctx.digest_sign_update(data).unwrap();
442        let mut signature = vec![];
443        ctx.digest_sign_final_to_vec(&mut signature).unwrap();
444
445        let good_data = b"Some Crypto Text";
446
447        ctx.digest_verify_init(Some(md), &key1).unwrap();
448        ctx.digest_verify_update(good_data).unwrap();
449        let valid = ctx.digest_verify_final(&signature).unwrap();
450        assert!(valid);
451    }
452
453    #[test]
454    fn verify_with_public_success() {
455        let rsa = Rsa::generate(2048).unwrap();
456        let key1 = PKey::from_rsa(rsa.clone()).unwrap();
457
458        let md = Md::sha256();
459        let data = b"Some Crypto Text";
460
461        let mut ctx = MdCtx::new().unwrap();
462        ctx.digest_sign_init(Some(md), &key1).unwrap();
463        ctx.digest_sign_update(data).unwrap();
464        let mut signature = vec![];
465        ctx.digest_sign_final_to_vec(&mut signature).unwrap();
466
467        let good_data = b"Some Crypto Text";
468
469        // try to verify using only public components of the key
470        let n = rsa.n().to_owned().unwrap();
471        let e = rsa.e().to_owned().unwrap();
472
473        let rsa = Rsa::from_public_components(n, e).unwrap();
474        let key1 = PKey::from_rsa(rsa).unwrap();
475
476        ctx.digest_verify_init(Some(md), &key1).unwrap();
477        ctx.digest_verify_update(good_data).unwrap();
478        let valid = ctx.digest_verify_final(&signature).unwrap();
479        assert!(valid);
480    }
481
482    #[test]
483    fn verify_md_ctx_size() {
484        let mut ctx = MdCtx::new().unwrap();
485        ctx.digest_init(Md::sha224()).unwrap();
486        assert_eq!(Md::sha224().size(), ctx.size());
487        assert_eq!(Md::sha224().size(), 28);
488
489        let mut ctx = MdCtx::new().unwrap();
490        ctx.digest_init(Md::sha256()).unwrap();
491        assert_eq!(Md::sha256().size(), ctx.size());
492        assert_eq!(Md::sha256().size(), 32);
493
494        let mut ctx = MdCtx::new().unwrap();
495        ctx.digest_init(Md::sha384()).unwrap();
496        assert_eq!(Md::sha384().size(), ctx.size());
497        assert_eq!(Md::sha384().size(), 48);
498
499        let mut ctx = MdCtx::new().unwrap();
500        ctx.digest_init(Md::sha512()).unwrap();
501        assert_eq!(Md::sha512().size(), ctx.size());
502        assert_eq!(Md::sha512().size(), 64);
503    }
504
505    #[test]
506    #[cfg(ossl111)]
507    fn verify_md_ctx_reset() {
508        let hello_expected =
509            hex::decode("185f8db32271fe25f561a6fc938b2e264306ec304eda518007d1764826381969")
510                .unwrap();
511        let world_expected =
512            hex::decode("78ae647dc5544d227130a0682a51e30bc7777fbb6d8a8f17007463a3ecd1d524")
513                .unwrap();
514        // Calculate SHA-256 digest of "Hello"
515        let mut ctx = MdCtx::new().unwrap();
516        ctx.digest_init(Md::sha256()).unwrap();
517        ctx.digest_update(b"Hello").unwrap();
518        let mut result = vec![0; 32];
519        let result_len = ctx.digest_final(result.as_mut_slice()).unwrap();
520        assert_eq!(result_len, result.len());
521        // Validate result of "Hello"
522        assert_eq!(result, hello_expected);
523
524        // Create new context
525        let mut ctx = MdCtx::new().unwrap();
526        // Initialize and update to "Hello"
527        ctx.digest_init(Md::sha256()).unwrap();
528        ctx.digest_update(b"Hello").unwrap();
529        // Now reset, init to SHA-256 and use "World"
530        ctx.reset().unwrap();
531        ctx.digest_init(Md::sha256()).unwrap();
532        ctx.digest_update(b"World").unwrap();
533
534        let mut reset_result = vec![0; 32];
535        let result_len = ctx.digest_final(reset_result.as_mut_slice()).unwrap();
536        assert_eq!(result_len, reset_result.len());
537        // Validate result of digest of "World"
538        assert_eq!(reset_result, world_expected);
539    }
540}
541