Whitespace cleanup in apps

[openssl.git] / doc / crypto / OPENSSL_malloc.pod

diff --git a/doc/crypto/OPENSSL_malloc.pod b/doc/crypto/OPENSSL_malloc.pod
index 04fa0b718c76ba674e25f8c79e180a6896cdb52d..9760135ee907dae5f7f1bed0902dcc28381dcdec 100644 (file)
--- a/doc/crypto/OPENSSL_malloc.pod
+++ b/doc/crypto/OPENSSL_malloc.pod
@@ -2,17 +2,21 @@
 
 =head1 NAME
 
+CRYPTO_MEM_CHECK_OFF, CRYPTO_MEM_CHECK_ON,
+CRYPTO_MEM_CHECK_DISABLE, CRYPTO_MEM_CHECK_ENABLE,
 OPENSSL_malloc_init,
 OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free,
-OPENSSL_clear_realloc, OPENSSL_clear_free,
+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,
 CRYPTO_clear_realloc, CRYPTO_clear_free,
 CRYPTO_get_mem_functions, CRYPTO_set_mem_functions,
 CRYPTO_set_mem_debug, CRYPTO_mem_ctrl,
-OPENSSL_mem_debug_push, OPENSSL_mem_debug_pop,
-CRYPTO_mem_debug_push, CRYPTO_mem_debug_pop,
 CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
 
 =head1 SYNOPSIS
@@ -27,10 +31,17 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
  void OPENSSL_free(void *addr)
  char *OPENSSL_strdup(const char *str)
  char *OPENSSL_strndup(const char *str, size_t s)
+ size_t OPENSSL_strlcat(char *dst, const char *src, size_t size);
+ size_t OPENSSL_strlcpy(char *dst, const char *src, size_t size);
+ void *OPENSSL_memdup(void *data, size_t s)
  void *OPENSSL_clear_realloc(void *p, size_t old_len, size_t num)
  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)
@@ -59,12 +70,13 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
  int CRYPTO_mem_ctrl(int mode);
 
  int OPENSSL_mem_debug_push(const char *info)
- int OPENSLS_mem_debug_pop)(void)
+ int OPENSSL_mem_debug_pop(void);
 
  int CRYPTO_mem_debug_push(const char *info, const char *file, int line);
+ int CRYPTO_mem_debug_pop(void);
 
  void CRYPTO_mem_leaks(BIO *b);
- void CRYPTO_mem_leaks(FILE *fp);
+ void CRYPTO_mem_leaks_fp(FILE *fp);
 
 =head1 DESCRIPTION
 
@@ -84,17 +96,39 @@ OPENSSL_zalloc() calls memset() to zero the memory before returning.
 
 OPENSSL_clear_realloc() and OPENSSL_clear_free() should be used
 when the buffer at B<addr> holds sensitive information.
-The old buffer is filled with arbitrary data by calling OPENSSL_cleanse()
+The old buffer is filled with zero's by calling OPENSSL_cleanse()
 before ultimately calling OPENSSL_free().
 
+OPENSSL_cleanse() fills B<ptr> of size B<len> with a string of 0's.
+Use OPENSSL_cleanse() with care if the memory is a mapping of a file.
+If the storage controller uses write compression, then its possible
+that sensitive tail bytes will survive zeroization because the block of
+zeros will be compressed. If the storage controller uses wear leveling,
+then the old sensitive data will not be overwritten; rather, a block of
+0's will be written at a new physical location.
+
 OPENSSL_strdup(), OPENSSL_strndup() and OPENSSL_memdup() are like the
 equivalent C functions, except that memory is allocated by calling the
-OPENSSL_malloc() and should be releaed by calling OPENSSL_free().
+OPENSSL_malloc() and should be released by calling OPENSSL_free().
 
 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).
@@ -147,6 +181,7 @@ 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.
 
@@ -167,4 +202,13 @@ at once.  I<This applies specially if OpenSSL was built with the
 configuration option> C<crypto-mdebug> I<enabled.  In case, swapping out
 only, say, the malloc() implementation is outright dangerous.>
 
+=head1 COPYRIGHT
+
+Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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