include/iprt/md5.h

   1 /** @file
   2  * IPRT - Message-Digest algorithm 5.
   3  */
   4
   5 /*
   6  * Copyright (C) 2006-2024 Oracle and/or its affiliates.
   7  *
   8  * This file is part of VirtualBox base platform packages, as
   9  * available from https://www.virtualbox.org.
  10  *
  11  * This program is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU General Public License
  13  * as published by the Free Software Foundation, in version 3 of the
  14  * License.
  15  *
  16  * This program is distributed in the hope that it will be useful, but
  17  * WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, see <https://www.gnu.org/licenses>.
  23  *
  24  * The contents of this file may alternatively be used under the terms
  25  * of the Common Development and Distribution License Version 1.0
  26  * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
  27  * in the VirtualBox distribution, in which case the provisions of the
  28  * CDDL are applicable instead of those of the GPL.
  29  *
  30  * You may elect to license modified versions of this file under the
  31  * terms and conditions of either the GPL or the CDDL or both.
  32  *
  33  * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
  34  */
  35
  36 #ifndef IPRT_INCLUDED_md5_h
  37 #define IPRT_INCLUDED_md5_h
  38 #ifndef RT_WITHOUT_PRAGMA_ONCE
  39 # pragma once
  40 #endif
  41
  42 #include <iprt/types.h>
  43
  44 /** @defgroup grp_rt_md5    RTMd5 - Message-Digest algorithm 5
  45  * @ingroup grp_rt
  46  * @{
  47  */
  48
  49 /** Size of a MD5 hash. */
  50 #define RTMD5_HASH_SIZE     16
  51 /** @deprecated Use RTMD5_HASH_SIZE. */
  52 #define RTMD5HASHSIZE       RTMD5_HASH_SIZE
  53 /** The length of a MD5 digest string. The terminator is not included. */
  54 #define RTMD5_DIGEST_LEN    32
  55 /** Size of a MD5 hash.
  56  * @deprecated Use RTMD5_DIGEST_LEN  */
  57 #define RTMD5_STRING_LEN    RTMD5_DIGEST_LEN
  58
  59 /**
  60  * MD5 hash algorithm context.
  61  */
  62 typedef union RTMD5CONTEXT
  63 {
  64     uint64_t            u64BetterAlignment;
  65     uint8_t             abPadding[(4 + 6 + 16 + 1) * sizeof(uint32_t)];
  66     /** Context used by md5-alt.cpp. */
  67     struct
  68     {
  69         uint32_t        in[16];
  70         uint32_t        buf[4];
  71         uint32_t        bits[2];
  72     } AltPrivate;
  73 #ifdef RT_MD5_OPENSSL_PRIVATE_CONTEXT
  74     /** Context used by md5-openssl.cpp. */
  75     MD5_CTX         OsslPrivate;
  76 #endif
  77 } RTMD5CONTEXT;
  78 /** Pointer to MD5 hash algorithm context. */
  79 typedef RTMD5CONTEXT *PRTMD5CONTEXT;
  80
  81 RT_C_DECLS_BEGIN
  82
  83 /**
  84  * Compute the MD5 hash of the data.
  85  *
  86  * @param   pvBuf       Pointer to data.
  87  * @param   cbBuf       Length of data (in bytes).
  88  * @param   pabDigest   Where to store the hash.
  89  *                      (What's passed is a pointer to the caller's buffer.)
  90  */
  91 RTDECL(void) RTMd5(const void *pvBuf, size_t cbBuf, uint8_t pabDigest[RTMD5HASHSIZE]);
  92
  93 /**
  94  * Initialize MD5 context.
  95  *
  96  * @param   pCtx        Pointer to the MD5 context to initialize.
  97  */
  98 RTDECL(void) RTMd5Init(PRTMD5CONTEXT pCtx);
  99
 100 /**
 101  * Feed data into the MD5 computation.
 102  *
 103  * @param   pCtx        Pointer to the MD5 context.
 104  * @param   pvBuf       Pointer to data.
 105  * @param   cbBuf       Length of data (in bytes).
 106  */
 107 RTDECL(void) RTMd5Update(PRTMD5CONTEXT pCtx, const void *pvBuf, size_t cbBuf);
 108
 109 /**
 110  * Compute the MD5 hash of the data.
 111  *
 112  * @param   pabDigest   Where to store the hash.
 113  *                      (What's passed is a pointer to the caller's buffer.)
 114  * @param   pCtx        Pointer to the MD5 context.
 115  */
 116 RTDECL(void) RTMd5Final(uint8_t pabDigest[RTMD5HASHSIZE], PRTMD5CONTEXT pCtx);
 117
 118 /**
 119  * Converts a MD5 hash to a digest string.
 120  *
 121  * @returns IPRT status code.
 122  *
 123  * @param   pabDigest   The binary digest returned by RTMd5Final or RTMd5.
 124  * @param   pszDigest   Where to return the stringified digest.
 125  * @param   cchDigest   The size of the output buffer. Should be at least
 126  *                      RTMD5_STRING_LEN + 1 bytes.
 127  */
 128 RTDECL(int) RTMd5ToString(uint8_t const pabDigest[RTMD5_HASH_SIZE], char *pszDigest, size_t cchDigest);
 129
 130 /**
 131  * Converts a MD5 hash to a digest string.
 132  *
 133  * @returns IPRT status code.
 134  *
 135  * @param   pszDigest   The stringified digest. Leading and trailing spaces are
 136  *                      ignored.
 137  * @param   pabDigest   Where to store the hash. (What is passed is a pointer to
 138  *                      the caller's buffer.)
 139  */
 140 RTDECL(int) RTMd5FromString(char const *pszDigest, uint8_t pabDigest[RTMD5_HASH_SIZE]);
 141
 142
 143 RT_C_DECLS_END
 144
 145 /** @} */
 146
 147 #endif /* !IPRT_INCLUDED_md5_h */
 148