secure/lib/libcrypto/man/man3/OCSP_REQUEST_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_REQUEST_NEW 3"
 136 .TH OCSP_REQUEST_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_REQUEST_new, OCSP_REQUEST_free, OCSP_request_add0_id, OCSP_request_sign, OCSP_request_add1_cert, OCSP_request_onereq_count, OCSP_request_onereq_get0 \- OCSP request functions
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ocsp.h>
 147 \&
 148 \& OCSP_REQUEST *OCSP_REQUEST_new(void);
 149 \& void OCSP_REQUEST_free(OCSP_REQUEST *req);
 150 \&
 151 \& OCSP_ONEREQ *OCSP_request_add0_id(OCSP_REQUEST *req, OCSP_CERTID *cid);
 152 \&
 153 \& int OCSP_request_sign(OCSP_REQUEST *req,
 154 \&                       X509 *signer, EVP_PKEY *key, const EVP_MD *dgst,
 155 \&                       STACK_OF(X509) *certs, unsigned long flags);
 156 \&
 157 \& int OCSP_request_add1_cert(OCSP_REQUEST *req, X509 *cert);
 158 \&
 159 \& int OCSP_request_onereq_count(OCSP_REQUEST *req);
 160 \& OCSP_ONEREQ *OCSP_request_onereq_get0(OCSP_REQUEST *req, int i);
 161 .Ve
 162 .SH "DESCRIPTION"
 163 .IX Header "DESCRIPTION"
 164 \&\fBOCSP_REQUEST_new()\fR allocates and returns an empty \fB\s-1OCSP_REQUEST\s0\fR structure.
 165 .PP
 166 \&\fBOCSP_REQUEST_free()\fR frees up the request structure \fBreq\fR.
 167 .PP
 168 \&\fBOCSP_request_add0_id()\fR adds certificate \s-1ID\s0 \fBcid\fR to \fBreq\fR. It returns
 169 the \fB\s-1OCSP_ONEREQ\s0\fR structure added so an application can add additional
 170 extensions to the request. The \fBid\fR parameter \fB\s-1MUST NOT\s0\fR be freed up after
 171 the operation.
 172 .PP
 173 \&\fBOCSP_request_sign()\fR signs \s-1OCSP\s0 request \fBreq\fR using certificate
 174 \&\fBsigner\fR, private key \fBkey\fR, digest \fBdgst\fR and additional certificates
 175 \&\fBcerts\fR. If the \fBflags\fR option \fB\s-1OCSP_NOCERTS\s0\fR is set then no certificates
 176 will be included in the request.
 177 .PP
 178 \&\fBOCSP_request_add1_cert()\fR adds certificate \fBcert\fR to request \fBreq\fR. The
 179 application is responsible for freeing up \fBcert\fR after use.
 180 .PP
 181 \&\fBOCSP_request_onereq_count()\fR returns the total number of \fB\s-1OCSP_ONEREQ\s0\fR
 182 structures in \fBreq\fR.
 183 .PP
 184 \&\fBOCSP_request_onereq_get0()\fR returns an internal pointer to the \fB\s-1OCSP_ONEREQ\s0\fR
 185 contained in \fBreq\fR of index \fBi\fR. The index value \fBi\fR runs from 0 to
 186 OCSP_request_onereq_count(req) \- 1.
 187 .SH "RETURN VALUES"
 188 .IX Header "RETURN VALUES"
 189 \&\fBOCSP_REQUEST_new()\fR returns an empty \fB\s-1OCSP_REQUEST\s0\fR structure or \fB\s-1NULL\s0\fR if
 190 an error occurred.
 191 .PP
 192 \&\fBOCSP_request_add0_id()\fR returns the \fB\s-1OCSP_ONEREQ\s0\fR structure containing \fBcid\fR
 193 or \fB\s-1NULL\s0\fR if an error occurred.
 194 .PP
 195 \&\fBOCSP_request_sign()\fR and \fBOCSP_request_add1_cert()\fR return 1 for success and 0
 196 for failure.
 197 .PP
 198 \&\fBOCSP_request_onereq_count()\fR returns the total number of \fB\s-1OCSP_ONEREQ\s0\fR
 199 structures in \fBreq\fR.
 200 .PP
 201 \&\fBOCSP_request_onereq_get0()\fR returns a pointer to an \fB\s-1OCSP_ONEREQ\s0\fR structure
 202 or \fB\s-1NULL\s0\fR if the index value is out or range.
 203 .SH "NOTES"
 204 .IX Header "NOTES"
 205 An \s-1OCSP\s0 request structure contains one or more \fB\s-1OCSP_ONEREQ\s0\fR structures
 206 corresponding to each certificate.
 207 .PP
 208 \&\fBOCSP_request_onereq_count()\fR and \fBOCSP_request_onereq_get0()\fR are mainly used by
 209 \&\s-1OCSP\s0 responders.
 210 .SH "EXAMPLES"
 211 .IX Header "EXAMPLES"
 212 Create an \fB\s-1OCSP_REQUEST\s0\fR structure for certificate \fBcert\fR with issuer
 213 \&\fBissuer\fR:
 214 .PP
 215 .Vb 2
 216 \& OCSP_REQUEST *req;
 217 \& OCSP_ID *cid;
 218 \&
 219 \& req = OCSP_REQUEST_new();
 220 \& if (req == NULL)
 221 \&    /* error */
 222 \& cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer);
 223 \& if (cid == NULL)
 224 \&    /* error */
 225 \&
 226 \& if (OCSP_REQUEST_add0_id(req, cid) == NULL)
 227 \&    /* error */
 228 \&
 229 \& /* Do something with req, e.g. query responder */
 230 \&
 231 \& OCSP_REQUEST_free(req);
 232 .Ve
 233 .SH "SEE ALSO"
 234 .IX Header "SEE ALSO"
 235 \&\fBcrypto\fR\|(7),
 236 \&\fBOCSP_cert_to_id\fR\|(3),
 237 \&\fBOCSP_request_add1_nonce\fR\|(3),
 238 \&\fBOCSP_resp_find_status\fR\|(3),
 239 \&\fBOCSP_response_status\fR\|(3),
 240 \&\fBOCSP_sendreq_new\fR\|(3)
 241 .SH "COPYRIGHT"
 242 .IX Header "COPYRIGHT"
 243 Copyright 2015\-2019 The OpenSSL Project Authors. All Rights Reserved.
 244 .PP
 245 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 246 this file except in compliance with the License.  You can obtain a copy
 247 in the file \s-1LICENSE\s0 in the source distribution or at
 248 <https://www.openssl.org/source/license.html>.