1.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.7 2019/06/06 01:06:59 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 6 2019 $ 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 PKCS8_PRIV_KEY_INFO_new 3 , 69.Xr X509_EXTENSION_new 3 , 70.Xr X509_new 3 , 71.Xr X509_REQ_new 3 72.Sh STANDARDS 73.Bl -ohang 74.It Xo 75For the general definition of the 76.Vt Attribute 77data type: 78.Xc 79ITU-T Recommendation X.501, also known as ISO/IEC 9594-2: 80Information Technology \(en Open Systems Interconnection \(en 81The Directory: Models, section 8.2: Overall structure 82.It For the specific definition in the context of certification requests: 83RFC 2986: PKCS #10: Certification Request Syntax Specification, 84section 4.1: CertificationRequestInfo 85.It For the specific use in the context of private key information: 86RFC 5208: Public-Key Cryptography Standards (PKCS) #8: 87Private-Key Information Syntax Specification 88.It For the specific definition in the context of PFX: 89RFC 7292: PKCS #12: Personal Information Exchange Syntax, 90section 4.2: The SafeBag Type 91.El 92.Sh HISTORY 93.Fn X509_ATTRIBUTE_new 94and 95.Fn X509_ATTRIBUTE_free 96first appeared in SSLeay 0.5.1 and have been available since 97.Ox 2.4 . 98.Sh BUGS 99A data type designed to hold arbitrary data is an oxymoron. 100.Pp 101While it may occasionally be useful for abstract syntax specification 102or for generic container objects, using it for the representation 103of specific data in a specific data structure feels like dubious 104design. 105.Pp 106Having two distinct data types to hold arbitrary data \(en 107in this case, 108.Vt X509_ATTRIBUTE 109on the X.501 language level and 110.Vt X509_EXTENSION 111as described in 112.Xr X509_EXTENSION_new 3 113on the X.509 language level \(en feels even more questionable, 114in particular considering that Attributes in certification requests 115can be used to ask for Extensions in certificates. 116.Pp 117At the very least, the direct use of the low-level generic 118.Vt X509_ATTRIBUTE 119type in specific data types like certification requests or private 120key information looks like a layering violation and appears to put 121type safety into jeopardy. 122