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