From be9b7c25b1703b7a4b60a7c73377ba93accb2783 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 28 Nov 2016 22:25:51 +0000 Subject: Add Copyright and license. Merge the documentation of six additional functions from OpenSSL. There are some differences between OpenSSL and LibreSSL, for example we don't have CRYPTO_free_ex_index(), CRYPTO_EX_INDEX_EC_KEY, and CRYPTO_EX_INDEX_APP. I hope i got the differences right. "if you don;t get any feedback promptly i say just go ahead" jmc@ --- src/lib/libcrypto/man/CRYPTO_set_ex_data.3 | 316 +++++++++++++++++++++++++++-- 1 file changed, 295 insertions(+), 21 deletions(-) (limited to 'src/lib/libcrypto/man/CRYPTO_set_ex_data.3') 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 . .\" 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 +.\" and by Rich Salz . +.\" 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 . -- cgit v1.2.3-55-g6feb