From 8f31a7ac73ecf71d0e9fc44c8c8de11e6d378783 Mon Sep 17 00:00:00 2001 From: schwarze Date: Thu, 21 Oct 2021 16:26:34 +0000 Subject: [PATCH] new manual page X509_ATTRIBUTE_set1_object(3) documenting five X.501 Attribute write accessors --- lib/libcrypto/man/Makefile | 3 +- .../man/X509_ATTRIBUTE_get0_object.3 | 7 +- lib/libcrypto/man/X509_ATTRIBUTE_new.3 | 5 +- .../man/X509_ATTRIBUTE_set1_object.3 | 267 ++++++++++++++++++ 4 files changed, 276 insertions(+), 6 deletions(-) create mode 100644 lib/libcrypto/man/X509_ATTRIBUTE_set1_object.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 0f6b84a1b6e..51c2cf45b7f 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.195 2021/10/20 13:14:00 schwarze Exp $ +# $OpenBSD: Makefile,v 1.196 2021/10/21 16:26:34 schwarze Exp $ .include @@ -279,6 +279,7 @@ MAN= \ X509_ALGOR_dup.3 \ X509_ATTRIBUTE_get0_object.3 \ X509_ATTRIBUTE_new.3 \ + X509_ATTRIBUTE_set1_object.3 \ X509_CINF_new.3 \ X509_CRL_get0_by_serial.3 \ X509_CRL_new.3 \ diff --git a/lib/libcrypto/man/X509_ATTRIBUTE_get0_object.3 b/lib/libcrypto/man/X509_ATTRIBUTE_get0_object.3 index 72a65579853..4212e27d7ec 100644 --- a/lib/libcrypto/man/X509_ATTRIBUTE_get0_object.3 +++ b/lib/libcrypto/man/X509_ATTRIBUTE_get0_object.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_ATTRIBUTE_get0_object.3,v 1.1 2021/10/20 05:06:36 schwarze Exp $ +.\" $OpenBSD: X509_ATTRIBUTE_get0_object.3,v 1.2 2021/10/21 16:26:34 schwarze Exp $ .\" .\" Copyright (c) 2021 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" 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 $ +.Dd $Mdocdate: October 21 2021 $ .Dt X509_ATTRIBUTE_GET0_OBJECT 3 .Os .Sh NAME @@ -128,7 +128,8 @@ is not of the requested .Xr ASN1_OBJECT_new 3 , .Xr ASN1_TYPE_new 3 , .Xr OPENSSL_sk_new 3 , -.Xr X509_ATTRIBUTE_new 3 +.Xr X509_ATTRIBUTE_new 3 , +.Xr X509_ATTRIBUTE_set1_object 3 .Sh HISTORY These functions first appeared in OpenSSL 0.9.5 and have been available since diff --git a/lib/libcrypto/man/X509_ATTRIBUTE_new.3 b/lib/libcrypto/man/X509_ATTRIBUTE_new.3 index cd3d90e4c96..e0cff822dac 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.10 2021/10/20 05:06:36 schwarze Exp $ +.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.11 2021/10/21 16:26:34 schwarze Exp $ .\" .\" Copyright (c) 2016, 2021 Ingo Schwarze .\" @@ -14,7 +14,7 @@ .\" 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 $ +.Dd $Mdocdate: October 21 2021 $ .Dt X509_ATTRIBUTE_NEW 3 .Os .Sh NAME @@ -116,6 +116,7 @@ fails on .Xr PKCS7_add_attribute 3 , .Xr PKCS8_PRIV_KEY_INFO_new 3 , .Xr X509_ATTRIBUTE_get0_object 3 , +.Xr X509_ATTRIBUTE_set1_object 3 , .Xr X509_EXTENSION_new 3 , .Xr X509_new 3 , .Xr X509_REQ_new 3 diff --git a/lib/libcrypto/man/X509_ATTRIBUTE_set1_object.3 b/lib/libcrypto/man/X509_ATTRIBUTE_set1_object.3 new file mode 100644 index 00000000000..6a578050711 --- /dev/null +++ b/lib/libcrypto/man/X509_ATTRIBUTE_set1_object.3 @@ -0,0 +1,267 @@ +.\" $OpenBSD: X509_ATTRIBUTE_set1_object.3,v 1.1 2021/10/21 16:26:34 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 21 2021 $ +.Dt X509_ATTRIBUTE_SET1_OBJECT 3 +.Os +.Sh NAME +.Nm X509_ATTRIBUTE_set1_object , +.Nm X509_ATTRIBUTE_set1_data , +.Nm X509_ATTRIBUTE_create_by_OBJ , +.Nm X509_ATTRIBUTE_create_by_NID , +.Nm X509_ATTRIBUTE_create_by_txt +.\" 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 modify an X.501 Attribute +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo X509_ATTRIBUTE_set1_object +.Fa "X509_ATTRIBUTE *attr" +.Fa "const ASN1_OBJECT *obj" +.Fc +.Ft int +.Fo X509_ATTRIBUTE_set1_data +.Fa "X509_ATTRIBUTE *attr" +.Fa "int type" +.Fa "const void *data" +.Fa "int len" +.Fc +.Ft X509_ATTRIBUTE * +.Fo X509_ATTRIBUTE_create_by_OBJ +.Fa "X509_ATTRIBUTE **pattr" +.Fa "const ASN1_OBJECT *obj" +.Fa "int type" +.Fa "const void *data" +.Fa "int len" +.Fc +.Ft X509_ATTRIBUTE * +.Fo X509_ATTRIBUTE_create_by_NID +.Fa "X509_ATTRIBUTE **pattr" +.Fa "int nid" +.Fa "int type" +.Fa "const void *data" +.Fa "int len" +.Fc +.Ft X509_ATTRIBUTE * +.Fo X509_ATTRIBUTE_create_by_txt +.Fa "X509_ATTRIBUTE **pattr" +.Fa "const char *name" +.Fa "int type" +.Fa "const unsigned char *bytes" +.Fa "int len" +.Fc +.Sh DESCRIPTION +.Fn X509_ATTRIBUTE_set1_object +sets the type of +.Fa attr +to +.Fa obj . +If +.Fa obj +is dynamically allocated, a deep copy is created. +If the type of +.Fa attr +was already set, the old type is freed +as far as it was dynamically allocated. +After calling this function, +.Fa attr +may be in an inconsistent state +because its values may not agree with the new attribute type. +.Pp +.Fn X509_ATTRIBUTE_set1_data +sets +.Fa attr +to be multi-valued and initializes its set of values +to contain a single new ASN.1 ANY object representing the +.Fa data . +.Pp +The interpretation of the +.Fa data +depends on the values of the +.Fa type +and +.Fa len +arguments; there are four different cases. +.Pp +If the +.Fa type +argument has the bit +.Dv MBSTRING_FLAG +set, +.Fa data +is expected to point to a multibyte character string that is +.Fa len +bytes long and uses the encoding specified by the +.Fa type +argument, and it is expected that an attribute type was already assigned to +.Fa attr , +for example by calling +.Fn X509_ATTRIBUTE_set1_object +before calling +.Fn X509_ATTRIBUTE_set1_data . +In this case, an appropriate ASN.1 multibyte string type is chosen and +a new object of that type is allocated and populated to represent the +.Fa data +by calling +.Xr ASN1_STRING_set_by_NID 3 . +The type of that new ASN.1 string object is subsequently used instead of the +.Fa type +argument. +.Pp +If the +.Fa type +argument does not have the bit +.Dv MBSTRING_FLAG +set and the +.Fa len argument +is not \-1, the +.Fa type +argument is expected to be one of the types documented in +.Xr ASN1_STRING_new 3 +and +.Fa data +is expected to point to a buffer of +.Fa len +bytes. +In this case, a new object is allocated with +.Xr ASN1_STRING_type_new 3 +and populated with +.Xr ASN1_STRING_set 3 . +.Pp +If the +.Fa type +argument does not have the bit +.Dv MBSTRING_FLAG +set and the +.Fa len argument +is \-1, +.Fa data +is expected to point to an object of the given +.Fa type +rather than to a buffer. +In this case, a deep copy of the existing object +into the new ASN.1 ANY object is performed with +.Xr ASN1_TYPE_set1 3 . +.Pp +If the +.Fa type +argument is 0, the +.Fa data +and +.Fa len +arguments are ignored and the set of values is left empty +instead of adding a single ASN.1 ANY object to it. +This violates section 8.2 of the X.501 standard, which requires +every attribute to contain at least one value, but some attribute +types used by the library use empty sets of values anyway. +.Pp +.Fn X509_ATTRIBUTE_create_by_OBJ +sets the type of +.Pf ** Fa attr +to +.Fa obj +using +.Fn X509_ATTRIBUTE_set1_object +and copies the +.Fa data +into it using +.Fn X509_ATTRIBUTE_set1_data . +If +.Fa attr +or +.Pf * Fa attr +is +.Dv NULL , +a new +.Vt X509_ATTRIBUTE +object is allocated, populated, and returned. +.Pp +.Fn X509_ATTRIBUTE_create_by_NID +is a wrapper around +.Fn X509_ATTRIBUTE_create_by_OBJ +that obtains the required +.Fa obj +argument by calling +.Xr OBJ_nid2obj 3 +on the +.Fa nid +argument. +.Pp +.Fn X509_ATTRIBUTE_create_by_txt +is a similar wrapper that obtains +.Fa obj +by calling +.Xr OBJ_txt2obj 3 +with the arguments +.Fa name +and 0, which means that long names, short names, and numerical OID +strings are all acceptable. +.Sh RETURN VALUES +.Fn X509_ATTRIBUTE_set1_object +returns 1 if successful or 0 if +.Fa attr +or +.Fa obj +is +.Dv NULL +or if memory allocation fails. +.Pp +.Fn X509_ATTRIBUTE_set1_data +returns 1 if successful or 0 if +.Fa attr +is +.Dv NULL +or if +.Xr ASN1_STRING_set_by_NID 3 , +.Xr ASN1_STRING_set 3 , +.Xr ASN1_TYPE_set1 3 , +or memory allocation fails. +.Pp +.Fn X509_ATTRIBUTE_create_by_OBJ , +.Fn X509_ATTRIBUTE_create_by_NID , +and +.Fn X509_ATTRIBUTE_create_by_txt +return a pointer to the changed or new object or +.Dv NULL +if obtaining +.Fa obj , +allocating mamory, or copying fails. +.Sh SEE ALSO +.Xr ASN1_OBJECT_new 3 , +.Xr ASN1_STRING_new 3 , +.Xr ASN1_STRING_set 3 , +.Xr ASN1_STRING_set_by_NID 3 , +.Xr ASN1_TYPE_new 3 , +.Xr OBJ_nid2obj 3 , +.Xr X509_ATTRIBUTE_get0_object 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 . +.Sh BUGS +If +.Fa attr +already contains one or more values, +.Fn X509_ATTRIBUTE_set1_data , +.Fn X509_ATTRIBUTE_create_by_OBJ , +.Fn X509_ATTRIBUTE_create_by_NID , +and +.Fn X509_ATTRIBUTE_create_by_txt +silently overwrite the pointers to the old values +and leak the memory used for them. -- 2.20.1