secure/lib/libcrypto/man/OCSP_sendreq_new.3

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