1.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.16 2021/10/26 12:56:48 schwarze 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: October 26 2021 $ 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 EVP_PKEY_add1_attr 3 , 115.Xr OBJ_nid2obj 3 , 116.Xr PKCS12_SAFEBAG_new 3 , 117.Xr PKCS7_add_attribute 3 , 118.Xr PKCS8_pkey_get0_attrs 3 , 119.Xr PKCS8_PRIV_KEY_INFO_new 3 , 120.Xr X509_ATTRIBUTE_get0_object 3 , 121.Xr X509_ATTRIBUTE_set1_object 3 , 122.Xr X509_EXTENSION_new 3 , 123.Xr X509_new 3 , 124.Xr X509_REQ_add1_attr 3 , 125.Xr X509_REQ_new 3 , 126.Xr X509at_add1_attr 3 , 127.Xr X509at_get_attr 3 128.Sh STANDARDS 129.Bl -ohang 130.It Xo 131For the general definition of the 132.Vt Attribute 133data type: 134.Xc 135ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: 136Information Technology \(en Open Systems Interconnection \(en 137The Directory: Models, section 8.2: Overall structure 138.It For the specific definition in the context of certification requests: 139RFC 2986: PKCS #10: Certification Request Syntax Specification, 140section 4.1: CertificationRequestInfo 141.It For the specific use in the context of private key information: 142RFC 5208: Public-Key Cryptography Standards (PKCS) #8: 143Private-Key Information Syntax Specification 144.It For the specific definition in the context of PFX: 145RFC 7292: PKCS #12: Personal Information Exchange Syntax, 146section 4.2: The SafeBag Type 147.El 148.Sh HISTORY 149.Fn X509_ATTRIBUTE_new 150and 151.Fn X509_ATTRIBUTE_free 152first appeared in SSLeay 0.5.1 and have been available since 153.Ox 2.4 . 154.Pp 155.Fn X509_ATTRIBUTE_create 156and 157.Fn X509_ATTRIBUTE_dup 158first appeared in SSLeay 0.9.1 and have been available since 159.Ox 2.6 . 160.Sh BUGS 161A data type designed to hold arbitrary data is an oxymoron. 162.Pp 163While it may occasionally be useful for abstract syntax specification 164or for generic container objects, using it for the representation 165of specific data in a specific data structure feels like dubious 166design. 167.Pp 168Having two distinct data types to hold arbitrary data \(en 169in this case, 170.Vt X509_ATTRIBUTE 171on the X.501 language level and 172.Vt X509_EXTENSION 173as described in 174.Xr X509_EXTENSION_new 3 175on the X.509 language level \(en feels even more questionable, 176in particular considering that Attributes in certification requests 177can be used to ask for Extensions in certificates. 178.Pp 179At the very least, the direct use of the low-level generic 180.Vt X509_ATTRIBUTE 181type in specific data types like certification requests or private 182key information looks like a layering violation and appears to put 183type safety into jeopardy. 184