lib/libcrypto/man/X509_OBJECT_get0_X509.3

   1 .\" $OpenBSD: X509_OBJECT_get0_X509.3,v 1.8 2018/08/24 19:23:07 tb Exp $
   2 .\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software for any
   5 .\" purpose with or without fee is hereby granted, provided that the above
   6 .\" copyright notice and this permission notice appear in all copies.
   7 .\"
   8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15 .\"
  16 .Dd $Mdocdate: August 24 2018 $
  17 .Dt X509_OBJECT_GET0_X509 3
  18 .Os
  19 .Sh NAME
  20 .Nm X509_OBJECT_get_type ,
  21 .Nm X509_OBJECT_up_ref_count ,
  22 .Nm X509_OBJECT_free_contents ,
  23 .Nm X509_OBJECT_get0_X509 ,
  24 .Nm X509_OBJECT_get0_X509_CRL ,
  25 .Nm X509_OBJECT_idx_by_subject ,
  26 .Nm X509_OBJECT_retrieve_by_subject ,
  27 .Nm X509_OBJECT_retrieve_match
  28 .Nd certificate, CRL, private key, and string wrapper for certificate stores
  29 .Sh SYNOPSIS
  30 .In openssl/x509_vfy.h
  31 .Ft int
  32 .Fo X509_OBJECT_get_type
  33 .Fa "const X509_OBJECT *obj"
  34 .Fc
  35 .Ft int
  36 .Fo X509_OBJECT_up_ref_count
  37 .Fa "X509_OBJECT *obj"
  38 .Fc
  39 .Ft void
  40 .Fo X509_OBJECT_free_contents
  41 .Fa "X509_OBJECT *obj"
  42 .Fc
  43 .Ft X509 *
  44 .Fo X509_OBJECT_get0_X509
  45 .Fa "const X509_OBJECT *obj"
  46 .Fc
  47 .Ft X509_CRL *
  48 .Fo X509_OBJECT_get0_X509_CRL
  49 .Fa "X509_OBJECT *obj"
  50 .Fc
  51 .Ft int
  52 .Fo X509_OBJECT_idx_by_subject
  53 .Fa "STACK_OF(X509_OBJECT) *stack"
  54 .Fa "int type"
  55 .Fa "X509_NAME *name"
  56 .Fc
  57 .Ft X509_OBJECT *
  58 .Fo X509_OBJECT_retrieve_by_subject
  59 .Fa "STACK_OF(X509_OBJECT) *stack"
  60 .Fa "int type"
  61 .Fa "X509_NAME *name"
  62 .Fc
  63 .Ft X509_OBJECT *
  64 .Fo X509_OBJECT_retrieve_match
  65 .Fa "STACK_OF(X509_OBJECT) *stack"
  66 .Fa "X509_OBJECT *obj"
  67 .Fc
  68 .Sh DESCRIPTION
  69 The
  70 .Vt X509_OBJECT
  71 structure is a shallow wrapper around one
  72 .Vt X509
  73 certificate object, one
  74 .Vt X509_CRL
  75 certificate revocation list object, one
  76 .Vt EVP_PKEY
  77 private key object, or one
  78 .Vt char *
  79 string.
  80 The type of object stored at any given time can be inspected with
  81 .Fn X509_OBJECT_get_type .
  82 .Pp
  83 Each
  84 .Vt X509_STORE
  85 object uses one stack of
  86 .Vt X509_OBJECT
  87 structures as its main storage area.
  88 .Pp
  89 If
  90 .Fa obj
  91 contains an
  92 .Vt X509
  93 certificate or an
  94 .Vt X509_CRL
  95 certificate revocation list,
  96 .Fn X509_OBJECT_up_ref_count
  97 increments the reference count of that inner object by 1.
  98 Otherwise, no action occurs.
  99 .Pp
 100 If
 101 .Fa obj
 102 contains an
 103 .Vt X509
 104 certificate,
 105 .Fn X509_OBJECT_free_contents
 106 calls
 107 .Xr X509_free 3
 108 on that inner object.
 109 If
 110 .Fa obj
 111 contains an
 112 .Vt X509_CRL
 113 certificate revocation list, it calls
 114 .Xr X509_CRL_free 3
 115 on that inner list.
 116 Otherwise, no action occurs.
 117 .Fn X509_OBJECT_free_contents
 118 does not free
 119 .Fa obj
 120 itself.
 121 .Pp
 122 If
 123 .Fa type
 124 is
 125 .Dv X509_LU_X509 ,
 126 .Fn X509_OBJECT_idx_by_subject
 127 and
 128 .Fn X509_OBJECT_retrieve_by_subject
 129 search the given
 130 .Fa stack
 131 for a certificate with the subject
 132 .Fa name .
 133 If
 134 .Fa type
 135 is
 136 .Dv X509_LU_CRL ,
 137 they search for a certificate revocation list with the issuer
 138 .Fa name
 139 instead.
 140 .Pp
 141 If
 142 .Fa obj
 143 contains a certificate,
 144 .Fn X509_OBJECT_retrieve_match
 145 searches the given
 146 .Fa stack
 147 for a certificate with a matching subject name;
 148 if it contains a certificate revocation list, it searches for a
 149 certificate revocation list with a matching issuer name instead;
 150 otherwise, it searches for an
 151 .Vt X509_OBJECT
 152 with a matching type.
 153 .Sh RETURN VALUES
 154 .Fn X509_OBJECT_get_type
 155 returns
 156 .Dv X509_LU_X509
 157 if
 158 .Fa obj
 159 contains a certificate,
 160 .Dv X509_LU_CRL
 161 if it contains a certificate revocation list,
 162 or 0 if an error occurs.
 163 .Pp
 164 .Fn X509_OBJECT_up_ref_count
 165 returns 1 on success and 0 on failure.
 166 .Pp
 167 .Fn X509_OBJECT_get0_X509
 168 returns an internal pointer to the certificate contained in
 169 .Fa obj
 170 or
 171 .Dv NULL
 172 if
 173 .Fa obj
 174 is
 175 .Dv NULL
 176 or contains no certificate.
 177 .Pp
 178 .Fn X509_OBJECT_get0_X509_CRL
 179 returns an internal pointer to the certificate revocation list contained in
 180 .Fa obj
 181 or
 182 .Dv NULL
 183 if
 184 .Fa obj
 185 is
 186 .Dv NULL
 187 or contains no certificate revocation list.
 188 .Pp
 189 .Fn X509_OBJECT_idx_by_subject
 190 returns the zero-based index of the first matching certificate
 191 or revocation list in the
 192 .Fa stack
 193 or \-1 if
 194 .Fa type
 195 is neither
 196 .Dv X509_LU_X509
 197 nor
 198 .Dv X509_LU_CRL
 199 or if no match is found.
 200 .Pp
 201 .Fn X509_OBJECT_retrieve_by_subject
 202 returns the first matching certificate or revocation list in the
 203 .Fa stack
 204 or
 205 .Dv NULL
 206 if
 207 .Fa type
 208 is neither
 209 .Dv X509_LU_X509
 210 nor
 211 .Dv X509_LU_CRL
 212 or if no match is found.
 213 .Pp
 214 .Fn X509_OBJECT_retrieve_match
 215 returns the first mathching
 216 .Vt X509_OBJECT
 217 or
 218 .Dv NULL
 219 if
 220 .Fa stack
 221 or
 222 .Fa obj
 223 is
 224 .Dv NULL
 225 or no match is found.
 226 .Sh SEE ALSO
 227 .Xr X509_STORE_get0_objects 3 ,
 228 .Xr X509_STORE_load_locations 3 ,
 229 .Xr X509_STORE_new 3
 230 .\" The type X509_OBJECT is also used
 231 .\" by the following undocumented public functions:
 232 .\" X509_STORE_get_by_subject
 233 .\" X509_LOOKUP_by_subject
 234 .\" X509_LOOKUP_by_issuer_serial
 235 .\" X509_LOOKUP_by_fingerprint
 236 .\" X509_LOOKUP_by_alias
 237 .Sh HISTORY
 238 .Fn X509_OBJECT_up_ref_count
 239 and
 240 .Fn X509_OBJECT_free_contents
 241 first appeared in SSLeay 0.8.0 and have been available since
 242 .Ox 2.4 .
 243 .Pp
 244 .Fn X509_OBJECT_idx_by_subject ,
 245 .Fn X509_OBJECT_retrieve_by_subject ,
 246 and
 247 .Fn X509_OBJECT_retrieve_match
 248 first appeared in OpenSSL 0.9.6 and have been available since
 249 .Ox 2.9 .
 250 .Pp
 251 .Fn X509_OBJECT_get_type ,
 252 .Fn X509_OBJECT_get0_X509 ,
 253 and
 254 .Fn X509_OBJECT_get0_X509_CRL
 255 first appeared in OpenSSL 1.1.0 and have been available since
 256 .Ox 6.3 .