secure/lib/libcrypto/man/man3/OCSP_sendreq_new.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "OCSP_SENDREQ_NEW 3"
 136 .TH OCSP_SENDREQ_NEW 3 "2022-05-03" "1.1.1o" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 OCSP_sendreq_new, OCSP_sendreq_nbio, OCSP_REQ_CTX_free, OCSP_set_max_response_length, OCSP_REQ_CTX_add1_header, OCSP_REQ_CTX_set1_req, OCSP_sendreq_bio, OCSP_REQ_CTX_i2d \&\- OCSP responder query functions
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ocsp.h>
 147 \&
 148 \& OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, OCSP_REQUEST *req,
 149 \&                                int maxline);
 150 \&
 151 \& int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OCSP_REQ_CTX *rctx);
 152 \&
 153 \& void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx);
 154 \&
 155 \& void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, unsigned long len);
 156 \&
 157 \& int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx,
 158 \&                              const char *name, const char *value);
 159 \&
 160 \& int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req);
 161 \&
 162 \& OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req);
 163 \&
 164 \& int OCSP_REQ_CTX_i2d(OCSP_REQ_CTX *rctx, const char *content_type,
 165 \&                      const ASN1_ITEM *it, ASN1_VALUE *req);
 166 .Ve
 167 .SH "DESCRIPTION"
 168 .IX Header "DESCRIPTION"
 169 The function \fBOCSP_sendreq_new()\fR returns an \fB\s-1OCSP_CTX\s0\fR structure using the
 170 responder \fBio\fR, the \s-1URL\s0 path \fBpath\fR, the \s-1OCSP\s0 request \fBreq\fR and with a
 171 response header maximum line length of \fBmaxline\fR. If \fBmaxline\fR is zero a
 172 default value of 4k is used. The \s-1OCSP\s0 request \fBreq\fR may be set to \fB\s-1NULL\s0\fR
 173 and provided later if required.
 174 .PP
 175 \&\fBOCSP_sendreq_nbio()\fR performs nonblocking I/O on the \s-1OCSP\s0 request context
 176 \&\fBrctx\fR. When the operation is complete it returns the response in \fB*presp\fR.
 177 .PP
 178 \&\fBOCSP_REQ_CTX_free()\fR frees up the \s-1OCSP\s0 context \fBrctx\fR.
 179 .PP
 180 \&\fBOCSP_set_max_response_length()\fR sets the maximum response length for \fBrctx\fR
 181 to \fBlen\fR. If the response exceeds this length an error occurs. If not
 182 set a default value of 100k is used.
 183 .PP
 184 \&\fBOCSP_REQ_CTX_add1_header()\fR adds header \fBname\fR with value \fBvalue\fR to the
 185 context \fBrctx\fR. It can be called more than once to add multiple headers.
 186 It \fB\s-1MUST\s0\fR be called before any calls to \fBOCSP_sendreq_nbio()\fR. The \fBreq\fR
 187 parameter in the initial to \fBOCSP_sendreq_new()\fR call \s-1MUST\s0 be set to \fB\s-1NULL\s0\fR if
 188 additional headers are set.
 189 .PP
 190 \&\fBOCSP_REQ_CTX_set1_req()\fR sets the \s-1OCSP\s0 request in \fBrctx\fR to \fBreq\fR. This
 191 function should be called after any calls to \fBOCSP_REQ_CTX_add1_header()\fR.
 192 OCSP_REQ_CTX_set1_req(rctx, req) is equivalent to the following:
 193 .PP
 194 .Vb 2
 195 \& OCSP_REQ_CTX_i2d(rctx, "application/ocsp\-request",
 196 \&                        ASN1_ITEM_rptr(OCSP_REQUEST), (ASN1_VALUE *)req)
 197 .Ve
 198 .PP
 199 \&\fBOCSP_REQ_CTX_i2d()\fR sets the request context \fBrctx\fR to have the request
 200 \&\fBreq\fR, which has the \s-1ASN.1\s0 type \fBit\fR.
 201 The \fBcontent_type\fR, if not \s-1NULL,\s0 will be included in the \s-1HTTP\s0 request.
 202 The function should be called after all other headers have already been added.
 203 .PP
 204 \&\fBOCSP_sendreq_bio()\fR performs an \s-1OCSP\s0 request using the responder \fBio\fR, the \s-1URL\s0
 205 path \fBpath\fR, and the \s-1OCSP\s0 request \fBreq\fR with a response header maximum line
 206 length 4k. It waits indefinitely on a response.
 207 .SH "RETURN VALUES"
 208 .IX Header "RETURN VALUES"
 209 \&\fBOCSP_sendreq_new()\fR returns a valid \fB\s-1OCSP_REQ_CTX\s0\fR structure or \fB\s-1NULL\s0\fR if
 210 an error occurred.
 211 .PP
 212 \&\fBOCSP_sendreq_nbio()\fR returns \fB1\fR if the operation was completed successfully,
 213 \&\fB\-1\fR if the operation should be retried and \fB0\fR if an error occurred.
 214 .PP
 215 \&\fBOCSP_REQ_CTX_add1_header()\fR, \fBOCSP_REQ_CTX_set1_req()\fR, and \fBOCSP_REQ_CTX_i2d()\fR
 216 return \fB1\fR for success and \fB0\fR for failure.
 217 .PP
 218 \&\fBOCSP_sendreq_bio()\fR returns the \fB\s-1OCSP_RESPONSE\s0\fR structure sent by the
 219 responder or \fB\s-1NULL\s0\fR if an error occurred.
 220 .PP
 221 \&\fBOCSP_REQ_CTX_free()\fR and \fBOCSP_set_max_response_length()\fR do not return values.
 222 .SH "NOTES"
 223 .IX Header "NOTES"
 224 These functions only perform a minimal \s-1HTTP\s0 query to a responder. If an
 225 application wishes to support more advanced features it should use an
 226 alternative more complete \s-1HTTP\s0 library.
 227 .PP
 228 Currently only \s-1HTTP POST\s0 queries to responders are supported.
 229 .PP
 230 The arguments to \fBOCSP_sendreq_new()\fR correspond to the components of the \s-1URL.\s0
 231 For example if the responder \s-1URL\s0 is \fBhttp://ocsp.com/ocspreq\fR the \s-1BIO\s0
 232 \&\fBio\fR should be connected to host \fBocsp.com\fR on port 80 and \fBpath\fR
 233 should be set to \fB\*(L"/ocspreq\*(R"\fR
 234 .PP
 235 The headers added with \fBOCSP_REQ_CTX_add1_header()\fR are of the form
 236 "\fBname\fR: \fBvalue\fR\*(L" or just \*(R"\fBname\fR" if \fBvalue\fR is \fB\s-1NULL\s0\fR. So to add
 237 a Host header for \fBocsp.com\fR you would call:
 238 .PP
 239 .Vb 1
 240 \& OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com");
 241 .Ve
 242 .PP
 243 If \fBOCSP_sendreq_nbio()\fR indicates an operation should be retried the
 244 corresponding \s-1BIO\s0 can be examined to determine which operation (read or
 245 write) should be retried and appropriate action taken (for example a \fBselect()\fR
 246 call on the underlying socket).
 247 .PP
 248 \&\fBOCSP_sendreq_bio()\fR does not support retries and so cannot handle nonblocking
 249 I/O efficiently. It is retained for compatibility and its use in new
 250 applications is not recommended.
 251 .SH "SEE ALSO"
 252 .IX Header "SEE ALSO"
 253 \&\fBcrypto\fR\|(7),
 254 \&\fBOCSP_cert_to_id\fR\|(3),
 255 \&\fBOCSP_request_add1_nonce\fR\|(3),
 256 \&\fBOCSP_REQUEST_new\fR\|(3),
 257 \&\fBOCSP_resp_find_status\fR\|(3),
 258 \&\fBOCSP_response_status\fR\|(3)
 259 .SH "COPYRIGHT"
 260 .IX Header "COPYRIGHT"
 261 Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved.
 262 .PP
 263 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 264 this file except in compliance with the License.  You can obtain a copy
 265 in the file \s-1LICENSE\s0 in the source distribution or at
 266 <https://www.openssl.org/source/license.html>.