lib/libcrypto/man/OCSP_cert_to_id.3

   1 .\"     $OpenBSD: OCSP_cert_to_id.3,v 1.6 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_CERT_TO_ID 3
  70 .Os
  71 .Sh NAME
  72 .Nm OCSP_CERTID_new ,
  73 .Nm OCSP_CERTID_free ,
  74 .Nm OCSP_cert_to_id ,
  75 .Nm OCSP_cert_id_new ,
  76 .Nm OCSP_id_issuer_cmp ,
  77 .Nm OCSP_id_cmp ,
  78 .Nm OCSP_id_get0_info
  79 .Nd OCSP certificate ID utility functions
  80 .Sh SYNOPSIS
  81 .In openssl/ocsp.h
  82 .Ft OCSP_CERTID *
  83 .Fn OCSP_CERTID_new void
  84 .Ft void
  85 .Fn OCSP_CERTID_free "OCSP_CERTID *id"
  86 .Ft OCSP_CERTID *
  87 .Fo OCSP_cert_to_id
  88 .Fa "const EVP_MD *dgst"
  89 .Fa "X509 *subject"
  90 .Fa "X509 *issuer"
  91 .Fc
  92 .Ft OCSP_CERTID *
  93 .Fo OCSP_cert_id_new
  94 .Fa "const EVP_MD *dgst"
  95 .Fa "X509_NAME *issuerName"
  96 .Fa "ASN1_BIT_STRING *issuerKey"
  97 .Fa "ASN1_INTEGER *serialNumber"
  98 .Fc
  99 .Ft int
 100 .Fo OCSP_id_issuer_cmp
 101 .Fa "OCSP_CERTID *a"
 102 .Fa "OCSP_CERTID *b"
 103 .Fc
 104 .Ft int
 105 .Fo OCSP_id_cmp
 106 .Fa "OCSP_CERTID *a"
 107 .Fa "OCSP_CERTID *b"
 108 .Fc
 109 .Ft int
 110 .Fo OCSP_id_get0_info
 111 .Fa "ASN1_OCTET_STRING **piNameHash"
 112 .Fa "ASN1_OBJECT **pmd"
 113 .Fa "ASN1_OCTET_STRING **pikeyHash"
 114 .Fa "ASN1_INTEGER **pserial"
 115 .Fa "OCSP_CERTID *cid"
 116 .Fc
 117 .Sh DESCRIPTION
 118 .Fn OCSP_CERTID_new
 119 allocates and initializes an empty
 120 .Vt OCSP_CERTID
 121 object, representing an ASN.1
 122 .Vt CertID
 123 structure defined in RFC 6960.
 124 It can store hashes of an issuer's distinguished name and public
 125 key together with a serial number of a certificate.
 126 It is used by the
 127 .Vt OCSP_ONEREQ
 128 object described in
 129 .Xr OCSP_ONEREQ_new 3
 130 and by the
 131 .Vt OCSP_SINGLERESP
 132 object described in
 133 .Xr OCSP_SINGLERESP_new 3 .
 134 .Fn OCSP_CERTID_free
 135 frees
 136 .Fa id .
 137 .Pp
 138 .Fn OCSP_cert_to_id
 139 creates and returns a new
 140 .Vt OCSP_CERTID
 141 object using message digest
 142 .Fa dgst
 143 for certificate
 144 .Fa subject
 145 with issuer
 146 .Fa issuer .
 147 If
 148 .Fa dgst
 149 is
 150 .Dv NULL
 151 then SHA1 is used.
 152 .Pp
 153 .Fn OCSP_cert_id_new
 154 creates and returns a new
 155 .Vt OCSP_CERTID
 156 using
 157 .Fa dgst
 158 and issuer name
 159 .Fa issuerName ,
 160 issuer key hash
 161 .Fa issuerKey
 162 and serial number
 163 .Fa serialNumber .
 164 .Pp
 165 .Fn OCSP_id_cmp
 166 compares
 167 .Vt OCSP_CERTID
 168 .Fa a
 169 and
 170 .Fa b .
 171 .Pp
 172 .Fn OCSP_id_issuer_cmp
 173 compares only the issuer name of
 174 .Vt OCSP_CERTID
 175 .Fa a
 176 and
 177 .Fa b .
 178 .Pp
 179 .Fn OCSP_id_get0_info
 180 returns the issuer name hash, hash OID, issuer key hash and serial
 181 number contained in
 182 .Fa cid .
 183 If any of the values are not required the corresponding parameter can be
 184 set to
 185 .Dv NULL .
 186 The values returned by
 187 .Fn OCSP_id_get0_info
 188 are internal pointers and must not be freed up by an application:
 189 they will be freed when the corresponding
 190 .Vt OCSP_CERTID
 191 object is freed.
 192 .Pp
 193 OCSP clients will typically only use
 194 .Fn OCSP_cert_to_id
 195 or
 196 .Fn OCSP_cert_id_new :
 197 the other functions are used by responder applications.
 198 .Sh RETURN VALUES
 199 .Fn OCSP_CERTID_new ,
 200 .Fn OCSP_cert_to_id ,
 201 and
 202 .Fn OCSP_cert_id_new
 203 return either a pointer to a valid
 204 .Vt OCSP_CERTID
 205 object or
 206 .Dv NULL
 207 if an error occurred.
 208 .Pp
 209 .Fn OCSP_id_cmp
 210 and
 211 .Fn OCSP_id_issuer_cmp
 212 return 0 for a match or non-zero otherwise.
 213 .Pp
 214 .Fn OCSP_id_get0_info
 215 returns 1 for success or 0 for failure.
 216 .Sh SEE ALSO
 217 .Xr OCSP_request_add1_nonce 3 ,
 218 .Xr OCSP_REQUEST_new 3 ,
 219 .Xr OCSP_resp_find_status 3 ,
 220 .Xr OCSP_response_status 3 ,
 221 .Xr OCSP_sendreq_new 3 ,
 222 .Xr X509_get_issuer_name 3 ,
 223 .Xr X509_NAME_new 3
 224 .Sh STANDARDS
 225 RFC 6960: X.509 Internet Public Key Infrastructure Online Certificate
 226 Status Protocol, section 4: Details of the Protocol