summaryrefslogtreecommitdiff
path: root/src/openvpn/ssl_verify_backend.h
blob: e8eaabe9e584182d2849604591ec936d7720e9fb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
/*
 *  OpenVPN -- An application to securely tunnel IP networks
 *             over a single TCP/UDP port, with support for SSL/TLS-based
 *             session authentication and key exchange,
 *             packet encryption, packet authentication, and
 *             packet compression.
 *
 *  Copyright (C) 2002-2017 OpenVPN Technologies, Inc. <sales@openvpn.net>
 *  Copyright (C) 2010-2017 Fox Crypto B.V. <openvpn@fox-it.com>
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License version 2
 *  as published by the Free Software Foundation.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along
 *  with this program; if not, write to the Free Software Foundation, Inc.,
 *  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

/**
 * @file Control Channel Verification Module library-specific backend interface
 */

#ifndef SSL_VERIFY_BACKEND_H_
#define SSL_VERIFY_BACKEND_H_

/**
 * Result of verification function
 */
typedef enum { SUCCESS = 0, FAILURE = 1 } result_t;

/*
 * Backend support functions.
 *
 * The following functions are needed by the backend, but defined in the main
 * file.
 */

/*
 * Verify certificate for the given session. Performs OpenVPN-specific
 * verification.
 *
 * This function must be called for every certificate in the certificate
 * chain during the certificate verification stage of the handshake.
 *
 * @param session       TLS Session associated with this tunnel
 * @param cert          Certificate to process
 * @param cert_depth    Depth of the current certificate
 *
 * @return              \c SUCCESS if verification was successful, \c FAILURE on failure.
 */
result_t verify_cert(struct tls_session *session, openvpn_x509_cert_t *cert, int cert_depth);

/*
 * Remember the given certificate hash, allowing the certificate chain to be
 * locked between sessions.
 *
 * Must be called for every certificate in the verification chain, whether it
 * is valid or not.
 *
 * @param session       TLS Session associated with this tunnel
 * @param cert_depth    Depth of the current certificate
 * @param cert_hash     Hash of the current certificate
 */
void cert_hash_remember(struct tls_session *session, const int cert_depth,
                        const struct buffer *cert_hash);

/*
 * Library-specific functions.
 *
 * The following functions must be implemented on a library-specific basis.
 */

/*
 * Retrieve certificate's subject name.
 *
 * @param cert          Certificate to retrieve the subject from.
 * @param gc            Garbage collection arena to use when allocating string.
 *
 * @return              a string containing the subject
 */
char *x509_get_subject(openvpn_x509_cert_t *cert, struct gc_arena *gc);

/**
 * Retrieve the certificate's SHA1 fingerprint.
 *
 * @param cert          Certificate to retrieve the fingerprint from.
 * @param gc            Garbage collection arena to use when allocating string.
 *
 * @return              a string containing the certificate fingerprint
 */
struct buffer x509_get_sha1_fingerprint(openvpn_x509_cert_t *cert,
                                        struct gc_arena *gc);

/**
 * Retrieve the certificate's SHA256 fingerprint.
 *
 * @param cert          Certificate to retrieve the fingerprint from.
 * @param gc            Garbage collection arena to use when allocating string.
 *
 * @return              a string containing the certificate fingerprint
 */
struct buffer x509_get_sha256_fingerprint(openvpn_x509_cert_t *cert,
                                          struct gc_arena *gc);

/*
 * Retrieve the certificate's username from the specified field.
 *
 * If the field is prepended with ext: and ENABLE_X509ALTUSERNAME is enabled,
 * it will be loaded from an X.509 extension
 *
 * @param cn                    Buffer to return the common name in.
 * @param cn_len                Length of the cn buffer.
 * @param x509_username_field   Name of the field to load from
 * @param cert                  Certificate to retrieve the common name from.
 *
 * @return              \c FAILURE, \c or SUCCESS
 */
result_t backend_x509_get_username(char *common_name, int cn_len,
                                   char *x509_username_field, openvpn_x509_cert_t *peer_cert);

#ifdef ENABLE_X509ALTUSERNAME
/**
 * Return true iff the supplied extension field is supported by the
 * --x509-username-field option.
 */
bool x509_username_field_ext_supported(const char *extname);
#endif

/*
 * Return the certificate's serial number in decimal string representation.
 *
 * The serial number is returned as a string, since it might be a bignum.
 *
 * @param cert          Certificate to retrieve the serial number from.
 * @param gc            Garbage collection arena to use when allocating string.
 *
 * @return              String representation of the certificate's serial number
 *                      in decimal notation, or NULL on error.
 */
char *backend_x509_get_serial(openvpn_x509_cert_t *cert, struct gc_arena *gc);

/*
 * Return the certificate's serial number in hex string representation.
 *
 * The serial number is returned as a string, since it might be a bignum.
 *
 * @param cert          Certificate to retrieve the serial number from.
 * @param gc            Garbage collection arena to use when allocating string.
 *
 * @return              String representation of the certificate's serial number
 *                      in hex notation, or NULL on error.
 */
char *backend_x509_get_serial_hex(openvpn_x509_cert_t *cert,
                                  struct gc_arena *gc);

/*
 * Save X509 fields to environment, using the naming convention:
 *
 * X509_{cert_depth}_{name}={value}
 *
 * @param es            Environment set to save variables in
 * @param cert_depth    Depth of the certificate
 * @param cert          Certificate to set the environment for
 */
void x509_setenv(struct env_set *es, int cert_depth, openvpn_x509_cert_t *cert);

/*
 * Start tracking the given attribute.
 *
 * The tracked attributes are stored in ll_head.
 *
 * @param ll_head       The x509_track to store tracked atttributes in
 * @param name          Name of the attribute to track
 * @param msglevel      Message level for errors
 * @param gc            Garbage collection arena for temp data
 *
 */
void x509_track_add(const struct x509_track **ll_head, const char *name,
                    int msglevel, struct gc_arena *gc);

/*
 * Save X509 fields to environment, using the naming convention:
 *
 *  X509_{cert_depth}_{name}={value}
 *
 * This function differs from setenv_x509 below in the following ways:
 *
 * (1) Only explicitly named attributes in xt are saved, per usage
 *     of --x509-track program options.
 * (2) Only the level 0 cert info is saved unless the XT_FULL_CHAIN
 *     flag is set in xt->flags (corresponds with prepending a '+'
 *     to the name when specified by --x509-track program option).
 * (3) This function supports both X509 subject name fields as
 *     well as X509 V3 extensions.
 *
 * @param xt
 * @param es            Environment set to save variables in
 * @param cert_depth    Depth of the certificate
 * @param cert          Certificate to set the environment for
 */
void x509_setenv_track(const struct x509_track *xt, struct env_set *es,
                       const int depth, openvpn_x509_cert_t *x509);

/*
 * Check X.509 Netscape certificate type field, if available.
 *
 * @param cert          Certificate to check.
 * @param usage         One of \c NS_CERT_CHECK_CLIENT, \c NS_CERT_CHECK_SERVER,
 *                      or \c NS_CERT_CHECK_NONE.
 *
 * @return              \c SUCCESS if NS_CERT_CHECK_NONE or if the certificate has
 *                      the expected bit set. \c FAILURE if the certificate does
 *                      not have NS cert type verification or the wrong bit set.
 */
result_t x509_verify_ns_cert_type(openvpn_x509_cert_t *cert, const int usage);

/*
 * Verify X.509 key usage extension field.
 *
 * @param cert          Certificate to check.
 * @param expected_ku   Array of valid key usage values
 * @param expected_len  Length of the key usage array
 *
 * @return              \c SUCCESS if one of the key usage values matches, \c FAILURE
 *                      if key usage is not enabled, or the values do not match.
 */
result_t x509_verify_cert_ku(openvpn_x509_cert_t *x509, const unsigned *const expected_ku,
                             int expected_len);

/*
 * Verify X.509 extended key usage extension field.
 *
 * @param cert          Certificate to check.
 * @param expected_oid  String representation of the expected Object ID. May be
 *                      either the string representation of the numeric OID
 *                      (e.g. \c "1.2.3.4", or the descriptive string matching
 *                      the OID.
 *
 * @return              \c SUCCESS if one of the expected OID matches one of the
 *                      extended key usage fields, \c FAILURE if extended key
 *                      usage is not enabled, or the values do not match.
 */
result_t x509_verify_cert_eku(openvpn_x509_cert_t *x509, const char *const expected_oid);

/*
 * Store the given certificate in pem format in a temporary file in tmp_dir
 *
 * @param cert          Certificate to store
 * @param tmp_dir       Temporary directory to store the directory
 * @param gc            gc_arena to store temporary objects in
 *
 *
 */
result_t x509_write_pem(FILE *peercert_file, openvpn_x509_cert_t *peercert);

/**
 * Return true iff a CRL is configured, but is not loaded.  This can be caused
 * by e.g. a CRL parsing error, a missing CRL file or CRL file permission
 * errors.  (These conditions are checked upon startup, but the CRL might be
 * updated and reloaded during runtime.)
 */
bool tls_verify_crl_missing(const struct tls_options *opt);

#endif /* SSL_VERIFY_BACKEND_H_ */