secure/lib/libcrypto/man/OCSP_sendreq_new.3

   1 .\" Automatically generated by Pod::Man 4.09 (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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "OCSP_SENDREQ_NEW 3"
 132 .TH OCSP_SENDREQ_NEW 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ocsp.h>
 143 \&
 144 \& OCSP_REQ_CTX *OCSP_sendreq_new(BIO *io, const char *path, OCSP_REQUEST *req,
 145 \&                                int maxline);
 146 \&
 147 \& int OCSP_sendreq_nbio(OCSP_RESPONSE **presp, OCSP_REQ_CTX *rctx);
 148 \&
 149 \& void OCSP_REQ_CTX_free(OCSP_REQ_CTX *rctx);
 150 \&
 151 \& void OCSP_set_max_response_length(OCSP_REQ_CTX *rctx, unsigned long len);
 152 \&
 153 \& int OCSP_REQ_CTX_add1_header(OCSP_REQ_CTX *rctx,
 154 \&                              const char *name, const char *value);
 155 \&
 156 \& int OCSP_REQ_CTX_set1_req(OCSP_REQ_CTX *rctx, OCSP_REQUEST *req);
 157 \&
 158 \& OCSP_RESPONSE *OCSP_sendreq_bio(BIO *io, const char *path, OCSP_REQUEST *req,
 159 \&                                 int maxline);
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 The function \fIOCSP_sendreq_new()\fR returns an \fB\s-1OCSP_CTX\s0\fR structure using the
 164 responder \fBio\fR, the \s-1URL\s0 path \fBpath\fR, the \s-1OCSP\s0 request \fBreq\fR and with a
 165 response header maximum line length of \fBmaxline\fR. If \fBmaxline\fR is zero a
 166 default value of 4k is used. The \s-1OCSP\s0 request \fBreq\fR may be set to \fB\s-1NULL\s0\fR
 167 and provided later if required.
 168 .PP
 169 \&\fIOCSP_sendreq_nbio()\fR performs non-blocking I/O on the \s-1OCSP\s0 request context
 170 \&\fBrctx\fR. When the operation is complete it returns the response in \fB*presp\fR.
 171 .PP
 172 \&\fIOCSP_REQ_CTX_free()\fR frees up the \s-1OCSP\s0 context \fBrctx\fR.
 173 .PP
 174 \&\fIOCSP_set_max_response_length()\fR sets the maximum response length for \fBrctx\fR
 175 to \fBlen\fR. If the response exceeds this length an error occurs. If not
 176 set a default value of 100k is used.
 177 .PP
 178 \&\fIOCSP_REQ_CTX_add1_header()\fR adds header \fBname\fR with value \fBvalue\fR to the
 179 context \fBrctx\fR. It can be called more than once to add multiple headers.
 180 It \fB\s-1MUST\s0\fR be called before any calls to \fIOCSP_sendreq_nbio()\fR. The \fBreq\fR
 181 parameter in the initial to \fIOCSP_sendreq_new()\fR call \s-1MUST\s0 be set to \fB\s-1NULL\s0\fR if
 182 additional headers are set.
 183 .PP
 184 \&\fIOCSP_REQ_CTX_set1_req()\fR sets the \s-1OCSP\s0 request in \fBrctx\fR to \fBreq\fR. This
 185 function should be called after any calls to \fIOCSP_REQ_CTX_add1_header()\fR.
 186 .PP
 187 \&\fIOCSP_sendreq_bio()\fR performs an \s-1OCSP\s0 request using the responder \fBio\fR, the \s-1URL\s0
 188 path \fBpath\fR, the \s-1OCSP\s0 request \fBreq\fR and with a response header maximum line
 189 length of \fBmaxline\fR. If \fBmaxline\fR is zero a default value of 4k is used.
 190 .SH "RETURN VALUES"
 191 .IX Header "RETURN VALUES"
 192 \&\fIOCSP_sendreq_new()\fR returns a valid \fB\s-1OCSP_REQ_CTX\s0\fR structure or \fB\s-1NULL\s0\fR if
 193 an error occurred.
 194 .PP
 195 \&\fIOCSP_sendreq_nbio()\fR returns \fB1\fR if the operation was completed successfully,
 196 \&\fB\-1\fR if the operation should be retried and \fB0\fR if an error occurred.
 197 .PP
 198 \&\fIOCSP_REQ_CTX_add1_header()\fR and \fIOCSP_REQ_CTX_set1_req()\fR return \fB1\fR for success
 199 and \fB0\fR for failure.
 200 .PP
 201 \&\fIOCSP_sendreq_bio()\fR returns the \fB\s-1OCSP_RESPONSE\s0\fR structure sent by the
 202 responder or \fB\s-1NULL\s0\fR if an error occurred.
 203 .PP
 204 \&\fIOCSP_REQ_CTX_free()\fR and \fIOCSP_set_max_response_length()\fR do not return values.
 205 .SH "NOTES"
 206 .IX Header "NOTES"
 207 These functions only perform a minimal \s-1HTTP\s0 query to a responder. If an
 208 application wishes to support more advanced features it should use an
 209 alternative more complete \s-1HTTP\s0 library.
 210 .PP
 211 Currently only \s-1HTTP POST\s0 queries to responders are supported.
 212 .PP
 213 The arguments to \fIOCSP_sendreq_new()\fR correspond to the components of the \s-1URL.\s0
 214 For example if the responder \s-1URL\s0 is \fBhttp://ocsp.com/ocspreq\fR the \s-1BIO\s0
 215 \&\fBio\fR should be connected to host \fBocsp.com\fR on port 80 and \fBpath\fR
 216 should be set to \fB\*(L"/ocspreq\*(R"\fR
 217 .PP
 218 The headers added with \fIOCSP_REQ_CTX_add1_header()\fR are of the form
 219 "\fBname\fR: \fBvalue\fR\*(L" or just \*(R"\fBname\fR" if \fBvalue\fR is \fB\s-1NULL\s0\fR. So to add
 220 a Host header for \fBocsp.com\fR you would call:
 221 .PP
 222 .Vb 1
 223 \& OCSP_REQ_CTX_add1_header(ctx, "Host", "ocsp.com");
 224 .Ve
 225 .PP
 226 If \fIOCSP_sendreq_nbio()\fR indicates an operation should be retried the
 227 corresponding \s-1BIO\s0 can be examined to determine which operation (read or
 228 write) should be retried and appropriate action taken (for example a \fIselect()\fR
 229 call on the underlying socket).
 230 .PP
 231 \&\fIOCSP_sendreq_bio()\fR does not support retries and so cannot handle non-blocking
 232 I/O efficiently. It is retained for compatibility and its use in new
 233 applications is not recommended.
 234 .SH "SEE ALSO"
 235 .IX Header "SEE ALSO"
 236 \&\fIcrypto\fR\|(7),
 237 \&\fIOCSP_cert_to_id\fR\|(3),
 238 \&\fIOCSP_request_add1_nonce\fR\|(3),
 239 \&\fIOCSP_REQUEST_new\fR\|(3),
 240 \&\fIOCSP_resp_find_status\fR\|(3),
 241 \&\fIOCSP_response_status\fR\|(3)
 242 .SH "COPYRIGHT"
 243 .IX Header "COPYRIGHT"
 244 Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved.
 245 .PP
 246 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 247 this file except in compliance with the License.  You can obtain a copy
 248 in the file \s-1LICENSE\s0 in the source distribution or at
 249 <https://www.openssl.org/source/license.html>.