From 103c7e6c70cfbcb48205e4b0271b1f7cdf444f8b Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 20 Oct 2021 05:06:36 +0000 Subject: [PATCH] new manual page X509_ATTRIBUTE_get0_object(3) documenting the four X.501 Attribute read accessors --- lib/libcrypto/man/Makefile | 3 +- .../man/X509_ATTRIBUTE_get0_object.3 | 135 ++++++++++++++++++ lib/libcrypto/man/X509_ATTRIBUTE_new.3 | 3 +- 3 files changed, 139 insertions(+), 2 deletions(-) create mode 100644 lib/libcrypto/man/X509_ATTRIBUTE_get0_object.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 9c84d130c58..97c6b3e9a4f 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.193 2021/10/19 17:42:49 schwarze Exp $ +# $OpenBSD: Makefile,v 1.194 2021/10/20 05:06:36 schwarze Exp $ .include @@ -276,6 +276,7 @@ MAN= \ X25519.3 \ X509V3_get_d2i.3 \ X509_ALGOR_dup.3 \ + X509_ATTRIBUTE_get0_object.3 \ X509_ATTRIBUTE_new.3 \ X509_CINF_new.3 \ X509_CRL_get0_by_serial.3 \ diff --git a/lib/libcrypto/man/X509_ATTRIBUTE_get0_object.3 b/lib/libcrypto/man/X509_ATTRIBUTE_get0_object.3 new file mode 100644 index 00000000000..72a65579853 --- /dev/null +++ b/lib/libcrypto/man/X509_ATTRIBUTE_get0_object.3 @@ -0,0 +1,135 @@ +.\" $OpenBSD: X509_ATTRIBUTE_get0_object.3,v 1.1 2021/10/20 05:06:36 schwarze Exp $ +.\" +.\" Copyright (c) 2021 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. +.\" +.Dd $Mdocdate: October 20 2021 $ +.Dt X509_ATTRIBUTE_GET0_OBJECT 3 +.Os +.Sh NAME +.Nm X509_ATTRIBUTE_get0_object , +.Nm X509_ATTRIBUTE_count , +.Nm X509_ATTRIBUTE_get0_type , +.Nm X509_ATTRIBUTE_get0_data +.\" In the following line, "X.501" and "Attribute" are not typos. +.\" The "Attribute" type is defined in X.501, not in X.509. +.\" The type is called "Attribute" with capital "A", not "attribute". +.Nd X.501 Attribute read accessors +.Sh SYNOPSIS +.In openssl/x509.h +.Ft ASN1_OBJECT * +.Fo X509_ATTRIBUTE_get0_object +.Fa "X509_ATTRIBUTE *attr" +.Fc +.Ft int +.Fo X509_ATTRIBUTE_count +.Fa "const X509_ATTRIBUTE *attr" +.Fc +.Ft ASN1_TYPE * +.Fo X509_ATTRIBUTE_get0_type +.Fa "X509_ATTRIBUTE *attr" +.Fa "int index" +.Fc +.Ft void * +.Fo X509_ATTRIBUTE_get0_data +.Fa "X509_ATTRIBUTE *attr" +.Fa "int index" +.Fa "int type" +.Fa "void *data" +.Fc +.Sh DESCRIPTION +These functions provide read access to the X.501 Attribute object +.Fa attr . +.Pp +For +.Fn X509_ATTRIBUTE_get0_data , +the +.Fa type +argument usually is one of the +.Dv V_ASN1_* +constants defined in +.In openssl/asn1.h . +For example, if a return value of the type +.Vt ASN1_OCTET_STRING +is expected, pass +.Dv V_ASN1_OCTET_STRING +as the +.Fa type +argument. +The +.Fa data +argument is ignored; passing +.Dv NULL +is recommended. +.Sh RETURN VALUES +.Fn X509_ATTRIBUTE_get0_object +returns an internal pointer to the type of +.Fa attr +or +.Dv NULL +if +.Fa attr +is +.Dv NULL +or if its type is not set. +.Pp +.Fn X509_ATTRIBUTE_count +returns the number of values stored in +.Fa attr +or 0 if no value or values are set. +.Pp +.Fn X509_ATTRIBUTE_get0_type +returns an internal pointer to the ASN.1 ANY object +representing the value with the given zero-based +.Fa index +or +.Dv NULL +if +.Fa attr +is +.Dv NULL , +if the +.Fa index +is larger than or equal to the number of values stored in +.Fa attr , +or if no value or values are set. +.Pp +.Fn X509_ATTRIBUTE_get0_data +returns an internal pointer to the data +contained in the value with the given zero-based +.Fa index +or +.Dv NULL +if +.Fa attr +is +.Dv NULL , +if the +.Fa index +is larger than or equal to the number of values stored in +.Fa attr , +if no value or values are set, +or if the ASN.1 ANY object representing the value with the given +.Fa index +is not of the requested +.Fa type . +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr ASN1_TYPE_new 3 , +.Xr OPENSSL_sk_new 3 , +.Xr X509_ATTRIBUTE_new 3 +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.5 +and have been available since +.Ox 2.7 . diff --git a/lib/libcrypto/man/X509_ATTRIBUTE_new.3 b/lib/libcrypto/man/X509_ATTRIBUTE_new.3 index aa14ea20998..cd3d90e4c96 100644 --- a/lib/libcrypto/man/X509_ATTRIBUTE_new.3 +++ b/lib/libcrypto/man/X509_ATTRIBUTE_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.9 2021/10/20 03:31:20 schwarze Exp $ +.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.10 2021/10/20 05:06:36 schwarze Exp $ .\" .\" Copyright (c) 2016, 2021 Ingo Schwarze .\" @@ -115,6 +115,7 @@ fails on .Xr PKCS12_SAFEBAG_new 3 , .Xr PKCS7_add_attribute 3 , .Xr PKCS8_PRIV_KEY_INFO_new 3 , +.Xr X509_ATTRIBUTE_get0_object 3 , .Xr X509_EXTENSION_new 3 , .Xr X509_new 3 , .Xr X509_REQ_new 3 -- 2.20.1