OpenVPN
ssl_verify_backend.h
Go to the documentation of this file.
1/*
2 * OpenVPN -- An application to securely tunnel IP networks
3 * over a single TCP/UDP port, with support for SSL/TLS-based
4 * session authentication and key exchange,
5 * packet encryption, packet authentication, and
6 * packet compression.
7 *
8 * Copyright (C) 2002-2025 OpenVPN Inc <sales@openvpn.net>
9 * Copyright (C) 2010-2021 Fox Crypto B.V. <openvpn@foxcrypto.com>
10 *
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License version 2
13 * as published by the Free Software Foundation.
14 *
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU General Public License for more details.
19 *
20 * You should have received a copy of the GNU General Public License along
21 * with this program; if not, see <https://www.gnu.org/licenses/>.
22 */
23
29#ifndef SSL_VERIFY_BACKEND_H_
30#define SSL_VERIFY_BACKEND_H_
31
35typedef enum
36{
38 FAILURE = 1
40
41/*
42 * Backend support functions.
43 *
44 * The following functions are needed by the backend, but defined in the main
45 * file.
46 */
47
48/*
49 * Verify certificate for the given session. Performs OpenVPN-specific
50 * verification.
51 *
52 * This function must be called for every certificate in the certificate
53 * chain during the certificate verification stage of the handshake.
54 *
55 * @param session TLS Session associated with this tunnel
56 * @param cert Certificate to process
57 * @param cert_depth Depth of the current certificate
58 *
59 * @return \c SUCCESS if verification was successful, \c FAILURE on failure.
60 */
61result_t verify_cert(struct tls_session *session, openvpn_x509_cert_t *cert, int cert_depth);
62
63/*
64 * Remember the given certificate hash, allowing the certificate chain to be
65 * locked between sessions.
66 *
67 * Must be called for every certificate in the verification chain, whether it
68 * is valid or not.
69 *
70 * @param session TLS Session associated with this tunnel
71 * @param cert_depth Depth of the current certificate
72 * @param cert_hash Hash of the current certificate
73 */
74void cert_hash_remember(struct tls_session *session, const int cert_depth,
75 const struct buffer *cert_hash);
76
77/*
78 * Library-specific functions.
79 *
80 * The following functions must be implemented on a library-specific basis.
81 */
82
83/*
84 * Retrieve certificate's subject name.
85 *
86 * @param cert Certificate to retrieve the subject from.
87 * @param gc Garbage collection arena to use when allocating string.
88 *
89 * @return a string containing the subject
90 */
92
102
112
113/*
114 * Retrieve the certificate's username from the specified field.
115 *
116 * If the field is prepended with ext: and ENABLE_X509ALTUSERNAME is enabled,
117 * it will be loaded from an X.509 extension
118 *
119 * @param cn Buffer to return the common name in.
120 * @param cn_len Length of the cn buffer.
121 * @param x509_username_field Name of the field to load from
122 * @param cert Certificate to retrieve the common name from.
123 *
124 * @return \c FAILURE, \c or SUCCESS
125 */
126result_t backend_x509_get_username(char *common_name, int cn_len, char *x509_username_field,
127 openvpn_x509_cert_t *peer_cert);
128
129#ifdef ENABLE_X509ALTUSERNAME
134bool x509_username_field_ext_supported(const char *extname);
135
136#endif
137
138/*
139 * Return the certificate's serial number in decimal string representation.
140 *
141 * The serial number is returned as a string, since it might be a bignum.
142 *
143 * @param cert Certificate to retrieve the serial number from.
144 * @param gc Garbage collection arena to use when allocating string.
145 *
146 * @return String representation of the certificate's serial number
147 * in decimal notation, or NULL on error.
148 */
150
151/*
152 * Return the certificate's serial number in hex string representation.
153 *
154 * The serial number is returned as a string, since it might be a bignum.
155 *
156 * @param cert Certificate to retrieve the serial number from.
157 * @param gc Garbage collection arena to use when allocating string.
158 *
159 * @return String representation of the certificate's serial number
160 * in hex notation, or NULL on error.
161 */
163
164/*
165 * Write the certificate to the file in PEM format.
166 *
167 *
168 * @param cert Certificate to serialise.
169 *
170 * @return \c FAILURE, \c or SUCCESS
171 */
172result_t backend_x509_write_pem(openvpn_x509_cert_t *cert, const char *filename);
173
174/*
175 * Save X509 fields to environment, using the naming convention:
176 *
177 * X509_{cert_depth}_{name}={value}
178 *
179 * @param es Environment set to save variables in
180 * @param cert_depth Depth of the certificate
181 * @param cert Certificate to set the environment for
182 */
183void x509_setenv(struct env_set *es, int cert_depth, openvpn_x509_cert_t *cert);
184
185/*
186 * Start tracking the given attribute.
187 *
188 * The tracked attributes are stored in ll_head.
189 *
190 * @param ll_head The x509_track to store tracked attributes in
191 * @param name Name of the attribute to track
192 * @param msglevel Message level for errors
193 * @param gc Garbage collection arena for temp data
194 *
195 */
196void x509_track_add(const struct x509_track **ll_head, const char *name, int msglevel,
197 struct gc_arena *gc);
198
199/*
200 * Save X509 fields to environment, using the naming convention:
201 *
202 * X509_{cert_depth}_{name}={value}
203 *
204 * This function differs from setenv_x509 below in the following ways:
205 *
206 * (1) Only explicitly named attributes in xt are saved, per usage
207 * of --x509-track program options.
208 * (2) Only the level 0 cert info is saved unless the XT_FULL_CHAIN
209 * flag is set in xt->flags (corresponds with prepending a '+'
210 * to the name when specified by --x509-track program option).
211 * (3) This function supports both X509 subject name fields as
212 * well as X509 V3 extensions.
213 *
214 * @param xt
215 * @param es Environment set to save variables in
216 * @param cert_depth Depth of the certificate
217 * @param cert Certificate to set the environment for
218 */
219void x509_setenv_track(const struct x509_track *xt, struct env_set *es, const int depth,
220 openvpn_x509_cert_t *x509);
221
222/*
223 * Check X.509 Netscape certificate type field, if available.
224 *
225 * @param cert Certificate to check.
226 * @param usage One of \c NS_CERT_CHECK_CLIENT, \c NS_CERT_CHECK_SERVER,
227 * or \c NS_CERT_CHECK_NONE.
228 *
229 * @return \c SUCCESS if NS_CERT_CHECK_NONE or if the certificate has
230 * the expected bit set. \c FAILURE if the certificate does
231 * not have NS cert type verification or the wrong bit set.
232 */
234
235/*
236 * Verify X.509 key usage extension field.
237 *
238 * @param cert Certificate to check.
239 * @param expected_ku Array of valid key usage values
240 * @param expected_len Length of the key usage array
241 *
242 * @return \c SUCCESS if one of the key usage values matches, \c FAILURE
243 * if key usage is not enabled, or the values do not match.
244 */
245result_t x509_verify_cert_ku(openvpn_x509_cert_t *x509, const unsigned *const expected_ku,
246 int expected_len);
247
248/*
249 * Verify X.509 extended key usage extension field.
250 *
251 * @param cert Certificate to check.
252 * @param expected_oid String representation of the expected Object ID. May be
253 * either the string representation of the numeric OID
254 * (e.g. \c "1.2.3.4", or the descriptive string matching
255 * the OID.
256 *
257 * @return \c SUCCESS if one of the expected OID matches one of the
258 * extended key usage fields, \c FAILURE if extended key
259 * usage is not enabled, or the values do not match.
260 */
261result_t x509_verify_cert_eku(openvpn_x509_cert_t *x509, const char *const expected_oid);
262
269bool tls_verify_crl_missing(const struct tls_options *opt);
270
271#endif /* SSL_VERIFY_BACKEND_H_ */
static void usage(void)
Definition options.c:4833
struct buffer x509_get_sha256_fingerprint(openvpn_x509_cert_t *cert, struct gc_arena *gc)
Retrieve the certificate's SHA256 fingerprint.
void cert_hash_remember(struct tls_session *session, const int cert_depth, const struct buffer *cert_hash)
Definition ssl_verify.c:194
void x509_setenv_track(const struct x509_track *xt, struct env_set *es, const int depth, openvpn_x509_cert_t *x509)
void x509_setenv(struct env_set *es, int cert_depth, openvpn_x509_cert_t *cert)
bool tls_verify_crl_missing(const struct tls_options *opt)
Return true iff a CRL is configured, but is not loaded.
result_t backend_x509_write_pem(openvpn_x509_cert_t *cert, const char *filename)
result_t x509_verify_ns_cert_type(openvpn_x509_cert_t *cert, const int usage)
result_t backend_x509_get_username(char *common_name, int cn_len, char *x509_username_field, openvpn_x509_cert_t *peer_cert)
char * backend_x509_get_serial_hex(openvpn_x509_cert_t *cert, struct gc_arena *gc)
result_t verify_cert(struct tls_session *session, openvpn_x509_cert_t *cert, int cert_depth)
Definition ssl_verify.c:577
result_t x509_verify_cert_ku(openvpn_x509_cert_t *x509, const unsigned *const expected_ku, int expected_len)
struct buffer x509_get_sha1_fingerprint(openvpn_x509_cert_t *cert, struct gc_arena *gc)
Retrieve the certificate's SHA1 fingerprint.
char * x509_get_subject(openvpn_x509_cert_t *cert, struct gc_arena *gc)
Definition test_pkcs11.c:68
char * backend_x509_get_serial(openvpn_x509_cert_t *cert, struct gc_arena *gc)
void x509_track_add(const struct x509_track **ll_head, const char *name, int msglevel, struct gc_arena *gc)
result_t
Result of verification function.
@ FAILURE
@ SUCCESS
result_t x509_verify_cert_eku(openvpn_x509_cert_t *x509, const char *const expected_oid)
mbedtls_x509_crt openvpn_x509_cert_t
Wrapper structure for dynamically allocated memory.
Definition buffer.h:60
Structure containing the hash for a single certificate.
Definition ssl_verify.h:58
Garbage collection arena used to keep track of dynamically allocated memory.
Definition buffer.h:116
Security parameter state of a single session within a VPN tunnel.
Definition ssl_common.h:490
struct env_set * es
struct gc_arena gc
Definition test_ssl.c:154