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-2022 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
25 /**
26 * @file Control Channel Verification Module
27 */
28
29 #ifndef SSL_VERIFY_H_
30 #define SSL_VERIFY_H_
31
32 #include "syshead.h"
33 #include "misc.h"
34 #include "ssl_common.h"
35
36 /* Include OpenSSL-specific code */
37 #ifdef ENABLE_CRYPTO_OPENSSL
38 #include "ssl_verify_openssl.h"
39 #endif
40 #ifdef ENABLE_CRYPTO_MBEDTLS
41 #include "ssl_verify_mbedtls.h"
42 #endif
43
44 #include "ssl_verify_backend.h"
45
46 /*
47 * Keep track of certificate hashes at various depths
48 */
49
50 /** Maximum certificate depth we will allow */
51 #define MAX_CERT_DEPTH 16
52
53 /** Structure containing the hash for a single certificate */
54 struct cert_hash {
55 unsigned char sha256_hash[256/8];
56 };
57
58 /** Structure containing the hashes for a full certificate chain */
59 struct cert_hash_set {
60 struct cert_hash *ch[MAX_CERT_DEPTH]; /**< Array of certificate hashes */
61 };
62
63 #define VERIFY_X509_NONE 0
64 #define VERIFY_X509_SUBJECT_DN 1
65 #define VERIFY_X509_SUBJECT_RDN 2
66 #define VERIFY_X509_SUBJECT_RDN_PREFIX 3
67
68 #define TLS_AUTHENTICATION_SUCCEEDED 0
69 #define TLS_AUTHENTICATION_FAILED 1
70 #define TLS_AUTHENTICATION_DEFERRED 2
71 #define TLS_AUTHENTICATION_UNDEFINED 3
72
73 /*
74 * Return current session authentication state. Return
75 * value is TLS_AUTHENTICATION_x.
76 *
77 * TODO: document this function
78 */
79 int tls_authentication_status(struct tls_multi *multi, const int latency);
80
81 /** Check whether the \a ks \c key_state is ready to receive data channel
82 * packets.
83 * @ingroup data_crypto
84 *
85 * If true, it is safe to assume that this session has been authenticated
86 * by TLS.
87 *
88 * @note This macro only works if S_SENT_KEY + 1 == S_GOT_KEY. */
89 #define DECRYPT_KEY_ENABLED(multi, ks) ((ks)->state >= (S_GOT_KEY - (multi)->opt.server))
90
91 /**
92 * Remove the given key state's auth control file, if it exists.
93 *
94 * @param ks The key state the remove the file for
95 */
96 void key_state_rm_auth_control_file(struct key_state *ks);
97
98 /**
99 * Frees the given set of certificate hashes.
100 *
101 * @param chs The certificate hash set to free.
102 */
103 void cert_hash_free(struct cert_hash_set *chs);
104
105 /**
106 * Locks the certificate hash set used in the given tunnel
107 *
108 * @param multi The tunnel to lock
109 */
110 void tls_lock_cert_hash_set(struct tls_multi *multi);
111
112 /**
113 * Locks the common name field for the given tunnel
114 *
115 * @param multi The tunnel to lock
116 */
117 void tls_lock_common_name(struct tls_multi *multi);
118
119 /**
120 * Returns the common name field for the given tunnel
121 *
122 * @param multi The tunnel to return the common name for
123 * @param null Whether null may be returned. If not, "UNDEF" will be returned.
124 */
125 const char *tls_common_name(const struct tls_multi *multi, const bool null);
126
127 /**
128 * Returns the username field for the given tunnel
129 *
130 * @param multi The tunnel to return the username for
131 * @param null Whether null may be returned. If not, "UNDEF" will be returned.
132 */
133 const char *tls_username(const struct tls_multi *multi, const bool null);
134
135 /**
136 * Compares certificates hashes, returns true if hashes are equal.
137 *
138 * @param chs1 cert 1 hash set
139 * @param chs2 cert 2 hash set
140 */
141 bool cert_hash_compare(const struct cert_hash_set *chs1, const struct cert_hash_set *chs2);
142
143 #ifdef ENABLE_PF
144
145 /**
146 * Retrieve the given tunnel's common name and its hash value.
147 *
148 * @param multi The tunnel to use
149 * @param cn Common name's string
150 * @param cn_hash Common name's hash value
151 *
152 * @return true if the common name was set, false otherwise.
153 */
154 static inline bool
tls_common_name_hash(const struct tls_multi * multi,const char ** cn,uint32_t * cn_hash)155 tls_common_name_hash(const struct tls_multi *multi, const char **cn, uint32_t *cn_hash)
156 {
157 if (multi)
158 {
159 const struct tls_session *s = &multi->session[TM_ACTIVE];
160 if (s->common_name && s->common_name[0] != '\0')
161 {
162 *cn = s->common_name;
163 *cn_hash = s->common_name_hashval;
164 return true;
165 }
166 }
167 return false;
168 }
169
170 #endif
171
172 /**
173 * Verify the given username and password, using either an external script, a
174 * plugin, or the management interface.
175 *
176 * If authentication succeeds, the appropriate state is filled into the
177 * session's primary key state's authenticated field. Authentication may also
178 * be deferred, in which case the key state's auth_deferred field is filled in.
179 *
180 * @param up The username and password to verify.
181 * @param multi The TLS multi structure to verify usernames against.
182 * @param session The current TLS session
183 *
184 */
185 void verify_user_pass(struct user_pass *up, struct tls_multi *multi,
186 struct tls_session *session);
187
188 /**
189 * Perform final authentication checks, including locking of the cn, the allowed
190 * certificate hashes, and whether a client config entry exists in the
191 * client config directory.
192 *
193 * @param multi The TLS multi structure to verify locked structures.
194 * @param session The current TLS session
195 *
196 */
197 void verify_final_auth_checks(struct tls_multi *multi, struct tls_session *session);
198
199 struct x509_track
200 {
201 const struct x509_track *next;
202 const char *name;
203 #define XT_FULL_CHAIN (1<<0)
204 unsigned int flags;
205 int nid;
206 };
207
208 /*
209 * Certificate checking for verify_nsCertType
210 */
211 /** Do not perform Netscape certificate type verification */
212 #define NS_CERT_CHECK_NONE (0)
213 /** Do not perform Netscape certificate type verification */
214 #define NS_CERT_CHECK_SERVER (1<<0)
215 /** Do not perform Netscape certificate type verification */
216 #define NS_CERT_CHECK_CLIENT (1<<1)
217
218 /** Require keyUsage to be present in cert (0xFFFF is an invalid KU value) */
219 #define OPENVPN_KU_REQUIRED (0xFFFF)
220
221 /*
222 * TODO: document
223 */
224 #ifdef MANAGEMENT_DEF_AUTH
225 bool tls_authenticate_key(struct tls_multi *multi, const unsigned int mda_key_id, const bool auth, const char *client_reason);
226
227 #endif
228
229 /**
230 * Sets the reason why authentication of a client failed. This be will send to the client
231 * when the AUTH_FAILED message is sent
232 * An example would be "SESSION: Token expired"
233 * @param multi The multi tls struct
234 * @param client_reason The string to send to the client as part of AUTH_FAILED
235 */
236 void auth_set_client_reason(struct tls_multi *multi, const char *client_reason);
237
238 static inline const char *
tls_client_reason(struct tls_multi * multi)239 tls_client_reason(struct tls_multi *multi)
240 {
241 return multi->client_reason;
242 }
243
244 /** Remove any X509_ env variables from env_set es */
245 void tls_x509_clear_env(struct env_set *es);
246
247 #endif /* SSL_VERIFY_H_ */
248