Document X509_EXTENSION_new(3) and X509_EXTENSION_free(3) listed

in <openssl/x509.h> and in OpenSSL doc/man3/X509_dup.pod.

Explain what an X509_EXTENSION object is and where it is used.
Add STANDARDS references.
Sort the functions into a more logical order.
Link to all other pages dealing with X509_EXTENSION objects.

1 files changed, 106 insertions, 53 deletions

diff --git a/lib/libcrypto/man/X509_EXTENSION_set_object.3 b/lib/libcrypto/man/X509_EXTENSION_set_object.3
index 32bb9c6828e..4dcf9875463 100644
--- a/lib/libcrypto/man/X509_EXTENSION_set_object.3
+++ b/lib/libcrypto/man/X509_EXTENSION_set_object.3
@@ -1,7 +1,24 @@
-.\"	$OpenBSD: X509_EXTENSION_set_object.3,v 1.1 2016/12/04 20:51:47 schwarze Exp $
+.\"	$OpenBSD: X509_EXTENSION_set_object.3,v 1.2 2016/12/15 15:13:54 schwarze Exp $
 .\"	OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2016 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 Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2015 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,20 +65,41 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 4 2016 $
+.Dd $Mdocdate: December 15 2016 $
 .Dt X509_EXTENSION_SET_OBJECT 3
 .Os
 .Sh NAME
+.Nm X509_EXTENSION_new ,
+.Nm X509_EXTENSION_free ,
+.Nm X509_EXTENSION_create_by_NID ,
+.Nm X509_EXTENSION_create_by_OBJ ,
 .Nm X509_EXTENSION_set_object ,
 .Nm X509_EXTENSION_set_critical ,
 .Nm X509_EXTENSION_set_data ,
-.Nm X509_EXTENSION_create_by_NID ,
-.Nm X509_EXTENSION_create_by_OBJ ,
 .Nm X509_EXTENSION_get_object ,
 .Nm X509_EXTENSION_get_critical ,
 .Nm X509_EXTENSION_get_data
-.Nd extension utility functions
+.Nd create, change, and inspect X.509 Extension objects
 .Sh SYNOPSIS
+.In openssl/x509.h
+.Ft X509_EXTENSION *
+.Fn X509_EXTENSION_new void
+.Ft void
+.Fn X509_EXTENSION_free "X509_EXTENSION *ex"
+.Ft X509_EXTENSION *
+.Fo X509_EXTENSION_create_by_NID
+.Fa "X509_EXTENSION **ex"
+.Fa "int nid"
+.Fa "int crit"
+.Fa "ASN1_OCTET_STRING *data"
+.Fc
+.Ft X509_EXTENSION *
+.Fo X509_EXTENSION_create_by_OBJ
+.Fa "X509_EXTENSION **ex"
+.Fa "ASN1_OBJECT *obj"
+.Fa "int crit"
+.Fa "ASN1_OCTET_STRING *data"
+.Fc
 .Ft int
 .Fo X509_EXTENSION_set_object
 .Fa "X509_EXTENSION *ex"
@@ -77,20 +115,6 @@
 .Fa "X509_EXTENSION *ex"
 .Fa "ASN1_OCTET_STRING *data"
 .Fc
-.Ft X509_EXTENSION *
-.Fo X509_EXTENSION_create_by_NID
-.Fa "X509_EXTENSION **ex"
-.Fa "int nid"
-.Fa "int crit"
-.Fa "ASN1_OCTET_STRING *data"
-.Fc
-.Ft X509_EXTENSION *
-.Fo X509_EXTENSION_create_by_OBJ
-.Fa "X509_EXTENSION **ex"
-.Fa "ASN1_OBJECT *obj"
-.Fa "int crit"
-.Fa "ASN1_OCTET_STRING *data"
-.Fc
 .Ft ASN1_OBJECT *
 .Fo X509_EXTENSION_get_object
 .Fa "X509_EXTENSION *ex"
@@ -104,6 +128,53 @@
 .Fa "X509_EXTENSION *ne"
 .Fc
 .Sh DESCRIPTION
+.Fn X509_EXTENSION_new
+allocates and initializes an empty
+.Vt X509_EXTENSION
+object, representing an ASN.1 Extension structure
+defined in RFC 5280 section 4.1.
+It is a wrapper object around specific extension objects of different
+types and stores an extension type identifier and a criticality
+flag in addition to the DER-encoded form of the wrapped object.
+.Vt X509_EXTENSION
+objects can be used for X.509 v3 certificates inside
+.Vt X509_CINF
+objects and for X.509 v2 certificate revocation lists inside
+.Vt X509_CRL_INFO
+and
+.Vt X509_REVOKED
+objects.
+.Pp
+.Fn X509_EXTENSION_free
+frees
+.Fa ex
+and all objects it is using.
+.Pp
+.Fn X509_EXTENSION_create_by_NID
+creates an extension of type
+.Fa nid
+and criticality
+.Fa crit
+using data
+.Fa data .
+The created extension is returned and written to
+.Pf * Fa ex
+reusing or allocating a new extension if necessary, so
+.Pf * Fa ex
+should either be
+.Dv NULL
+or a valid
+.Vt X509_EXTENSION
+structure.
+It must not be an uninitialised pointer.
+.Pp
+.Fn X509_EXTENSION_create_by_OBJ
+is identical to
+.Fn X509_EXTENSION_create_by_NID
+except that it creates an extension using
+.Fa obj
+instead of a NID.
+.Pp
 .Fn X509_EXTENSION_set_object
 sets the extension type of
 .Fa ex
@@ -133,31 +204,6 @@ The
 .Fa data
 pointer is duplicated internally.
 .Pp
-.Fn X509_EXTENSION_create_by_NID
-creates an extension of type
-.Fa nid ,
-criticality
-.Fa crit
-using data
-.Fa data .
-The created extension is returned and written to
-.Pf * Fa ex
-reusing or allocating a new extension if necessary, so
-.Pf * Fa ex
-should either be
-.Dv NULL
-or a valid
-.Vt X509_EXTENSION
-structure.
-It must not be an uninitialised pointer.
-.Pp
-.Fn X509_EXTENSION_create_by_OBJ
-is identical to
-.Fn X509_EXTENSION_create_by_NID
-except that it creates an extension using
-.Fa obj
-instead of a NID.
-.Pp
 .Fn X509_EXTENSION_get_object
 returns the extension type of
 .Fa ex
@@ -190,13 +236,8 @@ associated with an extension is the extension encoding in an
 .Vt ASN1_OCTET_STRING
 structure.
 .Sh RETURN VALUES
-.Fn X509_EXTENSION_set_object ,
-.Fn X509_EXTENSION_set_critical ,
-and
-.Fn X509_EXTENSION_set_data
-return 1 for success or 0 for failure.
-.Pp
-.Fn X509_EXTENSION_create_by_NID
+.Fn X509_EXTENSION_new ,
+.Fn X509_EXTENSION_create_by_NID ,
 and
 .Fn X509_EXTENSION_create_by_OBJ
 return an
@@ -205,6 +246,12 @@ pointer or
 .Dv NULL
 if an error occurs.
 .Pp
+.Fn X509_EXTENSION_set_object ,
+.Fn X509_EXTENSION_set_critical ,
+and
+.Fn X509_EXTENSION_set_data
+return 1 for success or 0 for failure.
+.Pp
 .Fn X509_EXTENSION_get_object
 returns an
 .Vt ASN1_OBJECT
@@ -218,4 +265,10 @@ returns an
 .Vt ASN1_OCTET_STRING
 pointer.
 .Sh SEE ALSO
-.Xr X509V3_get_d2i 3
+.Xr OCSP_CRLID_new 3 ,
+.Xr OCSP_SERVICELOC_new 3 ,
+.Xr X509V3_get_d2i 3 ,
+.Xr X509v3_get_ext_by_NID
+.Sh STANDARDS
+RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
+Certificate Revocation List (CRL) Profile