doc/man3/OCSP_response_status.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create,
   6 OCSP_RESPONSE_free, OCSP_RESPID_set_by_name,
   7 OCSP_RESPID_set_by_key_ex, OCSP_RESPID_set_by_key, OCSP_RESPID_match_ex,
   8 OCSP_RESPID_match, OCSP_basic_sign, OCSP_basic_sign_ctx
   9 - OCSP response functions
  10
  11 =head1 SYNOPSIS
  12
  13  #include <openssl/ocsp.h>
  14
  15  int OCSP_response_status(OCSP_RESPONSE *resp);
  16  OCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp);
  17  OCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs);
  18  void OCSP_RESPONSE_free(OCSP_RESPONSE *resp);
  19
  20  int OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert);
  21  int OCSP_RESPID_set_by_key_ex(OCSP_RESPID *respid, X509 *cert,
  22                                OPENSSL_CTX *libctx, const char *propq);
  23  int OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert);
  24  int OCSP_RESPID_match_ex(OCSP_RESPID *respid, X509 *cert, OPENSSL_CTX *libctx,
  25                           const char *propq);
  26  int OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert);
  27
  28  int OCSP_basic_sign(OCSP_BASICRESP *brsp, X509 *signer, EVP_PKEY *key,
  29                      const EVP_MD *dgst, STACK_OF(X509) *certs,
  30                      unsigned long flags);
  31  int OCSP_basic_sign_ctx(OCSP_BASICRESP *brsp, X509 *signer, EVP_MD_CTX *ctx,
  32                          STACK_OF(X509) *certs, unsigned long flags);
  33
  34 =head1 DESCRIPTION
  35
  36 OCSP_response_status() returns the OCSP response status of I<resp>. It returns
  37 one of the values: I<OCSP_RESPONSE_STATUS_SUCCESSFUL>,
  38 I<OCSP_RESPONSE_STATUS_MALFORMEDREQUEST>,
  39 I<OCSP_RESPONSE_STATUS_INTERNALERROR>, I<OCSP_RESPONSE_STATUS_TRYLATER>
  40 I<OCSP_RESPONSE_STATUS_SIGREQUIRED>, or I<OCSP_RESPONSE_STATUS_UNAUTHORIZED>.
  41
  42 OCSP_response_get1_basic() decodes and returns the I<OCSP_BASICRESP> structure
  43 contained in I<resp>.
  44
  45 OCSP_response_create() creates and returns an I<OCSP_RESPONSE> structure for
  46 I<status> and optionally including basic response I<bs>.
  47
  48 OCSP_RESPONSE_free() frees up OCSP response I<resp>.
  49
  50 OCSP_RESPID_set_by_name() sets the name of the OCSP_RESPID to be the same as the
  51 subject name in the supplied X509 certificate I<cert> for the OCSP responder.
  52
  53 OCSP_RESPID_set_by_key_ex() sets the key of the OCSP_RESPID to be the same as the
  54 key in the supplied X509 certificate I<cert> for the OCSP responder. The key is
  55 stored as a SHA1 hash. To calculate the hash the SHA1 algorithm is fetched using
  56 the library ctx I<libctx> and the property query string I<propq> (see
  57 L<provider(7)/Fetching algorithms> for further information).
  58
  59 OCSP_RESPID_set_by_key() does the same as OCSP_RESPID_set_by_key_ex() except
  60 that the default library context is used with an empty property query string.
  61
  62 Note that an OCSP_RESPID can only have one of the name, or the key set. Calling
  63 OCSP_RESPID_set_by_name() or OCSP_RESPID_set_by_key() will clear any existing
  64 setting.
  65
  66 OCSP_RESPID_match_ex() tests whether the OCSP_RESPID given in I<respid> matches
  67 with the X509 certificate I<cert> based on the SHA1 hash. To calculate the hash
  68 the SHA1 algorithm is fetched using the library ctx I<libctx> and the property
  69 query string I<propq> (see L<provider(7)/Fetching algorithms> for further
  70 information).
  71
  72 OCSP_RESPID_match() does the same as OCSP_RESPID_match_ex() except that the
  73 default library context is used with an empty property query string.
  74
  75 OCSP_basic_sign() signs OCSP response I<brsp> using certificate I<signer>, private key
  76 I<key>, digest I<dgst> and additional certificates I<certs>. If the I<flags> option
  77 I<OCSP_NOCERTS> is set then no certificates will be included in the response. If the
  78 I<flags> option I<OCSP_RESPID_KEY> is set then the responder is identified by key ID
  79 rather than by name. OCSP_basic_sign_ctx() also signs OCSP response I<brsp> but
  80 uses the parameters contained in digest context I<ctx>.
  81
  82 =head1 RETURN VALUES
  83
  84 OCSP_RESPONSE_status() returns a status value.
  85
  86 OCSP_response_get1_basic() returns an I<OCSP_BASICRESP> structure pointer or
  87 I<NULL> if an error occurred.
  88
  89 OCSP_response_create() returns an I<OCSP_RESPONSE> structure pointer or I<NULL>
  90 if an error occurred.
  91
  92 OCSP_RESPONSE_free() does not return a value.
  93
  94 OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key(), OCSP_basic_sign(), and
  95 OCSP_basic_sign_ctx() return 1 on success or 0
  96 on failure.
  97
  98 OCSP_RESPID_match() returns 1 if the OCSP_RESPID and the X509 certificate match
  99 or 0 otherwise.
 100
 101 =head1 NOTES
 102
 103 OCSP_response_get1_basic() is only called if the status of a response is
 104 I<OCSP_RESPONSE_STATUS_SUCCESSFUL>.
 105
 106 =head1 SEE ALSO
 107
 108 L<crypto(7)>
 109 L<OCSP_cert_to_id(3)>
 110 L<OCSP_request_add1_nonce(3)>
 111 L<OCSP_REQUEST_new(3)>
 112 L<OCSP_resp_find_status(3)>
 113 L<OCSP_sendreq_new(3)>
 114 L<OCSP_RESPID_new(3)>
 115 L<OCSP_RESPID_free(3)>
 116
 117 =head1 HISTORY
 118
 119 The OCSP_RESPID_set_by_name(), OCSP_RESPID_set_by_key() and OCSP_RESPID_match()
 120 functions were added in OpenSSL 1.1.0a.
 121
 122 The OCSP_basic_sign_ctx() function was added in OpenSSL 1.1.1.
 123
 124 =head1 COPYRIGHT
 125
 126 Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
 127
 128 Licensed under the Apache License 2.0 (the "License").  You may not use
 129 this file except in compliance with the License.  You can obtain a copy
 130 in the file LICENSE in the source distribution or at
 131 L<https://www.openssl.org/source/license.html>.
 132
 133 =cut