1.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.18 2024/09/02 07:57:27 tb Exp $ 2.\" 3.\" Copyright (c) 2016, 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: September 2 2024 $ 18.Dt X509_ATTRIBUTE_NEW 3 19.Os 20.Sh NAME 21.Nm X509_ATTRIBUTE_new , 22.Nm X509_ATTRIBUTE_create , 23.Nm X509_ATTRIBUTE_dup , 24.Nm X509_ATTRIBUTE_free 25.\" In the following line, "X.501" and "Attribute" are not typos. 26.\" The "Attribute" type is defined in X.501, not in X.509. 27.\" The type is called "Attribute" with capital "A", not "attribute". 28.Nd generic X.501 Attribute 29.Sh SYNOPSIS 30.In openssl/x509.h 31.Ft X509_ATTRIBUTE * 32.Fn X509_ATTRIBUTE_new void 33.Ft X509_ATTRIBUTE * 34.Fn X509_ATTRIBUTE_create "int nid" "int type" "void *value" 35.Ft X509_ATTRIBUTE * 36.Fn X509_ATTRIBUTE_dup "X509_ATTRIBUTE *attr" 37.Ft void 38.Fn X509_ATTRIBUTE_free "X509_ATTRIBUTE *attr" 39.Sh DESCRIPTION 40In the X.501 standard, an 41.Vt Attribute 42is the fundamental ASN.1 data type used to represent any kind of 43property of any kind of directory entry. 44In OpenSSL, very few objects use it directly, most notably the 45.Vt X509_REQ_INFO 46object used for PKCS#10 certification requests described in 47.Xr X509_REQ_new 3 , 48the 49.Vt PKCS8_PRIV_KEY_INFO 50object used for PKCS#8 private key information described in 51.Xr PKCS8_PRIV_KEY_INFO_new 3 , 52and the 53.Vt PKCS12_SAFEBAG 54container object described in 55.Xr PKCS12_SAFEBAG_new 3 . 56.Pp 57.Fn X509_ATTRIBUTE_new 58allocates and initializes an empty 59.Vt X509_ATTRIBUTE 60object. 61.Pp 62.Fn X509_ATTRIBUTE_create 63allocates a new multi-valued 64.Vt X509_ATTRIBUTE 65object of the type 66.Fa nid 67and initializes its set of values 68to contain one new ASN.1 ANY object with the given 69.Fa value 70and 71.Fa type . 72The 73.Fa type 74usually is one of the 75.Dv V_ASN1_* 76constants defined in 77.In openssl/asn1.h ; 78it is stored without validating it. 79If the function succeeds, ownership of the 80.Fa value 81is transferred to the new 82.Vt X509_ATTRIBUTE 83object. 84.Pp 85Be careful to not confuse the type of the attribute 86and the type of the value. 87.Pp 88.Fn X509_ATTRIBUTE_dup 89creates a deep copy of 90.Fa attr . 91.Pp 92.Fn X509_ATTRIBUTE_free 93frees 94.Fa attr . 95.Sh RETURN VALUES 96.Fn X509_ATTRIBUTE_new , 97.Fn X509_ATTRIBUTE_create , 98and 99.Fn X509_ATTRIBUTE_dup 100return the new 101.Vt X509_ATTRIBUTE 102object or 103.Dv NULL 104if an error occurs. 105.Pp 106In particular, these functions fail if memory allocation fails. 107.Fn X509_ATTRIBUTE_create 108also fails if 109.Xr OBJ_nid2obj 3 110fails on 111.Fa nid . 112.Sh SEE ALSO 113.Xr d2i_X509_ATTRIBUTE 3 , 114.Xr OBJ_nid2obj 3 , 115.Xr PKCS12_SAFEBAG_new 3 , 116.Xr PKCS7_add_attribute 3 , 117.Xr PKCS8_pkey_get0_attrs 3 , 118.Xr PKCS8_PRIV_KEY_INFO_new 3 , 119.Xr X509_ATTRIBUTE_get0_object 3 , 120.Xr X509_ATTRIBUTE_set1_object 3 , 121.Xr X509_EXTENSION_new 3 , 122.Xr X509_new 3 , 123.Xr X509_REQ_add1_attr 3 , 124.Xr X509_REQ_new 3 125.Sh STANDARDS 126.Bl -ohang 127.It Xo 128For the general definition of the 129.Vt Attribute 130data type: 131.Xc 132ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: 133Information Technology \(en Open Systems Interconnection \(en 134The Directory: Models, section 8.2: Overall structure 135.It For the specific definition in the context of certification requests: 136RFC 2986: PKCS #10: Certification Request Syntax Specification, 137section 4.1: CertificationRequestInfo 138.It For the specific use in the context of private key information: 139RFC 5208: Public-Key Cryptography Standards (PKCS) #8: 140Private-Key Information Syntax Specification 141.It For the specific definition in the context of PFX: 142RFC 7292: PKCS #12: Personal Information Exchange Syntax, 143section 4.2: The SafeBag Type 144.El 145.Sh HISTORY 146.Fn X509_ATTRIBUTE_new 147and 148.Fn X509_ATTRIBUTE_free 149first appeared in SSLeay 0.5.1 and have been available since 150.Ox 2.4 . 151.Pp 152.Fn X509_ATTRIBUTE_create 153and 154.Fn X509_ATTRIBUTE_dup 155first appeared in SSLeay 0.9.1 and have been available since 156.Ox 2.6 . 157.Sh BUGS 158A data type designed to hold arbitrary data is an oxymoron. 159.Pp 160While it may occasionally be useful for abstract syntax specification 161or for generic container objects, using it for the representation 162of specific data in a specific data structure feels like dubious 163design. 164.Pp 165Having two distinct data types to hold arbitrary data \(en 166in this case, 167.Vt X509_ATTRIBUTE 168on the X.501 language level and 169.Vt X509_EXTENSION 170as described in 171.Xr X509_EXTENSION_new 3 172on the X.509 language level \(en feels even more questionable, 173in particular considering that Attributes in certification requests 174can be used to ask for Extensions in certificates. 175.Pp 176At the very least, the direct use of the low-level generic 177.Vt X509_ATTRIBUTE 178type in specific data types like certification requests or private 179key information looks like a layering violation and appears to put 180type safety into jeopardy. 181