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-2024 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, write to the Free Software Foundation, Inc.,
22  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
23  */
24 
29 #ifndef SSL_VERIFY_BACKEND_H_
30 #define SSL_VERIFY_BACKEND_H_
31 
35 typedef enum { SUCCESS = 0, FAILURE = 1 } result_t;
36 
37 /*
38  * Backend support functions.
39  *
40  * The following functions are needed by the backend, but defined in the main
41  * file.
42  */
43 
44 /*
45  * Verify certificate for the given session. Performs OpenVPN-specific
46  * verification.
47  *
48  * This function must be called for every certificate in the certificate
49  * chain during the certificate verification stage of the handshake.
50  *
51  * @param session TLS Session associated with this tunnel
52  * @param cert Certificate to process
53  * @param cert_depth Depth of the current certificate
54  *
55  * @return \c SUCCESS if verification was successful, \c FAILURE on failure.
56  */
57 result_t verify_cert(struct tls_session *session, openvpn_x509_cert_t *cert, int cert_depth);
58 
59 /*
60  * Remember the given certificate hash, allowing the certificate chain to be
61  * locked between sessions.
62  *
63  * Must be called for every certificate in the verification chain, whether it
64  * is valid or not.
65  *
66  * @param session TLS Session associated with this tunnel
67  * @param cert_depth Depth of the current certificate
68  * @param cert_hash Hash of the current certificate
69  */
70 void cert_hash_remember(struct tls_session *session, const int cert_depth,
71  const struct buffer *cert_hash);
72 
73 /*
74  * Library-specific functions.
75  *
76  * The following functions must be implemented on a library-specific basis.
77  */
78 
79 /*
80  * Retrieve certificate's subject name.
81  *
82  * @param cert Certificate to retrieve the subject from.
83  * @param gc Garbage collection arena to use when allocating string.
84  *
85  * @return a string containing the subject
86  */
87 char *x509_get_subject(openvpn_x509_cert_t *cert, struct gc_arena *gc);
88 
98  struct gc_arena *gc);
99 
109  struct gc_arena *gc);
110 
111 /*
112  * Retrieve the certificate's username from the specified field.
113  *
114  * If the field is prepended with ext: and ENABLE_X509ALTUSERNAME is enabled,
115  * it will be loaded from an X.509 extension
116  *
117  * @param cn Buffer to return the common name in.
118  * @param cn_len Length of the cn buffer.
119  * @param x509_username_field Name of the field to load from
120  * @param cert Certificate to retrieve the common name from.
121  *
122  * @return \c FAILURE, \c or SUCCESS
123  */
124 result_t backend_x509_get_username(char *common_name, int cn_len,
125  char *x509_username_field, openvpn_x509_cert_t *peer_cert);
126 
127 #ifdef ENABLE_X509ALTUSERNAME
128 
132 bool x509_username_field_ext_supported(const char *extname);
133 
134 #endif
135 
136 /*
137  * Return the certificate's serial number in decimal string representation.
138  *
139  * The serial number is returned as a string, since it might be a bignum.
140  *
141  * @param cert Certificate to retrieve the serial number from.
142  * @param gc Garbage collection arena to use when allocating string.
143  *
144  * @return String representation of the certificate's serial number
145  * in decimal notation, or NULL on error.
146  */
147 char *backend_x509_get_serial(openvpn_x509_cert_t *cert, struct gc_arena *gc);
148 
149 /*
150  * Return the certificate's serial number in hex string representation.
151  *
152  * The serial number is returned as a string, since it might be a bignum.
153  *
154  * @param cert Certificate to retrieve the serial number from.
155  * @param gc Garbage collection arena to use when allocating string.
156  *
157  * @return String representation of the certificate's serial number
158  * in hex notation, or NULL on error.
159  */
161  struct gc_arena *gc);
162 
163 /*
164  * Write the certificate to the file in PEM format.
165  *
166  *
167  * @param cert Certificate to serialise.
168  *
169  * @return \c FAILURE, \c or SUCCESS
170  */
172  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  */
183 void 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  */
196 void x509_track_add(const struct x509_track **ll_head, const char *name,
197  int msglevel, 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  */
219 void x509_setenv_track(const struct x509_track *xt, struct env_set *es,
220  const int depth, 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  */
245 result_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  */
261 result_t x509_verify_cert_eku(openvpn_x509_cert_t *x509, const char *const expected_oid);
262 
269 bool tls_verify_crl_missing(const struct tls_options *opt);
270 
271 #endif /* SSL_VERIFY_BACKEND_H_ */
cert_hash_remember
void cert_hash_remember(struct tls_session *session, const int cert_depth, const struct buffer *cert_hash)
Definition: ssl_verify.c:199
x509_verify_cert_eku
result_t x509_verify_cert_eku(openvpn_x509_cert_t *x509, const char *const expected_oid)
Definition: ssl_verify_openssl.c:739
x509_get_sha256_fingerprint
struct buffer x509_get_sha256_fingerprint(openvpn_x509_cert_t *cert, struct gc_arena *gc)
Retrieve the certificate's SHA256 fingerprint.
Definition: ssl_verify_openssl.c:357
verify_cert
result_t verify_cert(struct tls_session *session, openvpn_x509_cert_t *cert, int cert_depth)
Definition: ssl_verify.c:598
es
struct env_set * es
Definition: test_pkcs11.c:133
backend_x509_get_username
result_t backend_x509_get_username(char *common_name, int cn_len, char *x509_username_field, openvpn_x509_cert_t *peer_cert)
Definition: ssl_verify_openssl.c:259
x509_setenv_track
void x509_setenv_track(const struct x509_track *xt, struct env_set *es, const int depth, openvpn_x509_cert_t *x509)
Definition: ssl_verify_openssl.c:463
result_t
result_t
Result of verification function.
Definition: ssl_verify_backend.h:35
backend_x509_get_serial
char * backend_x509_get_serial(openvpn_x509_cert_t *cert, struct gc_arena *gc)
Definition: ssl_verify_openssl.c:297
tls_verify_crl_missing
bool tls_verify_crl_missing(const struct tls_options *opt)
Return true iff a CRL is configured, but is not loaded.
Definition: ssl_verify_openssl.c:789
backend_x509_write_pem
result_t backend_x509_write_pem(openvpn_x509_cert_t *cert, const char *filename)
Definition: ssl_verify_openssl.c:324
x509_verify_cert_ku
result_t x509_verify_cert_ku(openvpn_x509_cert_t *x509, const unsigned *const expected_ku, int expected_len)
Definition: ssl_verify_openssl.c:678
tls_options
Definition: ssl_common.h:296
x509_get_sha1_fingerprint
struct buffer x509_get_sha1_fingerprint(openvpn_x509_cert_t *cert, struct gc_arena *gc)
Retrieve the certificate's SHA1 fingerprint.
Definition: ssl_verify_openssl.c:347
buffer
Wrapper structure for dynamically allocated memory.
Definition: buffer.h:60
x509_setenv
void x509_setenv(struct env_set *es, int cert_depth, openvpn_x509_cert_t *cert)
Definition: ssl_verify_openssl.c:552
SUCCESS
@ SUCCESS
Definition: ssl_verify_backend.h:35
tls_session
Security parameter state of a single session within a VPN tunnel.
Definition: ssl_common.h:471
gc_arena
Garbage collection arena used to keep track of dynamically allocated memory.
Definition: buffer.h:116
env_set
Definition: env_set.h:42
openvpn_x509_cert_t
X509 openvpn_x509_cert_t
Definition: openvpn-plugin.h:40
usage
static void usage(void)
Definition: options.c:4817
x509_verify_ns_cert_type
result_t x509_verify_ns_cert_type(openvpn_x509_cert_t *cert, const int usage)
Definition: ssl_verify_openssl.c:611
cert_hash
Structure containing the hash for a single certificate.
Definition: ssl_verify.h:54
x509_get_subject
char * x509_get_subject(openvpn_x509_cert_t *cert, struct gc_arena *gc)
Definition: ssl_verify_openssl.c:367
session
Definition: keyingmaterialexporter.c:56
x509_track_add
void x509_track_add(const struct x509_track **ll_head, const char *name, int msglevel, struct gc_arena *gc)
Definition: ssl_verify_openssl.c:423
backend_x509_get_serial_hex
char * backend_x509_get_serial_hex(openvpn_x509_cert_t *cert, struct gc_arena *gc)
Definition: ssl_verify_openssl.c:316
x509_track
Definition: ssl_verify.h:214
FAILURE
@ FAILURE
Definition: ssl_verify_backend.h:35