1.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.8 2020/06/04 10:24:27 schwarze Exp $ 2.\" 3.\" Copyright (c) 2016 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: June 4 2020 $ 18.Dt X509_ATTRIBUTE_NEW 3 19.Os 20.Sh NAME 21.Nm X509_ATTRIBUTE_new , 22.Nm X509_ATTRIBUTE_free 23.\" In the following line, "X.501" and "Attribute" are not typos. 24.\" The "Attribute" type is defined in X.501, not in X.509. 25.\" The type in called "Attribute" with capital "A", not "attribute". 26.Nd generic X.501 Attribute 27.Sh SYNOPSIS 28.In openssl/x509.h 29.Ft X509_ATTRIBUTE * 30.Fn X509_ATTRIBUTE_new void 31.Ft void 32.Fn X509_ATTRIBUTE_free "X509_ATTRIBUTE *attr" 33.Sh DESCRIPTION 34In the X.501 standard, an 35.Vt Attribute 36is the fundamental ASN.1 data type used to represent any kind of 37property of any kind of directory entry. 38In OpenSSL, very few objects use it directly, most notably the 39.Vt X509_REQ_INFO 40object used for PKCS#10 certification requests described in 41.Xr X509_REQ_new 3 , 42the 43.Vt PKCS8_PRIV_KEY_INFO 44object used for PKCS#8 private key information described in 45.Xr PKCS8_PRIV_KEY_INFO_new 3 , 46and the 47.Vt PKCS12_SAFEBAG 48container object described in 49.Xr PKCS12_SAFEBAG_new 3 . 50.Pp 51.Fn X509_ATTRIBUTE_new 52allocates and initializes an empty 53.Vt X509_ATTRIBUTE 54object. 55.Fn X509_ATTRIBUTE_free 56frees 57.Fa attr . 58.Sh RETURN VALUES 59.Fn X509_ATTRIBUTE_new 60returns the new 61.Vt X509_ATTRIBUTE 62object or 63.Dv NULL 64if an error occurs. 65.Sh SEE ALSO 66.Xr d2i_X509_ATTRIBUTE 3 , 67.Xr PKCS12_SAFEBAG_new 3 , 68.Xr PKCS7_add_attribute 3 , 69.Xr PKCS8_PRIV_KEY_INFO_new 3 , 70.Xr X509_EXTENSION_new 3 , 71.Xr X509_new 3 , 72.Xr X509_REQ_new 3 73.Sh STANDARDS 74.Bl -ohang 75.It Xo 76For the general definition of the 77.Vt Attribute 78data type: 79.Xc 80ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: 81Information Technology \(en Open Systems Interconnection \(en 82The Directory: Models, section 8.2: Overall structure 83.It For the specific definition in the context of certification requests: 84RFC 2986: PKCS #10: Certification Request Syntax Specification, 85section 4.1: CertificationRequestInfo 86.It For the specific use in the context of private key information: 87RFC 5208: Public-Key Cryptography Standards (PKCS) #8: 88Private-Key Information Syntax Specification 89.It For the specific definition in the context of PFX: 90RFC 7292: PKCS #12: Personal Information Exchange Syntax, 91section 4.2: The SafeBag Type 92.El 93.Sh HISTORY 94.Fn X509_ATTRIBUTE_new 95and 96.Fn X509_ATTRIBUTE_free 97first appeared in SSLeay 0.5.1 and have been available since 98.Ox 2.4 . 99.Sh BUGS 100A data type designed to hold arbitrary data is an oxymoron. 101.Pp 102While it may occasionally be useful for abstract syntax specification 103or for generic container objects, using it for the representation 104of specific data in a specific data structure feels like dubious 105design. 106.Pp 107Having two distinct data types to hold arbitrary data \(en 108in this case, 109.Vt X509_ATTRIBUTE 110on the X.501 language level and 111.Vt X509_EXTENSION 112as described in 113.Xr X509_EXTENSION_new 3 114on the X.509 language level \(en feels even more questionable, 115in particular considering that Attributes in certification requests 116can be used to ask for Extensions in certificates. 117.Pp 118At the very least, the direct use of the low-level generic 119.Vt X509_ATTRIBUTE 120type in specific data types like certification requests or private 121key information looks like a layering violation and appears to put 122type safety into jeopardy. 123