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

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   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 "2020-09-22" "1.1.1h" "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 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 .Ve
 164 .SH "DESCRIPTION"
 165 .IX Header "DESCRIPTION"
 166 The function \fBOCSP_sendreq_new()\fR returns an \fB\s-1OCSP_CTX\s0\fR structure using the
 167 responder \fBio\fR, the \s-1URL\s0 path \fBpath\fR, the \s-1OCSP\s0 request \fBreq\fR and with a
 168 response header maximum line length of \fBmaxline\fR. If \fBmaxline\fR is zero a
 169 default value of 4k is used. The \s-1OCSP\s0 request \fBreq\fR may be set to \fB\s-1NULL\s0\fR
 170 and provided later if required.
 171 .PP
 172 \&\fBOCSP_sendreq_nbio()\fR performs nonblocking I/O on the \s-1OCSP\s0 request context
 173 \&\fBrctx\fR. When the operation is complete it returns the response in \fB*presp\fR.
 174 .PP
 175 \&\fBOCSP_REQ_CTX_free()\fR frees up the \s-1OCSP\s0 context \fBrctx\fR.
 176 .PP
 177 \&\fBOCSP_set_max_response_length()\fR sets the maximum response length for \fBrctx\fR
 178 to \fBlen\fR. If the response exceeds this length an error occurs. If not
 179 set a default value of 100k is used.
 180 .PP
 181 \&\fBOCSP_REQ_CTX_add1_header()\fR adds header \fBname\fR with value \fBvalue\fR to the
 182 context \fBrctx\fR. It can be called more than once to add multiple headers.
 183 It \fB\s-1MUST\s0\fR be called before any calls to \fBOCSP_sendreq_nbio()\fR. The \fBreq\fR
 184 parameter in the initial to \fBOCSP_sendreq_new()\fR call \s-1MUST\s0 be set to \fB\s-1NULL\s0\fR if
 185 additional headers are set.
 186 .PP
 187 \&\fBOCSP_REQ_CTX_set1_req()\fR sets the \s-1OCSP\s0 request in \fBrctx\fR to \fBreq\fR. This
 188 function should be called after any calls to \fBOCSP_REQ_CTX_add1_header()\fR.
 189 .PP
 190 \&\fBOCSP_sendreq_bio()\fR performs an \s-1OCSP\s0 request using the responder \fBio\fR, the \s-1URL\s0
 191 path \fBpath\fR, and the \s-1OCSP\s0 request \fBreq\fR with a response header maximum line
 192 length 4k. It waits indefinitely on a response.
 193 .SH "RETURN VALUES"
 194 .IX Header "RETURN VALUES"
 195 \&\fBOCSP_sendreq_new()\fR returns a valid \fB\s-1OCSP_REQ_CTX\s0\fR structure or \fB\s-1NULL\s0\fR if
 196 an error occurred.
 197 .PP
 198 \&\fBOCSP_sendreq_nbio()\fR returns \fB1\fR if the operation was completed successfully,
 199 \&\fB\-1\fR if the operation should be retried and \fB0\fR if an error occurred.
 200 .PP
 201 \&\fBOCSP_REQ_CTX_add1_header()\fR and \fBOCSP_REQ_CTX_set1_req()\fR return \fB1\fR for success
 202 and \fB0\fR for failure.
 203 .PP
 204 \&\fBOCSP_sendreq_bio()\fR returns the \fB\s-1OCSP_RESPONSE\s0\fR structure sent by the
 205 responder or \fB\s-1NULL\s0\fR if an error occurred.
 206 .PP
 207 \&\fBOCSP_REQ_CTX_free()\fR and \fBOCSP_set_max_response_length()\fR do not return values.
 208 .SH "NOTES"
 209 .IX Header "NOTES"
 210 These functions only perform a minimal \s-1HTTP\s0 query to a responder. If an
 211 application wishes to support more advanced features it should use an
 212 alternative more complete \s-1HTTP\s0 library.
 213 .PP
 214 Currently only \s-1HTTP POST\s0 queries to responders are supported.
 215 .PP
 216 The arguments to \fBOCSP_sendreq_new()\fR correspond to the components of the \s-1URL.\s0
 217 For example if the responder \s-1URL\s0 is \fBhttp://ocsp.com/ocspreq\fR the \s-1BIO\s0
 218 \&\fBio\fR should be connected to host \fBocsp.com\fR on port 80 and \fBpath\fR
 219 should be set to \fB\*(L"/ocspreq\*(R"\fR
 220 .PP
 221 The headers added with \fBOCSP_REQ_CTX_add1_header()\fR are of the form
 222 "\fBname\fR: \fBvalue\fR\*(L" or just \*(R"\fBname\fR" if \fBvalue\fR is \fB\s-1NULL\s0\fR. So to add
 223 a Host header for \fBocsp.com\fR you would call:
 224 .PP
 225 .Vb 1
 226 \& OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com");
 227 .Ve
 228 .PP
 229 If \fBOCSP_sendreq_nbio()\fR indicates an operation should be retried the
 230 corresponding \s-1BIO\s0 can be examined to determine which operation (read or
 231 write) should be retried and appropriate action taken (for example a \fBselect()\fR
 232 call on the underlying socket).
 233 .PP
 234 \&\fBOCSP_sendreq_bio()\fR does not support retries and so cannot handle nonblocking
 235 I/O efficiently. It is retained for compatibility and its use in new
 236 applications is not recommended.
 237 .SH "SEE ALSO"
 238 .IX Header "SEE ALSO"
 239 \&\fBcrypto\fR\|(7),
 240 \&\fBOCSP_cert_to_id\fR\|(3),
 241 \&\fBOCSP_request_add1_nonce\fR\|(3),
 242 \&\fBOCSP_REQUEST_new\fR\|(3),
 243 \&\fBOCSP_resp_find_status\fR\|(3),
 244 \&\fBOCSP_response_status\fR\|(3)
 245 .SH "COPYRIGHT"
 246 .IX Header "COPYRIGHT"
 247 Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved.
 248 .PP
 249 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 250 this file except in compliance with the License.  You can obtain a copy
 251 in the file \s-1LICENSE\s0 in the source distribution or at
 252 <https://www.openssl.org/source/license.html>.