Changeset 23507 in vbox for trunk/include/iprt

Timestamp:

Oct 2, 2009 12:02:02 PM (15 years ago)

Author:

vboxsync

Message:

IPRT: Added APIs for convering digests to/from strings.

Location:

trunk/include/iprt

Files:

• md5.h (modified) (2 diffs)
• sha.h (modified) (5 diffs)
• string.h (modified) (1 diff)

trunk/include/iprt/md5.h

@@ -39 +39 @@
 
 /** Size of a MD5 hash. */
-#define RTMD5HASHSIZE 16
+#define RTMD5_HASH_SIZE     16
+/** @deprecated Use RTMD5_HASH_SIZE. */
+#define RTMD5HASHSIZE       RTMD5_HASH_SIZE
+/** Size of a MD5 hash. */
+#define RTMD5_STRING_LEN    32
 
 /**
@@ -91 +95 @@
 RTDECL(void) RTMd5Final(uint8_t pabDigest[RTMD5HASHSIZE], PRTMD5CONTEXT pCtx);
 
+/**
+ * Converts a MD5 hash to a digest string.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   pabDigest   The binary digest returned by RTMd5Final or RTMd5.
+ * @param   pszDigest   Where to return the stringified digest.
+ * @param   cchDigest   The size of the output buffer. Should be at least
+ *                      RTMD5_STRING_LEN + 1 bytes.
+ */
+RTDECL(int) RTMd5ToString(uint8_t const pabDigest[RTMD5_HASH_SIZE], char *pszDigest, size_t cchDigest);
+
+/**
+ * Converts a MD5 hash to a digest string.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   pszDigest   The strigified digest. Leading and trailing spaces are
+ *                      ignored.
+ * @param   pabDigest   Where to store the hash. (What is passed is a pointer to
+ *                      the caller's buffer.)
+ */
+RTDECL(int) RTMd5FromString(char const *pszDigest, uint8_t pabDigest[RTMD5_HASH_SIZE]);
+
+
 RT_C_DECLS_END
 

trunk/include/iprt/sha.h

@@ -41 +41 @@
 
 /** The size of a SHA-1 hash. */
-#define RTSHA1_HASH_SIZE  20
+#define RTSHA1_HASH_SIZE    20
+/** The length of a SHA-1 digest string. The terminator is not included. */
+#define RTSHA1_DIGEST_LEN  (40+1)
 
 /**
@@ -91 +93 @@
 RTDECL(void) RTSha1Final(PRTSHA1CONTEXT pCtx, uint8_t pabDigest[RTSHA1_HASH_SIZE]);
 
+/**
+ * Converts a SHA-512 hash to a digest string.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   pabDigest   The binary digest returned by RTSha1Final or RTSha1.
+ * @param   pszDigest   Where to return the stringified digest.
+ * @param   cchDigest   The size of the output buffer. Should be at least
+ *                      RTSHA1_STRING_LEN + 1 bytes.
+ */
+RTDECL(int) RTSha1ToString(uint8_t const pabDigest[RTSHA1_HASH_SIZE], char *pszDigest, size_t cchDigest);
+
+/**
+ * Converts a SHA-1 hash to a digest string.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   pszDigest   The strigified digest. Leading and trailing spaces are
+ *                      ignored.
+ * @param   pabDigest   Where to store the hash. (What is passed is a pointer to
+ *                      the caller's buffer.)
+ */
+RTDECL(int) RTSha1FromString(char const *pszDigest, uint8_t pabDigest[RTSHA1_HASH_SIZE]);
 
 /**
@@ -103 +128 @@
 
 
+
 /** The size of a SHA-256 hash. */
-#define RTSHA256_HASH_SIZE  32
+#define RTSHA256_HASH_SIZE      32
+/** The length of a SHA-256 digest string. The terminator is not included. */
+#define RTSHA256_DIGEST_LEN     64
 
 /**
@@ -154 +182 @@
 RTDECL(void) RTSha256Final(PRTSHA256CONTEXT pCtx, uint8_t pabDigest[RTSHA256_HASH_SIZE]);
 
+/**
+ * Converts a SHA-256 hash to a digest string.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   pabDigest   The binary digest returned by RTSha256Final or RTSha256.
+ * @param   pszDigest   Where to return the stringified digest.
+ * @param   cchDigest   The size of the output buffer. Should be at least
+ *                      RTSHA256_STRING_LEN + 1 bytes.
+ */
+RTDECL(int) RTSha256ToString(uint8_t const pabDigest[RTSHA256_HASH_SIZE], char *pszDigest, size_t cchDigest);
+
+/**
+ * Converts a SHA-256 hash to a digest string.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   pszDigest   The strigified digest. Leading and trailing spaces are
+ *                      ignored.
+ * @param   pabDigest   Where to store the hash. (What is passed is a pointer to
+ *                      the caller's buffer.)
+ */
+RTDECL(int) RTSha256FromString(char const *pszDigest, uint8_t pabDigest[RTSHA256_HASH_SIZE]);
+
+
 
 /** The size of a SHA-512 hash. */
-#define RTSHA512_HASH_SIZE  64
+#define RTSHA512_HASH_SIZE      64
+/** The length of a SHA-512 digest string. The terminator is not included. */
+#define RTSHA512_STRING_LEN     128
 
 /**
@@ -206 +261 @@
 RTDECL(void) RTSha512Final(PRTSHA512CONTEXT pCtx, uint8_t pabDigest[RTSHA512_HASH_SIZE]);
 
+/**
+ * Converts a SHA-512 hash to a digest string.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   pabDigest   The binary digest returned by RTSha512Final or RTSha512.
+ * @param   pszDigest   Where to return the stringified digest.
+ * @param   cchDigest   The size of the output buffer. Should be at least
+ *                      RTSHA512_STRING_LEN + 1 bytes.
+ */
+RTDECL(int) RTSha512ToString(uint8_t const pabDigest[RTSHA512_HASH_SIZE], char *pszDigest, size_t cchDigest);
+
+/**
+ * Converts a SHA-512 hash to a digest string.
+ *
+ * @returns IPRT status code.
+ *
+ * @param   pszDigest   The strigified digest. Leading and trailing spaces are
+ *                      ignored.
+ * @param   pabDigest   Where to store the hash. (What is passed is a pointer to
+ *                      the caller's buffer.)
+ */
+RTDECL(int) RTSha512FromString(char const *pszDigest, uint8_t pabDigest[RTSHA512_HASH_SIZE]);
+
 /** @} */
 

trunk/include/iprt/string.h

@@ -1432 +1432 @@
 RTDECL(int8_t) RTStrToInt8(const char *pszValue);
 
+/**
+ * Formats a buffer stream as hex bytes.
+ *
+ * The default is no separating spaces or line breaks or anything.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_INVALID_POINTER if any of the pointers are wrong.
+ * @retval  VERR_BUFFER_OVERFLOW if the buffer is insufficent to hold the bytes.
+ *
+ * @param   pszBuf      Output string buffer.
+ * @param   cchBuf      The size of the output buffer.
+ * @param   pv          Pointer to the bytes to stringify.
+ * @param   cb          The number of bytes to stringify.
+ * @param   fFlags      Must be zero, reserved for future use.
+ */
+RTDECL(int) RTStrPrintHexBytes(char *pszBuf, size_t cchBuf, void const *pv, size_t cb, uint32_t fFlags);
+
+/**
+ * Converts a string of hex bytes back into binary data.
+ *
+ * @returns IPRT status code.
+ * @retval  VERR_INVALID_POINTER if any of the pointers are wrong.
+ * @retval  VERR_BUFFER_OVERFLOW if the string contains too many hex bytes.
+ * @retval  VERR_BUFFER_UNDERFLOW if there aren't enough hex bytes to fill up
+ *          the output buffer.
+ * @retval  VERR_UNEVEN_INPUT if the input contains a half byte.
+ * @retval  VERR_NO_DIGITS
+ * @retval  VWRN_TRAILING_CHARS
+ * @retval  VWRN_TRAILING_SPACES
+ *
+ * @param   pszHex      The string containing the hex bytes.
+ * @param   pv          Output buffer.
+ * @param   cb          The size of the output buffer.
+ * @param   fFlags      Must be zero, reserved for future use.
+ */
+RTDECL(int) RTStrConvertHexBytes(char const *pszHex, void *pv, size_t cb, uint32_t fFlags);
+
 /** @} */