From 73b7d4e652c0b4c202146042cde610213cb6deb6 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 28 Nov 2016 16:33:48 +0000 Subject: Document and discourage those wrappers that we have and that OpenSSL documents, too. There are many additional undocumented ones in our public OpenSSL headers, but advertising those would be a bad idea. Nothing of the text from OPENSSL_malloc.pod remains, so use my own Copyright and license. --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/OPENSSL_malloc.3 | 172 +++++++++++++++++++++++++++++++++ 2 files changed, 174 insertions(+), 1 deletion(-) create mode 100644 src/lib/libcrypto/man/OPENSSL_malloc.3 (limited to 'src') diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index a1cc37cb35..fc9f62bd06 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.56 2016/11/27 20:40:07 schwarze Exp $ +# $OpenBSD: Makefile,v 1.57 2016/11/28 16:33:48 schwarze Exp $ .include @@ -131,6 +131,7 @@ MAN= \ OPENSSL_VERSION_NUMBER.3 \ OPENSSL_config.3 \ OPENSSL_load_builtin_modules.3 \ + OPENSSL_malloc.3 \ OpenSSL_add_all_algorithms.3 \ PEM_read_bio_PrivateKey.3 \ PEM_write_bio_PKCS7_stream.3 \ diff --git a/src/lib/libcrypto/man/OPENSSL_malloc.3 b/src/lib/libcrypto/man/OPENSSL_malloc.3 new file mode 100644 index 0000000000..bc76e8367b --- /dev/null +++ b/src/lib/libcrypto/man/OPENSSL_malloc.3 @@ -0,0 +1,172 @@ +.\" $OpenBSD: OPENSSL_malloc.3,v 1.1 2016/11/28 16:33:48 schwarze Exp $ +.\" +.\" Copyright (c) 2016 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: November 28 2016 $ +.Dt OPENSSL_MALLOC 3 +.Os +.Sh NAME +.Nm OPENSSL_malloc , +.Nm OPENSSL_realloc , +.Nm OPENSSL_free , +.Nm OPENSSL_strdup , +.Nm OPENSSL_cleanse , +.Nm CRYPTO_malloc , +.Nm CRYPTO_realloc , +.Nm CRYPTO_free , +.Nm CRYPTO_strdup , +.Nm CRYPTO_get_mem_functions , +.Nm CRYPTO_set_mem_functions , +.Nm CRYPTO_mem_ctrl , +.Nm CRYPTO_mem_leaks , +.Nm CRYPTO_mem_leaks_fp +.Nd legacy OpenSSL memory allocation wrappers +.Sh SYNOPSIS +.In openssl/crypto.h +.Ft void * +.Fo OPENSSL_malloc +.Fa "size_t num" +.Fc +.Ft void * +.Fo OPENSSL_realloc +.Fa "void *addr" +.Fa "size_t num" +.Fc +.Ft void +.Fo OPENSSL_free +.Fa "void *addr" +.Fc +.Ft char * +.Fo OPENSSL_strdup +.Fa "const char *str" +.Fc +.Ft void +.Fo OPENSSL_cleanse +.Fa "void *ptr" +.Fa "size_t len" +.Fc +.Ft void * +.Fo CRYPTO_malloc +.Fa "size_t num" +.Fa "const char *file" +.Fa "int line" +.Fc +.Ft void * +.Fo CRYPTO_realloc +.Fa "void *p" +.Fa "size_t num" +.Fa "const char *file" +.Fa "int line" +.Fc +.Ft void +.Fo CRYPTO_free +.Fa "void *str" +.Fa "const char *" +.Fa int +.Fc +.Ft char * +.Fo CRYPTO_strdup +.Fa "const char *p" +.Fa "const char *file" +.Fa "int line" +.Fc +.Ft void +.Fo CRYPTO_get_mem_functions +.Fa "void *(**m)(size_t)" +.Fa "void *(**r)(void *, size_t)" +.Fa "void (**f)(void *)" +.Fc +.Ft int +.Fo CRYPTO_set_mem_functions +.Fa "void *(*m)(size_t)" +.Fa "void *(*r)(void *, size_t)" +.Fa "void (*f)(void *)" +.Fc +.Ft int +.Fo CRYPTO_mem_ctrl +.Fa "int mode" +.Fc +.Ft void +.Fo CRYPTO_mem_leaks +.Fa "BIO *b" +.Fc +.Ft void +.Fo CRYPTO_mem_leaks_fp +.Fa "FILE *fp" +.Fc +.Sh DESCRIPTION +Do not use any of the interfaces documented here. +They are provided purely for compatibility with legacy application code. +.Pp +.Fn OPENSSL_malloc , +.Fn OPENSSL_realloc , +.Fn OPENSSL_free , +and +.Fn OPENSSL_strdup +have the same semantics as +.Xr malloc 3 , +.Xr realloc 3 , +.Xr free 3 , +and +.Xr strdup 3 . +They are wrapper macros around +.Fn CRYPTO_malloc , +.Fn CRYPTO_realloc , +.Fn CRYPTO_free , +and +.Fn CRYPTO_strdup , +which in turn are wrapper functions around +.Xr malloc 3 , +.Xr realloc 3 , +.Xr free 3 , +and +.Xr strdup 3 . +.Pp +.Fn OPENSSL_cleanse +has the same semantics as and is a wrapper around +.Xr explicit_bzero 3 . +.Pp +.Fn CRYPTO_get_mem_functions +assigns pointers to the C library functions +.Xr malloc 3 , +.Xr realloc 3 , +and +.Xr free 3 +to those of its arguments that are not +.Dv NULL. +.Pp +.Fn CRYPTO_set_mem_functions , +.Fn CRYPTO_mem_ctrl , +.Fn CRYPTO_mem_leaks , +and +.Fn CRYPTO_mem_leaks_fp +have no effect. +.Sh RETURN VALUES +.Fn OPENSSL_malloc , +.Fn OPENSSL_realloc , +.Fn CRYPTO_malloc , +.Fn CRYPTO_realloc , +and +.Fn OPENSSL_strdup +return a pointer to allocated memory or +.Dv NULL +on error. +.Pp +.Fn CRYPTO_set_mem_functions +always returns 0. +.Pp +.Fn CRYPTO_mem_ctrl +always returns +.Dv CRYPTO_MEM_CHECK_OFF . -- cgit v1.2.3-55-g6feb