1 files changed, 285 insertions, 36 deletions

diff --git a/src/lib/libcrypto/man/crypto.3 b/src/lib/libcrypto/man/crypto.3
index 6e98f643de..598eb30504 100644
--- a/src/lib/libcrypto/man/crypto.3
+++ b/src/lib/libcrypto/man/crypto.3
@@ -1,7 +1,24 @@
-.\"     $OpenBSD: crypto.3,v 1.25 2020/06/24 17:00:38 schwarze Exp $
+.\"     $OpenBSD: crypto.3,v 1.26 2021/12/09 15:11:48 schwarze Exp $
 .\"     OpenSSL a9c85cea Nov 11 09:33:55 2016 +0100
 .\"
-.\" This file was written by Ulf Moeller <ulf@openssl.org> and
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" 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.
+.\"
+.\" The original file was written by Ulf Moeller <ulf@openssl.org> and
 .\" Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2002 The OpenSSL Project.  All rights reserved.
 .\"
@@ -49,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 24 2020 $
+.Dd $Mdocdate: December 9 2021 $
 .Dt CRYPTO 3
 .Os
 .Sh NAME
@@ -139,43 +156,275 @@ include
 .Xr lh_new 3 ,
 and
 .Xr STACK_OF 3 .
+.Sh NAMING CONVENTIONS
+Elements used in the names of API functions include the following:
+.Bl -tag -width Ds
+.It add0
+See
+.Dq set0
+below.
+.It add1
+See
+.Dq set1
+below.
+.It BIO
+basic input and/or output abstraction:
+The function manipulates objects of the idiosyncratic OpenSSL
+.Vt BIO
+object type.
+See
+.Xr BIO_new 3 .
+.It bio
+The function uses a
+.Vt BIO
+object for input or output.
+In many cases, simpler variants of the function are available
+that operate directly on
+.In stdio.h
+.Vt FILE
+objects or directly in RAM, usually using byte arrays.
+.It BIO_f_
+filter BIO:
+The function returns a pointer to a static built-in object that,
+when passed to
+.Xr BIO_new 3 ,
+results in the creation of a BIO object that can write data to
+and/or read data from another
+.Vt BIO
+object.
+.It BIO_s_
+source and/or sink BIO:
+The function returns a pointer to a static built-in object that,
+when passed to
+.Xr BIO_new 3 ,
+results in the creation of a BIO object
+that can write data to an external destination
+and/or read data from an external source,
+for example a file descriptor or object, a memory buffer, or the network.
+.It BN
+big number:
+The function operates on
+.Vt BIGNUM
+objects representing integer numbers of variable, almost unlimited size.
+See
+.Xr BN_new 3 .
+.It cb
+callback:
+The function takes or returns a function pointer
+that is called by API functions from inside the library.
+The function pointed to may be defined by the application program.
+In some cases, API functions with
+.Dq cb
+in their name may return function pointers to internal functions
+defined inside the library that are not API functions.
+The element
+.Dq cb
+is also used in the names of some function pointer datatypes
+declared with
+.Sy typedef .
+In a small number of cases, the all caps form
+.Dq CB
+is used with the same meaning.
+.It CTX
+context:
+The function operates on a wrapper object around another object.
+The purposes and properties of such
+.Dq CTX
+wrapper objects vary wildly depending on the objects in question.
+A few function names use the lower case form
+.Dq ctx
+in the same sense.
+.It d2i
+DER to internal:
+The function decodes input conforming to ASN.1 basic encoding rules (BER)
+and either stores the result in an existing object
+or in a newly allocated object.
+The latter is usually preferable because
+creating a new object is more robust and less error prone.
+In spite of the name, the input usually does not need to conform to ASN.1
+distinguished encoding rules (DER), which are more restrictive than BER.
+.It EVP
+digital EnVeloPe library:
+See
+.Xr evp 3 .
+.It ex
+This name element is used for two completely unrelated purposes.
 .Pp
-Some of the newer functions follow a naming convention using the numbers
-.Sq 0
-and
-.Sq 1 .
-For example consider the names of these functions:
+extended version:
+The function is similar to an older function without the
+.Dq ex
+in its name, but takes one or more additional arguments
+in order to make it more versatile.
+In several cases, the older version is now deprecated.
 .Pp
-.Ft int
-.Fo X509_CRL_add0_revoked
-.Fa "X509_CRL *crl"
-.Fa "X509_REVOKED *rev"
-.Fc
-.br
-.Ft int
-.Fo X509_add1_trust_object
-.Fa "X509 *x"
-.Fa "ASN1_OBJECT *obj"
-.Fc
+extra data:
+Some object types support storing additional, application-specific data
+inside objects in addition to the data the object is designed to hold.
+The function sets, retrieves, or prepares for using such extra data.
+Related function names usually contain
+.Dq ex_data
+or
+.Dq ex_new_index .
+See
+.Xr CRYPTO_set_ex_data 3 .
+.It fp
+file pointer:
+The function takes a
+.Vt FILE *
+argument.
+Usually, the function is a variant of another function taking a
+.Vt BIO *
+argument instead.
+.It i2d
+internal to DER:
+The function encodes an object passed as an argument
+according to ASN.1 distinguished encoding rules (DER).
+There are a few rare excpetions of functions that have
+.Dq i2d
+in their name but produce output anyway
+that only conforms to ASN.1 basic encoding rules (BER) and not to DER.
+.It get0
+The function returns an internal pointer
+owned by the object passed as an argument.
+The returned pointer must not be freed by the calling code.
+It will be freed automatically
+when the object owning the pointer will be freed.
+.It get1
+The function returns a copy of a sub-object
+of an object passed as an argument.
+The caller is responsible for freeing the returned object
+when it is no longer needed.
 .Pp
-The
-.Sq 0
-version uses the supplied structure pointer directly in the parent and
-it will be freed up when the parent is freed.
-In the above example
-.Fa crl
-would be freed but
-.Fa rev
-would not.
+If the object type is reference counted, usually the reference count
+is incremented instead of copying the object.
+Consequently, modifying the returned object may still impact all
+objects containing references to it.
+The caller is responsible for freeing the returned object
+when it is no longer needed; for reference-counted objects still
+referenced elsewhere, this will merely decrement the reference count.
+.It get
+Functions containing
+.Dq get
+in their name without a following digit may behave in
+.Dq get0
+or, more rarely, in
+.Dq get1
+style.
+To find out which is the case, refer to the individual manual pages.
+.It lh
+linear hash:
+The function manipulates a dynamic hash table.
+See
+.Xr lh_new 3 .
+.It md
+message digest.
+Some function names use the all caps form
+.Dq MD
+in the same sense.
+.It meth
+The function manipulates an object holding a function table.
+Usually, such function tables allow the application program
+to implement additional cryptographic or I/O algorithms
+and to use them with the same high-level API functions as the
+algorithms provided by the library itself, or to replace the
+implementations of algorithms provided by the library with
+custom implementations provided by the application program.
+Some API functions use the name elements
+.Dq method
+or
+.Dq METHOD
+in the same sense.
+See also the
+.Dq cb
+entry in the present list.
+.It ndef
+indefinite length form:
+The function encodes according to ASN.1 basic encoding rules (BER)
+using the indefinite length form.
+Even if the function name also includes
+.Dq i2d ,
+the output does not conform to ASN.1 distinguished encoding rules (DER).
+See
+.Xr ASN1_item_ndef_i2d 3 .
+Some function names contain the all caps version
+.Dq NDEF
+with the same meaning.
+.It nid
+numerical identifier:
+A non-standard, LibreSSL-specific
+.Vt int
+number associated with an ASN.1 object identifier.
+In several cases, the all caps form
+.Dq NID
+is used in the same sense.
+See
+.Xr OBJ_nid2obj 3 .
+.It obj
+This name element and its all caps form
+.Dq OBJ
+usually refer to ASN.1 object identifiers represented by the
+.Vt ASN1_OBJECT
+data type.
+See
+.Xr ASN1_OBJECT_new 3 .
+.It PKEY
+In most cases, this name element and its lower case form
+.Dq pkey
+mean
+.Dq private key ,
+but for both forms, there are some cases where they mean
+.Dq public key
+instead.
+.It set0
+The function transfers ownership of a pointer passed as an argument
+to an object passed as another argument,
+by storing the pointer inside the object.
+The transferred pointer must not be freed by the calling code.
+It will be freed automatically
+when the object now owning the pointer will be freed.
+.It set1
+The function copies the content of one object passed as an argument
+into another object also passed as an argument.
+When the calling code no longer needs the copied object,
+it can free that object.
 .Pp
-The
-.Sq 1
-function uses a copy of the supplied structure pointer (or in some cases
-increases its link count) in the parent and so both
-.Pf ( Fa x
-and
-.Fa obj
-above) should be freed up.
+In some cases, if the object to be copied is reference counted,
+the function does not actually copy the object but merely increments
+its reference count and stores the pointer to it in the other object.
+When the calling code no longer needs its original pointer to
+the now inner object, it can free the original pointer, thus
+decrementing the reference count of the inner object
+and transferring ownership of the inner object to the outer object.
+The inner object will then be freed automatically
+when the outer object is freed later on.
+.It set
+Functions containing
+.Dq set
+in their name without a following digit may behave in
+.Dq set0
+or, more rarely, in
+.Dq set1
+style.
+To find out which is the case, refer to the individual manual pages.
+.It sk
+stack:
+The function manipulates a variable-sized array of pointers
+in the idiosyncratic style described in
+.Xr OPENSSL_sk_new 3 .
+.It TS
+X.509 time-stamp protocol:
+See
+.Xr TS_REQ_new 3 .
+.It up_ref
+The function increments the reference count of the argument by one.
+Only a minority of object types support reference counting.
+For those that do, if the reference count is greater than one,
+the corresponding
+.Dq free
+function reverses the effect of one call to the
+.Dq up_ref
+function rather than freeing the object.
+.El
 .Sh SEE ALSO
 .Xr openssl 1 ,
 .Xr ssl 3