From 8e0c9b4c76e2045ef1ae90f05120e1dcc1f1fa70 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Thu, 15 Dec 2016 15:13:54 +0000 Subject: Document X509_EXTENSION_new(3) and X509_EXTENSION_free(3) listed in 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. --- src/lib/libcrypto/man/X509_EXTENSION_set_object.3 | 159 ++++++++++++++-------- 1 file changed, 106 insertions(+), 53 deletions(-) (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/X509_EXTENSION_set_object.3 b/src/lib/libcrypto/man/X509_EXTENSION_set_object.3 index 32bb9c6828..4dcf987546 100644 --- a/src/lib/libcrypto/man/X509_EXTENSION_set_object.3 +++ b/src/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 . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" 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. +.\" +.\" The original file was written by Dr. Stephen Henson . .\" 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 -- cgit v1.2.3-55-g6feb