lib/libcrypto/man/OCSP_sendreq_new.3

   1 .\"     $OpenBSD: OCSP_sendreq_new.3,v 1.4 2017/07/06 15:42:04 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
   5 .\" Copyright (c) 2014, 2016 The OpenSSL Project.  All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in
  16 .\"    the documentation and/or other materials provided with the
  17 .\"    distribution.
  18 .\"
  19 .\" 3. All advertising materials mentioning features or use of this
  20 .\"    software must display the following acknowledgment:
  21 .\"    "This product includes software developed by the OpenSSL Project
  22 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  23 .\"
  24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  25 .\"    endorse or promote products derived from this software without
  26 .\"    prior written permission. For written permission, please contact
  27 .\"    openssl-core@openssl.org.
  28 .\"
  29 .\" 5. Products derived from this software may not be called "OpenSSL"
  30 .\"    nor may "OpenSSL" appear in their names without prior written
  31 .\"    permission of the OpenSSL Project.
  32 .\"
  33 .\" 6. Redistributions of any form whatsoever must retain the following
  34 .\"    acknowledgment:
  35 .\"    "This product includes software developed by the OpenSSL Project
  36 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  37 .\"
  38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  41 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  50 .\"
  51 .Dd $Mdocdate: July 6 2017 $
  52 .Dt OCSP_SENDREQ_NEW 3
  53 .Os
  54 .Sh NAME
  55 .Nm OCSP_sendreq_new ,
  56 .Nm OCSP_sendreq_nbio ,
  57 .Nm OCSP_REQ_CTX_free ,
  58 .Nm OCSP_REQ_CTX_add1_header ,
  59 .Nm OCSP_REQ_CTX_set1_req ,
  60 .Nm OCSP_sendreq_bio
  61 .Nd OCSP responder query functions
  62 .Sh SYNOPSIS
  63 .In openssl/ocsp.h
  64 .Ft OCSP_REQ_CTX *
  65 .Fo OCSP_sendreq_new
  66 .Fa "BIO *io"
  67 .Fa "const char *path"
  68 .Fa "OCSP_REQUEST *req"
  69 .Fa "int maxline"
  70 .Fc
  71 .Ft int
  72 .Fo OCSP_sendreq_nbio
  73 .Fa "OCSP_RESPONSE **presp"
  74 .Fa "OCSP_REQ_CTX *rctx"
  75 .Fc
  76 .Ft void
  77 .Fo OCSP_REQ_CTX_free
  78 .Fa "OCSP_REQ_CTX *rctx"
  79 .Fc
  80 .Ft int
  81 .Fo OCSP_REQ_CTX_add1_header
  82 .Fa "OCSP_REQ_CTX *rctx"
  83 .Fa "const char *name"
  84 .Fa "const char *value"
  85 .Fc
  86 .Ft int
  87 .Fo OCSP_REQ_CTX_set1_req
  88 .Fa "OCSP_REQ_CTX *rctx"
  89 .Fa "OCSP_REQUEST *req"
  90 .Fc
  91 .Ft OCSP_RESPONSE *
  92 .Fo OCSP_sendreq_bio
  93 .Fa "BIO *io"
  94 .Fa "const char *path"
  95 .Fa "OCSP_REQUEST *req"
  96 .Fc
  97 .Sh DESCRIPTION
  98 The function
  99 .Fn OCSP_sendreq_new
 100 returns an
 101 .Vt OCSP_REQ_CTX
 102 structure using the responder
 103 .Fa io ,
 104 the URI path
 105 .Fa path ,
 106 the OCSP request
 107 .Fa req
 108 and with a response header maximum line length of
 109 .Fa maxline .
 110 If
 111 .Fa maxline
 112 is zero, a default value of 4k is used.
 113 The OCSP request
 114 .Fa req
 115 may be set to
 116 .Dv NULL
 117 and provided later if required.
 118 .Pp
 119 The arguments to
 120 .Fn OCSP_sendreq_new
 121 correspond to the components of the URI.
 122 For example, if the responder URI is
 123 .Pa http://ocsp.com/ocspreq ,
 124 the BIO
 125 .Fa io
 126 should be connected to host
 127 .Pa ocsp.com
 128 on port 80 and
 129 .Fa path
 130 should be set to
 131 .Qq /ocspreq .
 132 .Pp
 133 .Fn OCSP_sendreq_nbio
 134 performs non-blocking I/O on the OCSP request context
 135 .Fa rctx .
 136 When the operation is complete it returns the response in
 137 .Pf * Fa presp .
 138 If
 139 .Fn OCSP_sendreq_nbio
 140 indicates an operation should be retried, the corresponding BIO can
 141 be examined to determine which operation (read or write) should be
 142 retried and appropriate action can be taken, for example a
 143 .Xr select 2
 144 call on the underlying socket.
 145 .Pp
 146 .Fn OCSP_REQ_CTX_free
 147 frees up the OCSP context
 148 .Fa rctx .
 149 .Pp
 150 .Fn OCSP_REQ_CTX_add1_header
 151 adds header
 152 .Fa name
 153 with value
 154 .Fa value
 155 to the context
 156 .Fa rctx .
 157 The added headers are of the form
 158 .Qq Fa name : value
 159 or just
 160 .Qq Fa name
 161 if
 162 .Fa value
 163 is
 164 .Dv NULL .
 165 .Fn OCSP_REQ_CTX_add1_header
 166 can be called more than once to add multiple headers.
 167 It must be called before any calls to
 168 .Fn OCSP_sendreq_nbio .
 169 The
 170 .Fa req
 171 parameter in the initial to
 172 .Fn OCSP_sendreq_new
 173 call must be set to
 174 .Dv NULL
 175 if additional headers are set.
 176 .Pp
 177 .Fn OCSP_REQ_CTX_set1_req
 178 sets the OCSP request in
 179 .Fa rctx
 180 to
 181 .Fa req .
 182 This function should be called after any calls to
 183 .Fn OCSP_REQ_CTX_add1_header .
 184 .Pp
 185 .Fn OCSP_sendreq_bio
 186 performs an OCSP request using the responder
 187 .Fa io ,
 188 the URI path
 189 .Fa path ,
 190 the OCSP request
 191 .Fa req .
 192 It does not support retries and so cannot handle non-blocking I/O
 193 efficiently.
 194 It is retained for compatibility and its use in new applications
 195 is not recommended.
 196 .Sh RETURN VALUES
 197 .Fn OCSP_sendreq_new
 198 returns a valid
 199 .Vt OCSP_REQ_CTX
 200 structure or
 201 .Dv NULL
 202 if an error occurred.
 203 .Pp
 204 .Fn OCSP_sendreq_nbio
 205 returns 1 if the operation was completed successfully,
 206 -1 if the operation should be retried,
 207 or 0 if an error occurred.
 208 .Pp
 209 .Fn OCSP_REQ_CTX_add1_header
 210 and
 211 .Fn OCSP_REQ_CTX_set1_req
 212 return 1 for success or 0 for failure.
 213 .Pp
 214 .Fn OCSP_sendreq_bio
 215 returns the
 216 .Vt OCSP_RESPONSE
 217 structure sent by the responder or
 218 .Dv NULL
 219 if an error occurred.
 220 .Sh EXAMPLES
 221 Add a Host header for
 222 .Pa ocsp.com :
 223 .Pp
 224 .Dl OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com");
 225 .Sh SEE ALSO
 226 .Xr OCSP_cert_to_id 3 ,
 227 .Xr OCSP_request_add1_nonce 3 ,
 228 .Xr OCSP_REQUEST_new 3 ,
 229 .Xr OCSP_resp_find_status 3 ,
 230 .Xr OCSP_response_status 3
 231 .Sh CAVEATS
 232 These functions only perform a minimal HTTP query to a responder.
 233 If an application wishes to support more advanced features, it
 234 should use an alternative, more complete, HTTP library.
 235 .Pp
 236 Currently only HTTP POST queries to responders are supported.