lib/libcrypto/man/OCSP_SERVICELOC_new.3

   1 .\"     $OpenBSD: OCSP_SERVICELOC_new.3,v 1.5 2016/12/25 22:15:10 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: December 25 2016 $
  18 .Dt OCSP_SERVICELOC_NEW 3
  19 .Os
  20 .Sh NAME
  21 .Nm OCSP_SERVICELOC_new ,
  22 .Nm OCSP_SERVICELOC_free ,
  23 .Nm OCSP_url_svcloc_new
  24 .Nd OCSP service locator extension
  25 .Sh SYNOPSIS
  26 .In openssl/ocsp.h
  27 .Ft OCSP_SERVICELOC *
  28 .Fn OCSP_SERVICELOC_new void
  29 .Ft void
  30 .Fn OCSP_SERVICELOC_free "OCSP_SERVICELOC *sloc"
  31 .Ft X509_EXTENSION *
  32 .Fo OCSP_url_svcloc_new
  33 .Fa "X509_NAME *issuer"
  34 .Fa "char **urls"
  35 .Fc
  36 .Sh DESCRIPTION
  37 Due to restrictions of network routing, a client may be unable to
  38 directly contact the authoritative OCSP server for a certificate
  39 that needs to be checked.
  40 In that case, the request can be sent via a proxy server.
  41 An ASN.1
  42 .Vt ServiceLocator
  43 structure is included in the singleRequestExtensions field of the
  44 .Vt Request
  45 structure to indicate where to forward the request.
  46 The
  47 .Vt ServiceLocator
  48 is represented by a
  49 .Vt OCSP_SERVICELOC
  50 object, which will be stored inside the
  51 .Vt OCSP_ONEREQ
  52 object documented in
  53 .Xr OCSP_ONEREQ_new 3 .
  54 .Pp
  55 .Fn OCSP_SERVICELOC_new
  56 allocates and initializes an empty
  57 .Vt OCSP_SERVICELOC
  58 object.
  59 .Fn OCSP_SERVICELOC_free
  60 frees
  61 .Fa sloc .
  62 .Pp
  63 .Fn OCSP_url_svcloc_new
  64 requires an
  65 .Fa issuer
  66 name and optionally accepts an array of
  67 .Fa urls .
  68 If
  69 .Fa urls
  70 or its first element is
  71 .Dv NULL ,
  72 the locator field is omitted from the
  73 .Vt ServiceLocator
  74 structure and only the issuer is included.
  75 The resulting
  76 .Vt ServiceLocator
  77 structure is encoded in ASN.1 using
  78 .Xr X509V3_EXT_i2d 3
  79 with criticality 0.
  80 .Sh RETURN VALUES
  81 .Fn OCSP_SERVICELOC_new
  82 returns a new
  83 .Vt OCSP_SERVICELOC
  84 object or
  85 .Dv NULL
  86 if an error occurred.
  87 .Pp
  88 .Fn OCSP_url_svcloc_new
  89 returns a new
  90 .Vt X509_EXTENSION
  91 object or
  92 .Dv NULL
  93 if an error occurred.
  94 .Sh SEE ALSO
  95 .Xr OCSP_REQUEST_new 3 ,
  96 .Xr X509_EXTENSION_new 3 ,
  97 .Xr X509_get_issuer_name 3 ,
  98 .Xr X509_NAME_new 3
  99 .Sh STANDARDS
 100 RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate
 101 Status Protocol, section 4.4.6: Service Locator