Debian Codegraph @

upstream/debian-unstable/man3/OCSP_response_status.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OCSP_RESPONSE_STATUS 3SSL"
58 .TH OCSP_RESPONSE_STATUS 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OCSP_response_status, OCSP_response_get1_basic, OCSP_response_create,
65 OCSP_RESPONSE_free, OCSP_RESPID_set_by_name,
66 OCSP_RESPID_set_by_key_ex, OCSP_RESPID_set_by_key, OCSP_RESPID_match_ex,
67 OCSP_RESPID_match, OCSP_basic_sign, OCSP_basic_sign_ctx
68 \&\- OCSP response functions
69 .SH SYNOPSIS
70 .IX Header "SYNOPSIS"
71 .Vb 1
72 \& #include <openssl/ocsp.h>
73 \&
74 \& int OCSP_response_status(OCSP_RESPONSE *resp);
75 \& OCSP_BASICRESP *OCSP_response_get1_basic(OCSP_RESPONSE *resp);
76 \& OCSP_RESPONSE *OCSP_response_create(int status, OCSP_BASICRESP *bs);
77 \& void OCSP_RESPONSE_free(OCSP_RESPONSE *resp);
78 \&
79 \& int OCSP_RESPID_set_by_name(OCSP_RESPID *respid, X509 *cert);
80 \& int OCSP_RESPID_set_by_key_ex(OCSP_RESPID *respid, X509 *cert,
81 \& OSSL_LIB_CTX *libctx, const char *propq);
82 \& int OCSP_RESPID_set_by_key(OCSP_RESPID *respid, X509 *cert);
83 \& int OCSP_RESPID_match_ex(OCSP_RESPID *respid, X509 *cert, OSSL_LIB_CTX *libctx,
84 \& const char *propq);
85 \& int OCSP_RESPID_match(OCSP_RESPID *respid, X509 *cert);
86 \&
87 \& int OCSP_basic_sign(OCSP_BASICRESP *brsp, X509 *signer, EVP_PKEY *key,
88 \& const EVP_MD *dgst, STACK_OF(X509) *certs,
89 \& unsigned long flags);
90 \& int OCSP_basic_sign_ctx(OCSP_BASICRESP *brsp, X509 *signer, EVP_MD_CTX *ctx,
91 \& STACK_OF(X509) *certs, unsigned long flags);
92 .Ve
93 .SH DESCRIPTION
94 .IX Header "DESCRIPTION"
95 \&\fBOCSP_response_status()\fR returns the OCSP response status of \fIresp\fR. It returns
96 one of the values: \fIOCSP_RESPONSE_STATUS_SUCCESSFUL\fR,
97 \&\fIOCSP_RESPONSE_STATUS_MALFORMEDREQUEST\fR,
98 \&\fIOCSP_RESPONSE_STATUS_INTERNALERROR\fR, \fIOCSP_RESPONSE_STATUS_TRYLATER\fR
99 \&\fIOCSP_RESPONSE_STATUS_SIGREQUIRED\fR, or \fIOCSP_RESPONSE_STATUS_UNAUTHORIZED\fR.
100 .PP
101 \&\fBOCSP_response_get1_basic()\fR decodes and returns the \fIOCSP_BASICRESP\fR structure
102 contained in \fIresp\fR.
103 .PP
104 \&\fBOCSP_response_create()\fR creates and returns an \fIOCSP_RESPONSE\fR structure for
105 \&\fIstatus\fR and optionally including basic response \fIbs\fR.
106 .PP
107 \&\fBOCSP_RESPONSE_free()\fR frees up OCSP response \fIresp\fR.
108 If the argument is NULL, nothing is done.
109 .PP
110 \&\fBOCSP_RESPID_set_by_name()\fR sets the name of the OCSP_RESPID to be the same as the
111 subject name in the supplied X509 certificate \fIcert\fR for the OCSP responder.
112 .PP
113 \&\fBOCSP_RESPID_set_by_key_ex()\fR sets the key of the OCSP_RESPID to be the same as the
114 key in the supplied X509 certificate \fIcert\fR for the OCSP responder. The key is
115 stored as a SHA1 hash. To calculate the hash the SHA1 algorithm is fetched using
116 the library ctx \fIlibctx\fR and the property query string \fIpropq\fR (see
117 "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further information).
118 .PP
119 \&\fBOCSP_RESPID_set_by_key()\fR does the same as \fBOCSP_RESPID_set_by_key_ex()\fR except
120 that the default library context is used with an empty property query string.
121 .PP
122 Note that an OCSP_RESPID can only have one of the name, or the key set. Calling
123 \&\fBOCSP_RESPID_set_by_name()\fR or \fBOCSP_RESPID_set_by_key()\fR will clear any existing
124 setting.
125 .PP
126 \&\fBOCSP_RESPID_match_ex()\fR tests whether the OCSP_RESPID given in \fIrespid\fR matches
127 with the X509 certificate \fIcert\fR based on the SHA1 hash. To calculate the hash
128 the SHA1 algorithm is fetched using the library ctx \fIlibctx\fR and the property
129 query string \fIpropq\fR (see "ALGORITHM FETCHING" in \fBcrypto\fR\|(7) for further
130 information).
131 .PP
132 \&\fBOCSP_RESPID_match()\fR does the same as \fBOCSP_RESPID_match_ex()\fR except that the
133 default library context is used with an empty property query string.
134 .PP
135 \&\fBOCSP_basic_sign()\fR signs OCSP response \fIbrsp\fR using certificate \fIsigner\fR, private key
136 \&\fIkey\fR, digest \fIdgst\fR and additional certificates \fIcerts\fR. If the \fIflags\fR option
137 \&\fIOCSP_NOCERTS\fR is set then no certificates will be included in the response. If the
138 \&\fIflags\fR option \fIOCSP_RESPID_KEY\fR is set then the responder is identified by key ID
139 rather than by name. \fBOCSP_basic_sign_ctx()\fR also signs OCSP response \fIbrsp\fR but
140 uses the parameters contained in digest context \fIctx\fR.
141 .SH "RETURN VALUES"
142 .IX Header "RETURN VALUES"
143 \&\fBOCSP_RESPONSE_status()\fR returns a status value.
144 .PP
145 \&\fBOCSP_response_get1_basic()\fR returns an \fIOCSP_BASICRESP\fR structure pointer or
146 \&\fINULL\fR if an error occurred.
147 .PP
148 \&\fBOCSP_response_create()\fR returns an \fIOCSP_RESPONSE\fR structure pointer or \fINULL\fR
149 if an error occurred.
150 .PP
151 \&\fBOCSP_RESPONSE_free()\fR does not return a value.
152 .PP
153 \&\fBOCSP_RESPID_set_by_name()\fR, \fBOCSP_RESPID_set_by_key()\fR, \fBOCSP_basic_sign()\fR, and
154 \&\fBOCSP_basic_sign_ctx()\fR return 1 on success or 0
155 on failure.
156 .PP
157 \&\fBOCSP_RESPID_match()\fR returns 1 if the OCSP_RESPID and the X509 certificate match
158 or 0 otherwise.
159 .SH NOTES
160 .IX Header "NOTES"
161 \&\fBOCSP_response_get1_basic()\fR is only called if the status of a response is
162 \&\fIOCSP_RESPONSE_STATUS_SUCCESSFUL\fR.
163 .SH "SEE ALSO"
164 .IX Header "SEE ALSO"
165 \&\fBcrypto\fR\|(7)
166 \&\fBOCSP_cert_to_id\fR\|(3)
167 \&\fBOCSP_request_add1_nonce\fR\|(3)
168 \&\fBOCSP_REQUEST_new\fR\|(3)
169 \&\fBOCSP_resp_find_status\fR\|(3)
170 \&\fBOCSP_sendreq_new\fR\|(3)
171 \&\fBOCSP_RESPID_new\fR\|(3)
172 \&\fBOCSP_RESPID_free\fR\|(3)
173 .SH HISTORY
174 .IX Header "HISTORY"
175 The \fBOCSP_RESPID_set_by_name()\fR, \fBOCSP_RESPID_set_by_key()\fR and \fBOCSP_RESPID_match()\fR
176 functions were added in OpenSSL 1.1.0a.
177 .PP
178 The \fBOCSP_basic_sign_ctx()\fR function was added in OpenSSL 1.1.1.
179 .SH COPYRIGHT
180 .IX Header "COPYRIGHT"
181 Copyright 2015\-2024 The OpenSSL Project Authors. All Rights Reserved.
182 .PP
183 Licensed under the Apache License 2.0 (the "License"). You may not use
184 this file except in compliance with the License. You can obtain a copy
185 in the file LICENSE in the source distribution or at
186 <https://www.openssl.org/source/license.html>.