1.\" $OpenBSD: X509_ATTRIBUTE_set1_object.3,v 1.3 2021/11/26 13:48:21 jsg Exp $ 2.\" 3.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: November 26 2021 $ 18.Dt X509_ATTRIBUTE_SET1_OBJECT 3 19.Os 20.Sh NAME 21.Nm X509_ATTRIBUTE_set1_object , 22.Nm X509_ATTRIBUTE_set1_data , 23.Nm X509_ATTRIBUTE_create_by_OBJ , 24.Nm X509_ATTRIBUTE_create_by_NID , 25.Nm X509_ATTRIBUTE_create_by_txt 26.\" In the following line, "X.501" and "Attribute" are not typos. 27.\" The "Attribute" type is defined in X.501, not in X.509. 28.\" The type is called "Attribute" with capital "A", not "attribute". 29.Nd modify an X.501 Attribute 30.Sh SYNOPSIS 31.In openssl/x509.h 32.Ft int 33.Fo X509_ATTRIBUTE_set1_object 34.Fa "X509_ATTRIBUTE *attr" 35.Fa "const ASN1_OBJECT *obj" 36.Fc 37.Ft int 38.Fo X509_ATTRIBUTE_set1_data 39.Fa "X509_ATTRIBUTE *attr" 40.Fa "int type" 41.Fa "const void *data" 42.Fa "int len" 43.Fc 44.Ft X509_ATTRIBUTE * 45.Fo X509_ATTRIBUTE_create_by_OBJ 46.Fa "X509_ATTRIBUTE **pattr" 47.Fa "const ASN1_OBJECT *obj" 48.Fa "int type" 49.Fa "const void *data" 50.Fa "int len" 51.Fc 52.Ft X509_ATTRIBUTE * 53.Fo X509_ATTRIBUTE_create_by_NID 54.Fa "X509_ATTRIBUTE **pattr" 55.Fa "int nid" 56.Fa "int type" 57.Fa "const void *data" 58.Fa "int len" 59.Fc 60.Ft X509_ATTRIBUTE * 61.Fo X509_ATTRIBUTE_create_by_txt 62.Fa "X509_ATTRIBUTE **pattr" 63.Fa "const char *name" 64.Fa "int type" 65.Fa "const unsigned char *data" 66.Fa "int len" 67.Fc 68.Sh DESCRIPTION 69.Fn X509_ATTRIBUTE_set1_object 70sets the type of 71.Fa attr 72to 73.Fa obj . 74If 75.Fa obj 76is dynamically allocated, a deep copy is created. 77If the type of 78.Fa attr 79was already set, the old type is freed 80as far as it was dynamically allocated. 81After calling this function, 82.Fa attr 83may be in an inconsistent state 84because its values may not agree with the new attribute type. 85.Pp 86.Fn X509_ATTRIBUTE_set1_data 87sets 88.Fa attr 89to be multi-valued and initializes its set of values 90to contain a single new ASN.1 ANY object representing the 91.Fa data . 92.Pp 93The interpretation of the 94.Fa data 95depends on the values of the 96.Fa type 97and 98.Fa len 99arguments; there are four different cases. 100.Pp 101If the 102.Fa type 103argument has the bit 104.Dv MBSTRING_FLAG 105set, 106.Fa data 107is expected to point to a multibyte character string that is 108.Fa len 109bytes long and uses the encoding specified by the 110.Fa type 111argument, and it is expected that an attribute type was already assigned to 112.Fa attr , 113for example by calling 114.Fn X509_ATTRIBUTE_set1_object 115before calling 116.Fn X509_ATTRIBUTE_set1_data . 117In this case, an appropriate ASN.1 multibyte string type is chosen and 118a new object of that type is allocated and populated to represent the 119.Fa data 120by calling 121.Xr ASN1_STRING_set_by_NID 3 . 122The type of that new ASN.1 string object is subsequently used instead of the 123.Fa type 124argument. 125.Pp 126If the 127.Fa type 128argument does not have the bit 129.Dv MBSTRING_FLAG 130set and the 131.Fa len argument 132is not \-1, the 133.Fa type 134argument is expected to be one of the types documented in 135.Xr ASN1_STRING_new 3 136and 137.Fa data 138is expected to point to a buffer of 139.Fa len 140bytes. 141In this case, a new object is allocated with 142.Xr ASN1_STRING_type_new 3 143and populated with 144.Xr ASN1_STRING_set 3 . 145.Pp 146If the 147.Fa type 148argument does not have the bit 149.Dv MBSTRING_FLAG 150set and the 151.Fa len argument 152is \-1, 153.Fa data 154is expected to point to an object of the given 155.Fa type 156rather than to a buffer. 157In this case, a deep copy of the existing object 158into the new ASN.1 ANY object is performed with 159.Xr ASN1_TYPE_set1 3 . 160.Pp 161If the 162.Fa type 163argument is 0, the 164.Fa data 165and 166.Fa len 167arguments are ignored and the set of values is left empty 168instead of adding a single ASN.1 ANY object to it. 169This violates section 8.2 of the X.501 standard, which requires 170every attribute to contain at least one value, but some attribute 171types used by the library use empty sets of values anyway. 172.Pp 173.Fn X509_ATTRIBUTE_create_by_OBJ 174sets the type of 175.Pf ** Fa attr 176to 177.Fa obj 178using 179.Fn X509_ATTRIBUTE_set1_object 180and copies the 181.Fa data 182into it using 183.Fn X509_ATTRIBUTE_set1_data . 184If 185.Fa attr 186or 187.Pf * Fa attr 188is 189.Dv NULL , 190a new 191.Vt X509_ATTRIBUTE 192object is allocated, populated, and returned. 193.Pp 194.Fn X509_ATTRIBUTE_create_by_NID 195is a wrapper around 196.Fn X509_ATTRIBUTE_create_by_OBJ 197that obtains the required 198.Fa obj 199argument by calling 200.Xr OBJ_nid2obj 3 201on the 202.Fa nid 203argument. 204.Pp 205.Fn X509_ATTRIBUTE_create_by_txt 206is a similar wrapper that obtains 207.Fa obj 208by calling 209.Xr OBJ_txt2obj 3 210with the arguments 211.Fa name 212and 0, which means that long names, short names, and numerical OID 213strings are all acceptable. 214.Sh RETURN VALUES 215.Fn X509_ATTRIBUTE_set1_object 216returns 1 if successful or 0 if 217.Fa attr 218or 219.Fa obj 220is 221.Dv NULL 222or if memory allocation fails. 223.Pp 224.Fn X509_ATTRIBUTE_set1_data 225returns 1 if successful or 0 if 226.Fa attr 227is 228.Dv NULL 229or if 230.Xr ASN1_STRING_set_by_NID 3 , 231.Xr ASN1_STRING_set 3 , 232.Xr ASN1_TYPE_set1 3 , 233or memory allocation fails. 234.Pp 235.Fn X509_ATTRIBUTE_create_by_OBJ , 236.Fn X509_ATTRIBUTE_create_by_NID , 237and 238.Fn X509_ATTRIBUTE_create_by_txt 239return a pointer to the changed or new object or 240.Dv NULL 241if obtaining 242.Fa obj , 243allocating memory, or copying fails. 244.Sh SEE ALSO 245.Xr ASN1_OBJECT_new 3 , 246.Xr ASN1_STRING_new 3 , 247.Xr ASN1_STRING_set 3 , 248.Xr ASN1_STRING_set_by_NID 3 , 249.Xr ASN1_TYPE_new 3 , 250.Xr OBJ_nid2obj 3 , 251.Xr X509_ATTRIBUTE_get0_object 3 , 252.Xr X509_ATTRIBUTE_new 3 253.Sh HISTORY 254These functions first appeared in OpenSSL 0.9.5 255and have been available since 256.Ox 2.7 . 257.Sh BUGS 258If 259.Fa attr 260already contains one or more values, 261.Fn X509_ATTRIBUTE_set1_data , 262.Fn X509_ATTRIBUTE_create_by_OBJ , 263.Fn X509_ATTRIBUTE_create_by_NID , 264and 265.Fn X509_ATTRIBUTE_create_by_txt 266silently overwrite the pointers to the old values 267and leak the memory used for them. 268