lib/libcrypto/man/ACCESS_DESCRIPTION_new.3

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