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