1 files changed, 295 insertions, 21 deletions

diff --git a/src/lib/libcrypto/man/CRYPTO_set_ex_data.3 b/src/lib/libcrypto/man/CRYPTO_set_ex_data.3
index 86cbadc46b..7cf8f6377c 100644
--- a/src/lib/libcrypto/man/CRYPTO_set_ex_data.3
+++ b/src/lib/libcrypto/man/CRYPTO_set_ex_data.3
@@ -1,5 +1,5 @@
-.\"     $OpenBSD: CRYPTO_set_ex_data.3,v 1.4 2016/11/23 16:28:23 schwarze Exp $
-.\"     OpenSSL 35cb565a Nov 19 15:49:30 2015 -0500
+.\"     $OpenBSD: CRYPTO_set_ex_data.3,v 1.5 2016/11/28 22:25:51 schwarze Exp $
+.\"     OpenSSL CRYPTO_get_ex_new_index.pod 35cb565a Nov 19 15:49:30 2015 -0500
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2006 The OpenSSL Project.  All rights reserved.
@@ -47,17 +47,115 @@
 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"     OpenSSL
 .\"
-.Dd $Mdocdate: November 23 2016 $
+.\" This file was written by Dr. Stephen Henson <steve@openssl.org>
+.\" and by Rich Salz <rsalz@akamai.com>.
+.\" Copyright (c) 2000, 2006, 2015, 2016 The OpenSSL Project.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: November 28 2016 $
 .Dt CRYPTO_SET_EX_DATA 3
 .Os
 .Sh NAME
+.Nm CRYPTO_EX_new ,
+.Nm CRYPTO_EX_free ,
+.Nm CRYPTO_EX_dup ,
+.Nm CRYPTO_get_ex_new_index ,
 .Nm CRYPTO_set_ex_data ,
-.Nm CRYPTO_get_ex_data
-.Nd internal application specific data functions
+.Nm CRYPTO_get_ex_data ,
+.Nm CRYPTO_free_ex_data ,
+.Nm CRYPTO_new_ex_data
+.Nd functions supporting application-specific data
 .Sh SYNOPSIS
 .In openssl/crypto.h
 .Ft int
+.Fo CRYPTO_get_ex_new_index
+.Fa "int class_index"
+.Fa "long argl"
+.Fa "void *argp"
+.Fa "CRYPTO_EX_new *new_func"
+.Fa "CRYPTO_EX_dup *dup_func"
+.Fa "CRYPTO_EX_free *free_func"
+.Fc
+.Ft typedef int
+.Fo CRYPTO_EX_new
+.Fa "void *parent"
+.Fa "void *ptr"
+.Fa "CRYPTO_EX_DATA *ad"
+.Fa "int idx"
+.Fa "long argl"
+.Fa "void *argp"
+.Fc
+.Ft typedef void
+.Fo CRYPTO_EX_free
+.Fa "void *parent"
+.Fa "void *ptr"
+.Fa "CRYPTO_EX_DATA *ad"
+.Fa "int idx"
+.Fa "long argl"
+.Fa "void *argp"
+.Fc
+.Ft typedef int
+.Fo CRYPTO_EX_dup
+.Fa "CRYPTO_EX_DATA *to"
+.Fa "const CRYPTO_EX_DATA *from"
+.Fa "void *from_d"
+.Fa "int idx"
+.Fa "long argl"
+.Fa "void *argp"
+.Fc
+.Ft int
+.Fo CRYPTO_new_ex_data
+.Fa "int class_index"
+.Fa "void *obj"
+.Fa "CRYPTO_EX_DATA *ad"
+.Fc
+.Ft int
 .Fo CRYPTO_set_ex_data
 .Fa "CRYPTO_EX_DATA *r"
 .Fa "int idx"
@@ -68,22 +166,191 @@
 .Fa "CRYPTO_EX_DATA *r"
 .Fa "int idx"
 .Fc
+.Ft void
+.Fo CRYPTO_free_ex_data
+.Fa "int class_index"
+.Fa "void *obj"
+.Fa "CRYPTO_EX_DATA *r"
+.Fc
 .Sh DESCRIPTION
 Several OpenSSL structures can have application specific data attached
-to them.
-These functions are used internally by OpenSSL to manipulate application
-specific data attached to a specific structure.
+to them, known as "exdata."
+The specific structures are:
+.Bd -literal
+    SSL
+    SSL_CTX
+    SSL_SESSION
+    X509
+    X509_STORE
+    X509_STORE_CTX
+    DH
+    DSA
+    RSA
+    ENGINE
+    UI
+    BIO
+.Ed
 .Pp
-These functions should only be used by applications to manipulate
+Each is identified by a
+.Dv CRYPTO_EX_INDEX_*
+constant defined in the
+.In openssl/crypto.h
+header file.
+.Pp
+The API described here is used by OpenSSL to manipulate exdata for
+specific structures.
+Since the application data can be anything at all it is passed and
+retrieved as a
+.Vt void *
+type.
+.Pp
+The
 .Vt CRYPTO_EX_DATA
-structures passed to the
-.Fn new_func ,
-.Fn free_func ,
+type is opaque.
+To initialize the exdata part of a structure, call
+.Fn CRYPTO_new_ex_data .
+.Pp
+Exdata types are identified by an index, an integer guaranteed to
+be unique within structures for the lifetime of the program.
+Applications using exdata typically call
+.Fn CRYPTO_get_ex_new_index
+at startup and store the result in a global variable, or write a
+wrapper function to provide lazy evaluation.
+The
+.Fa class_index
+should be one of the
+.Dv CRYPTO_EX_INDEX_*
+values.
+The
+.Fa argl
 and
-.Fn dup_func
-callbacks, as passed to
-.Xr RSA_get_ex_new_index 3 ,
-for example.
+.Fa argp
+parameters are saved to be passed to the callbacks but are otherwise not
+used.
+In order to transparently manipulate exdata, three callbacks must be
+provided.
+The semantics of those callbacks are described below.
+.Pp
+When copying or releasing objects with exdata, the callback functions
+are called in increasing order of their index value.
+.Pp
+To set or get the exdata on an object, the appropriate type-specific
+routine must be used.
+This is because the containing structure is opaque and the
+.Vt CRYPTO_EX_DATA
+field is not accessible.
+In both APIs, the
+.Fa idx
+parameter should be an already-created index value.
+.Pp
+When setting exdata, the pointer specified with a particular index is
+saved, and returned on a subsequent "get" call.
+If the application is going to release the data, it must make sure to
+set a
+.Dv NULL
+value at the index, to avoid likely double-free crashes.
+.Pp
+The function
+.Fn CRYPTO_free_ex_data
+is used to free all exdata attached to a structure.
+The appropriate type-specific routine must be used.
+The
+.Fa class_index
+identifies the structure type, the
+.Fa obj
+is be the pointer to the actual structure, and
+.Fa r
+is a pointer to the structure's exdata field.
+.Pp
+The callback functions are used as follows.
+.Pp
+When a structure is initially allocated (such as by
+.Xr RSA_new 3 ) ,
+then
+.Fa new_func
+is called for every defined index.
+There is no requirement that the entire parent, or containing, structure
+has been set up.
+The
+.Fa new_func
+is typically used only to allocate memory to store the
+exdata, and perhaps an "initialized" flag within that memory.
+The exdata value should be set by calling
+.Fn CRYPTO_set_ex_data .
+.Pp
+When a structure is free'd (such as by
+.Xr SSL_CTX_free 3 ) ,
+then the
+.Fa free_func
+is called for every defined index.
+Again, the state of the parent structure is not guaranteed.
+The
+.Fa free_func
+may be called with a
+.Dv NULL
+pointer.
+.Pp
+Both
+.Fa new_func
+and
+.Fa free_func
+take the same parameters.
+The
+.Fa parent
+is the pointer to the structure that contains the exdata.
+The
+.Fa ptr
+is the current exdata item; for
+.Fa new_func
+this will typically be
+.Dv NULL .
+The
+.Fa r
+parameter is a pointer to the exdata field of the object.
+The
+.Fa idx
+is the index and is the value returned when the callbacks were initially
+registered via
+.Fn CRYPTO_get_ex_new_index
+and can be used if the same callback handles different types of exdata.
+.Pp
+.Fa dup_func
+is called when a structure is being copied.
+This is only done for
+.Vt SSL
+and
+.Vt SSL_SESSION
+objects.
+The
+.Fa to
+and
+.Fa from
+parameters are pointers to the destination and source
+.Vt CRYPTO_EX_DATA
+structures, respectively.
+The
+.Fa from_d
+parameter is a pointer to the source exdata.
+When
+.Fa dup_func
+returns, the value in
+.Fa from_d
+is copied to the destination ex_data.
+If the pointer contained in
+.Fa from_d
+is not modified by the
+.Fa dup_func ,
+then both
+.Fa to
+and
+.Fa from
+will point to the same data.
+The
+.Fa idx ,
+.Fa argl
+and
+.Fa argp
+parameters are as described for the other two callbacks.
 .Pp
 .Fn CRYPTO_set_ex_data
 is used to set application specific data.
@@ -98,15 +365,22 @@ supplied to a previous
 .Fn CRYPTO_set_ex_data
 call.
 .Sh RETURN VALUES
+.Fn CRYPTO_get_ex_new_index
+returns a new index or -1 on failure; the value 0 is reserved for
+the legacy "app_data" APIs.
+.Pp
 .Fn CRYPTO_set_ex_data
 returns 1 on success or 0 on failure.
 .Pp
 .Fn CRYPTO_get_ex_data
-returns the application data or 0 on failure.
-0 may also be valid application data but currently it can only fail if
-given an invalid
-.Fa idx
-parameter.
+returns the application data or
+.Dv NULL
+on failure; note that
+.Dv NULL
+may be a valid value.
+.Pp
+.Fa dup_func
+should return 0 for failure and 1 for success.
 .Pp
 On failure an error code can be obtained from
 .Xr ERR_get_error 3 .