lib/libcrypto/man/OCSP_REQUEST_new.3

   1 .\"     $OpenBSD: OCSP_REQUEST_new.3,v 1.7 2016/12/25 22:15:10 schwarze Exp $
   2 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
   3 .\"
   4 .\" This file is a derived work.
   5 .\" The changes are covered by the following Copyright and license:
   6 .\"
   7 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
   8 .\"
   9 .\" Permission to use, copy, modify, and distribute this software for any
  10 .\" purpose with or without fee is hereby granted, provided that the above
  11 .\" copyright notice and this permission notice appear in all copies.
  12 .\"
  13 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  14 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  15 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  16 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  17 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  18 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  19 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  20 .\"
  21 .\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
  22 .\" Copyright (c) 2014, 2016 The OpenSSL Project.  All rights reserved.
  23 .\"
  24 .\" Redistribution and use in source and binary forms, with or without
  25 .\" modification, are permitted provided that the following conditions
  26 .\" are met:
  27 .\"
  28 .\" 1. Redistributions of source code must retain the above copyright
  29 .\"    notice, this list of conditions and the following disclaimer.
  30 .\"
  31 .\" 2. Redistributions in binary form must reproduce the above copyright
  32 .\"    notice, this list of conditions and the following disclaimer in
  33 .\"    the documentation and/or other materials provided with the
  34 .\"    distribution.
  35 .\"
  36 .\" 3. All advertising materials mentioning features or use of this
  37 .\"    software must display the following acknowledgment:
  38 .\"    "This product includes software developed by the OpenSSL Project
  39 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  40 .\"
  41 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  42 .\"    endorse or promote products derived from this software without
  43 .\"    prior written permission. For written permission, please contact
  44 .\"    openssl-core@openssl.org.
  45 .\"
  46 .\" 5. Products derived from this software may not be called "OpenSSL"
  47 .\"    nor may "OpenSSL" appear in their names without prior written
  48 .\"    permission of the OpenSSL Project.
  49 .\"
  50 .\" 6. Redistributions of any form whatsoever must retain the following
  51 .\"    acknowledgment:
  52 .\"    "This product includes software developed by the OpenSSL Project
  53 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  54 .\"
  55 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  56 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  57 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  58 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  59 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  60 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  61 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  62 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  63 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  64 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  65 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  66 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  67 .\"
  68 .Dd $Mdocdate: December 25 2016 $
  69 .Dt OCSP_REQUEST_NEW 3
  70 .Os
  71 .Sh NAME
  72 .Nm OCSP_REQUEST_new ,
  73 .Nm OCSP_REQUEST_free ,
  74 .Nm OCSP_SIGNATURE_new ,
  75 .Nm OCSP_SIGNATURE_free ,
  76 .Nm OCSP_REQINFO_new ,
  77 .Nm OCSP_REQINFO_free ,
  78 .Nm OCSP_ONEREQ_new ,
  79 .Nm OCSP_ONEREQ_free ,
  80 .Nm OCSP_request_add0_id ,
  81 .Nm OCSP_request_sign ,
  82 .Nm OCSP_request_add1_cert ,
  83 .Nm OCSP_request_onereq_count ,
  84 .Nm OCSP_request_onereq_get0
  85 .Nd OCSP request functions
  86 .Sh SYNOPSIS
  87 .In openssl/ocsp.h
  88 .Ft OCSP_REQUEST *
  89 .Fn OCSP_REQUEST_new void
  90 .Ft void
  91 .Fn OCSP_REQUEST_free "OCSP_REQUEST *req"
  92 .Ft OCSP_SIGNATURE *
  93 .Fn OCSP_SIGNATURE_new void
  94 .Ft void
  95 .Fn OCSP_SIGNATURE_free "OCSP_SIGNATURE *signature"
  96 .Ft OCSP_REQINFO *
  97 .Fn OCSP_REQINFO_new void
  98 .Ft void
  99 .Fn OCSP_REQINFO_free "OCSP_REQINFO *reqinfo"
 100 .Ft OCSP_ONEREQ *
 101 .Fn OCSP_ONEREQ_new void
 102 .Ft void
 103 .Fn OCSP_ONEREQ_free "OCSP_ONEREQ *onereq"
 104 .Ft OCSP_ONEREQ *
 105 .Fo OCSP_request_add0_id
 106 .Fa "OCSP_REQUEST *req"
 107 .Fa "OCSP_CERTID *cid"
 108 .Fc
 109 .Ft int
 110 .Fo OCSP_request_sign
 111 .Fa "OCSP_REQUEST *req"
 112 .Fa "X509 *signer"
 113 .Fa "EVP_PKEY *key"
 114 .Fa "const EVP_MD *dgst"
 115 .Fa "STACK_OF(X509) *certs"
 116 .Fa "unsigned long flags"
 117 .Fc
 118 .Ft int
 119 .Fo OCSP_request_add1_cert
 120 .Fa "OCSP_REQUEST *req"
 121 .Fa "X509 *cert"
 122 .Fc
 123 .Ft int
 124 .Fo OCSP_request_onereq_count
 125 .Fa "OCSP_REQUEST *req"
 126 .Fc
 127 .Ft OCSP_ONEREQ *
 128 .Fo OCSP_request_onereq_get0
 129 .Fa "OCSP_REQUEST *req"
 130 .Fa "int i"
 131 .Fc
 132 .Sh DESCRIPTION
 133 .Fn OCSP_REQUEST_new
 134 allocates and initializes an empty
 135 .Vt OCSP_REQUEST
 136 object, representing an ASN.1
 137 .Vt OCSPRequest
 138 structure defined in RFC 6960.
 139 .Fn OCSP_REQUEST_free
 140 frees
 141 .Fa req .
 142 .Pp
 143 .Fn OCSP_SIGNATURE_new
 144 allocates and initializes an empty
 145 .Vt OCSP_SIGNATURE
 146 object, representing an ASN.1
 147 .Vt Signature
 148 structure defined in RFC 6960.
 149 Such an object is used inside
 150 .Vt OCSP_REQUEST .
 151 .Fn OCSP_SIGNATURE_free
 152 frees
 153 .Fa signature .
 154 .Pp
 155 .Fn OCSP_REQINFO_new
 156 allocates and initializes an empty
 157 .Vt OCSP_REQINFO
 158 object, representing an ASN.1
 159 .Vt TBSRequest
 160 structure defined in RFC 6960.
 161 Such an object is used inside
 162 .Vt OCSP_REQUEST .
 163 It asks about the validity of one or more certificates.
 164 .Fn OCSP_REQINFO_free
 165 frees
 166 .Fa reqinfo .
 167 .Pp
 168 .Fn OCSP_ONEREQ_new
 169 allocates and initializes an empty
 170 .Vt OCSP_ONEREQ
 171 object, representing an ASN.1
 172 .Vt Request
 173 structure defined in RFC 6960.
 174 Such objects are used inside
 175 .Vt OCSP_REQINFO .
 176 Each one asks about the validity of one certificiate.
 177 .Fn OCSP_ONEREQ_free
 178 frees
 179 .Fa onereq .
 180 .Pp
 181 .Fn OCSP_request_add0_id
 182 adds certificate ID
 183 .Fa cid
 184 to
 185 .Fa req .
 186 It returns the
 187 .Vt OCSP_ONEREQ
 188 object added so an application can add additional extensions to the
 189 request.
 190 The
 191 .Fa cid
 192 parameter must not be freed up after the operation.
 193 .Pp
 194 .Fn OCSP_request_sign
 195 signs OCSP request
 196 .Fa req
 197 using certificate
 198 .Fa signer ,
 199 private key
 200 .Fa key ,
 201 digest
 202 .Fa dgst ,
 203 and additional certificates
 204 .Fa certs .
 205 If the
 206 .Fa flags
 207 option
 208 .Dv OCSP_NOCERTS
 209 is set, then no certificates will be included in the request.
 210 .Pp
 211 .Fn OCSP_request_add1_cert
 212 adds certificate
 213 .Fa cert
 214 to request
 215 .Fa req .
 216 The application is responsible for freeing up
 217 .Fa cert
 218 after use.
 219 .Pp
 220 .Fn OCSP_request_onereq_count
 221 returns the total number of
 222 .Vt OCSP_ONEREQ
 223 objects in
 224 .Fa req .
 225 .Pp
 226 .Fn OCSP_request_onereq_get0
 227 returns an internal pointer to the
 228 .Vt OCSP_ONEREQ
 229 contained in
 230 .Fa req
 231 of index
 232 .Fa i .
 233 The index value
 234 .Fa i
 235 runs from 0 to
 236 .Fn OCSP_request_onereq_count req No - 1 .
 237 .Pp
 238 .Fn OCSP_request_onereq_count
 239 and
 240 .Fn OCSP_request_onereq_get0
 241 are mainly used by OCSP responders.
 242 .Sh RETURN VALUES
 243 .Fn OCSP_REQUEST_new ,
 244 .Fn OCSP_SIGNATURE_new ,
 245 .Fn OCSP_REQINFO_new ,
 246 and
 247 .Fn OCSP_ONEREQ_new
 248 return an empty
 249 .Vt OCSP_REQUEST ,
 250 .Vt OCSP_SIGNATURE ,
 251 .Vt OCSP_REQINFO ,
 252 or
 253 .Vt OCSP_ONEREQ
 254 object, respectively, or
 255 .Dv NULL
 256 if an error occurred.
 257 .Pp
 258 .Fn OCSP_request_add0_id
 259 returns the
 260 .Vt OCSP_ONEREQ
 261 object containing
 262 .Fa cid
 263 or
 264 .Dv NULL
 265 if an error occurred.
 266 .Pp
 267 .Fn OCSP_request_sign
 268 and
 269 .Fn OCSP_request_add1_cert
 270 return 1 for success or 0 for failure.
 271 .Pp
 272 .Fn OCSP_request_onereq_count
 273 returns the total number of
 274 .Vt OCSP_ONEREQ
 275 objects in
 276 .Fa req .
 277 .Pp
 278 .Fn OCSP_request_onereq_get0
 279 returns a pointer to an
 280 .Vt OCSP_ONEREQ
 281 object or
 282 .Dv NULL
 283 if the index value is out of range.
 284 .Sh EXAMPLES
 285 Create an
 286 .Vt OCSP_REQUEST
 287 object for certificate
 288 .Fa cert
 289 with issuer
 290 .Fa issuer :
 291 .Bd -literal -offset indent
 292 OCSP_REQUEST *req;
 293 OCSP_ID *cid;
 294
 295 req = OCSP_REQUEST_new();
 296 if (req == NULL)
 297         /* error */
 298 cid = OCSP_cert_to_id(EVP_sha1(), cert, issuer);
 299 if (cid == NULL)
 300         /* error */
 301
 302 if (OCSP_REQUEST_add0_id(req, cid) == NULL)
 303         /* error */
 304
 305  /* Do something with req, e.g. query responder */
 306
 307 OCSP_REQUEST_free(req);
 308 .Ed
 309 .Sh SEE ALSO
 310 .Xr ACCESS_DESCRIPTION_new 3 ,
 311 .Xr OCSP_cert_to_id 3 ,
 312 .Xr OCSP_request_add1_nonce 3 ,
 313 .Xr OCSP_resp_find_status 3 ,
 314 .Xr OCSP_response_status 3 ,
 315 .Xr OCSP_sendreq_new 3 ,
 316 .Xr OCSP_SERVICELOC_new 3
 317 .Sh STANDARDS
 318 RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate
 319 Status Protocol, section 4.1: Request Syntax