1.\" $OpenBSD: ACCESS_DESCRIPTION_new.3,v 1.5 2019/06/06 01:06:58 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 ACCESS_DESCRIPTION_NEW 3 19.Os 20.Sh NAME 21.Nm ACCESS_DESCRIPTION_new , 22.Nm ACCESS_DESCRIPTION_free , 23.Nm AUTHORITY_INFO_ACCESS_new , 24.Nm AUTHORITY_INFO_ACCESS_free 25.Nd X.509 information access extensions 26.Sh SYNOPSIS 27.In openssl/x509v3.h 28.Ft ACCESS_DESCRIPTION * 29.Fn ACCESS_DESCRIPTION_new void 30.Ft void 31.Fn ACCESS_DESCRIPTION_free "ACCESS_DESCRIPTION *ad" 32.Ft AUTHORITY_INFO_ACCESS 33.Fn AUTHORITY_INFO_ACCESS_new void 34.Ft void 35.Fn AUTHORITY_INFO_ACCESS_free "AUTHORITY_INFO_ACCESS *aia" 36.Sh DESCRIPTION 37Using the information access extensions, certificates and certificate 38revocation lists can point to auxiliary information and services 39available online, for example online validation services or CA 40policy data. 41.Pp 42.Fn ACCESS_DESCRIPTION_new 43allocates and initializes an empty 44.Vt ACCESS_DESCRIPTION 45object, representing an ASN.1 46.Vt AccessDescription 47structure defined in RFC 5280 section 4.2.2.1. 48It can hold a pointer to a 49.Vt GENERAL_NAME 50object documented in 51.Xr GENERAL_NAME_new 3 52and an access method identifier. 53.Fn ACCESS_DESCRIPTION_free 54frees 55.Fa ad . 56.Pp 57The access method identifier is somewhat misnamed; it identifies 58the type and format of the information provided. 59How to access that information is often obvious from the 60.Vt GENERAL_NAME 61which may for example include a uniform resource identifier. 62.Pp 63Four standard access method identifiers are defined in RFC 5280: 64.Bl -bullet 65.It 66.Qq id-ad-caIssuers 67can occur in the authority information access extension of certificates 68and certificate revocation lists and provides access to certificates 69issued to the CA that issued the certificate, or provides access 70to certificates used for signing the CRL, in order to help constructing 71a certification path. 72.It 73.Qq id-ad-ocsp 74can occur in the authority information access extension of certificates 75and provides access to revocation information via the Online 76Certificate Status Protocol (OCSP) defined in RFC 6960. 77.It 78.Qq id-ad-caRepository 79can occur in the subject information access extension of CA 80certificates and provides access to an online repository of 81certificates issued by the CA. 82.It 83.Qq id-ad-timeStamping 84can occur in the subject information access extension of end entity 85certificates and indicates that the subject offers timestamping 86services using the Time Stamp Protocol defined in RFC 3161. 87.El 88.Pp 89.Fn AUTHORITY_INFO_ACCESS_new 90allocates and initializes an empty 91.Vt AUTHORITY_INFO_ACCESS 92object, which is a 93.Vt STACK_OF(ACCESS_DESCRIPTION) 94and represents an ASN.1 95.Vt AuthorityInfoAccessSyntax 96structure defined in RFC 5280 section 4.2.2.1. 97If can be used for the authority information access extension of 98certificates and certificate revocation lists and for the subject 99information access extension of certificates. 100.Fn AUTHORITY_INFO_ACCESS_free 101frees 102.Fa aia . 103.Sh RETURN VALUES 104.Fn ACCESS_DESCRIPTION_new 105and 106.Fn AUTHORITY_INFO_ACCESS_new 107return the new 108.Vt ACCESS_DESCRIPTION 109or 110.Vt AUTHORITY_INFO_ACCESS 111object, respectively, or 112.Dv NULL 113if an error occurs. 114.Sh SEE ALSO 115.Xr d2i_ACCESS_DESCRIPTION 3 , 116.Xr DIST_POINT_new 3 , 117.Xr GENERAL_NAME_new 3 , 118.Xr OCSP_REQUEST_new 3 , 119.Xr TS_REQ_new 3 , 120.Xr X509_CRL_new 3 , 121.Xr X509_EXTENSION_new 3 , 122.Xr X509_new 3 123.Sh STANDARDS 124These extensions are only defined in the following RFC and not 125specified in the underlying X.509 standard. 126.Pp 127RFC 5280: Internet X.509 Public Key Infrastructure Certificate and 128Certificate Revocation List (CRL) Profile: 129.Bl -dash -compact 130.It 131section 4.2.2.1: Certificate Extensions: Authority Information Access 132.It 133section 4.2.2.2: Certificate Extensions: Subject Information Access 134.It 135section 5.2.7: CRL Extensions: Authority Information Access 136.El 137.Pp 138Regarding OCSP and TSP, see: 139.Pp 140RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate 141Status Protocol 142.Pp 143RFC 3161: Internet X.509 Public Key Infrastructure Time-Stamp Protocol 144.Sh HISTORY 145.Fn ACCESS_DESCRIPTION_new , 146.Fn ACCESS_DESCRIPTION_free , 147.Fn AUTHORITY_INFO_ACCESS_new , 148and 149.Fn AUTHORITY_INFO_ACCESS_free 150first appeared in OpenSSL 0.9.5 and have been available since 151.Ox 2.7 . 152