OCSP_response_status.pod 5.1 KB

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