diff options
author | Richard Levitte <levitte@openssl.org> | 2019-07-03 18:40:17 +0200 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2019-08-12 12:50:41 +0200 |
commit | 82bd7c2cbd3a4b38321fb9053b8aa0f5d100cf54 (patch) | |
tree | b3a77966489689c83d94dcd2be519186e4f08bd9 /doc | |
parent | a42cb4ba8aa74757b526af2cad2ac09b493df3fb (diff) |
Add OPENSSL_hexstr2buf_ex() and OPENSSL_buf2hexstr_ex()
They do the same thing as OPENSSL_hexstr2buf() and OPENSSL_buf2hexstr(),
except they take a result buffer from the caller.
We take the opportunity to break out the documentation of the hex to /
from buffer conversion routines from the OPENSSL_malloc() file to its
own file. These routines aren't memory allocation routines per se.
Reviewed-by: Paul Dale <paul.dale@oracle.com>
(Merged from https://github.com/openssl/openssl/pull/9303)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/OPENSSL_hexchar2int.pod | 74 | ||||
-rw-r--r-- | doc/man3/OPENSSL_malloc.pod | 20 |
2 files changed, 74 insertions, 20 deletions
diff --git a/doc/man3/OPENSSL_hexchar2int.pod b/doc/man3/OPENSSL_hexchar2int.pod new file mode 100644 index 0000000000..930b32b61f --- /dev/null +++ b/doc/man3/OPENSSL_hexchar2int.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +OPENSSL_hexchar2int, +OPENSSL_hexstr2buf_ex, OPENSSL_hexstr2buf, +OPENSSL_buf2hexstr_ex, OPENSSL_buf2hexstr +- Hex encoding and decoding functions + +=head1 SYNOPSIS + + #include <openssl/crypto.h> + + int OPENSSL_hexchar2int(unsigned char c); + int OPENSSL_hexstr2buf_ex(unsigned char *buf, size_t buf_n, long *buflen, + const char *str); + unsigned char *OPENSSL_hexstr2buf(const char *str, long *len); + int OPENSSL_buf2hexstr_ex(char *str, size_t str_n, size_t *strlen, + const unsigned char *buf, long buflen); + char *OPENSSL_buf2hexstr(const unsigned char *buf, long buflen); + +=head1 DESCRIPTION + +OPENSSL_hexchar2int() converts a hexadecimal character to its numeric +equivalent. + +OPENSSL_hexstr2buf_ex() decodes the hex string B<str> and places the +resulting string of bytes in the given I<buf>. +I<buf_n> gives the size of the buffer. +If I<buflen> is not NULL, it is filled in with the result length. +To find out how large the result will be, call this function with NULL +for I<buf>. +Colons between two-character hex "bytes" are accepted and ignored. +An odd number of hex digits is an error. + +OPENSSL_hexstr2buf() does the same thing as OPENSSL_hexstr2buf_ex(), +but allocates the space for the result, and returns the result. +The memory is allocated by calling OPENSSL_malloc() and should be +released by calling OPENSSL_free(). + +OPENSSL_buf2hexstr_ex() encodes the contents of the given I<buf> with +length I<buflen> and places the resulting hexadecimal character string +in the given I<str>. +I<str_n> gives the size of the of the string buffer. +If I<strlen> is not NULL, it is filled in with the result length. +To find out how large the result will be, call this function with NULL +for I<str>. + +OPENSSL_buf2hexstr() does the same thing as OPENSSL_buf2hexstr_ex(), +but allocates the space for the result, and returns the result. +The memory is allocated by calling OPENSSL_malloc() and should be +released by calling OPENSSL_free(). + +=head1 RETURN VALUES + +OPENSSL_hexchar2int returns the value of a decoded hex character, +or -1 on error. + +OPENSSL_buf2hexstr() and OPENSSL_hexstr2buf() +return a pointer to allocated memory, or NULL on error. + +OPENSSL_buf2hexstr_ex() and OPENSSL_hexstr2buf_ex() return 1 on +success, or 0 on error. + +=head1 COPYRIGHT + +Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut diff --git a/doc/man3/OPENSSL_malloc.pod b/doc/man3/OPENSSL_malloc.pod index 38edf49d4d..198251fcd7 100644 --- a/doc/man3/OPENSSL_malloc.pod +++ b/doc/man3/OPENSSL_malloc.pod @@ -8,7 +8,6 @@ OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse, CRYPTO_malloc, CRYPTO_zalloc, CRYPTO_realloc, CRYPTO_free, OPENSSL_strdup, OPENSSL_strndup, OPENSSL_memdup, OPENSSL_strlcpy, OPENSSL_strlcat, -OPENSSL_hexstr2buf, OPENSSL_buf2hexstr, OPENSSL_hexchar2int, CRYPTO_strdup, CRYPTO_strndup, OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop, CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop, @@ -40,10 +39,6 @@ OPENSSL_MALLOC_FD void OPENSSL_clear_free(void *str, size_t num) void OPENSSL_cleanse(void *ptr, size_t len); - unsigned char *OPENSSL_hexstr2buf(const char *str, long *len); - char *OPENSSL_buf2hexstr(const unsigned char *buffer, long len); - int OPENSSL_hexchar2int(unsigned char c); - void *CRYPTO_malloc(size_t num, const char *file, int line) void *CRYPTO_zalloc(size_t num, const char *file, int line) void *CRYPTO_realloc(void *p, size_t num, const char *file, int line) @@ -119,20 +114,6 @@ OPENSSL_strlcpy(), OPENSSL_strlcat() and OPENSSL_strnlen() are equivalents of the common C library functions and are provided for portability. -OPENSSL_hexstr2buf() parses B<str> as a hex string and returns a -pointer to the parsed value. The memory is allocated by calling -OPENSSL_malloc() and should be released by calling OPENSSL_free(). -If B<len> is not NULL, it is filled in with the output length. -Colons between two-character hex "bytes" are ignored. -An odd number of hex digits is an error. - -OPENSSL_buf2hexstr() takes the specified buffer and length, and returns -a hex string for value, or NULL on error. -B<Buffer> cannot be NULL; if B<len> is 0 an empty string is returned. - -OPENSSL_hexchar2int() converts a character to the hexadecimal equivalent, -or returns -1 on error. - If no allocations have been done, it is possible to "swap out" the default implementations for OPENSSL_malloc(), OPENSSL_realloc and OPENSSL_free() and replace them with alternate versions (hooks). @@ -216,7 +197,6 @@ OPENSSL_malloc(), OPENSSL_zalloc(), OPENSSL_realloc(), OPENSSL_clear_realloc(), CRYPTO_malloc(), CRYPTO_zalloc(), CRYPTO_realloc(), CRYPTO_clear_realloc(), -OPENSSL_buf2hexstr(), OPENSSL_hexstr2buf(), OPENSSL_strdup(), and OPENSSL_strndup() return a pointer to allocated memory or NULL on error. |