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-2018 OpenVPN Inc <sales@openvpn.net> 9 * Copyright (C) 2010-2018 Fox Crypto B.V. <openvpn@fox-it.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 library-specific backend interface 27 */ 28 29 #ifndef SSL_VERIFY_BACKEND_H_ 30 #define SSL_VERIFY_BACKEND_H_ 31 32 /** 33 * Result of verification function 34 */ 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 89 /** 90 * Retrieve the certificate's SHA1 fingerprint. 91 * 92 * @param cert Certificate to retrieve the fingerprint from. 93 * @param gc Garbage collection arena to use when allocating string. 94 * 95 * @return a string containing the certificate fingerprint 96 */ 97 struct buffer x509_get_sha1_fingerprint(openvpn_x509_cert_t *cert, 98 struct gc_arena *gc); 99 100 /** 101 * Retrieve the certificate's SHA256 fingerprint. 102 * 103 * @param cert Certificate to retrieve the fingerprint from. 104 * @param gc Garbage collection arena to use when allocating string. 105 * 106 * @return a string containing the certificate fingerprint 107 */ 108 struct buffer x509_get_sha256_fingerprint(openvpn_x509_cert_t *cert, 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 /** 129 * Return true iff the supplied extension field is supported by the 130 * --x509-username-field option. 131 */ 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 */ 160 char *backend_x509_get_serial_hex(openvpn_x509_cert_t *cert, 161 struct gc_arena *gc); 162 163 /* 164 * Save X509 fields to environment, using the naming convention: 165 * 166 * X509_{cert_depth}_{name}={value} 167 * 168 * @param es Environment set to save variables in 169 * @param cert_depth Depth of the certificate 170 * @param cert Certificate to set the environment for 171 */ 172 void x509_setenv(struct env_set *es, int cert_depth, openvpn_x509_cert_t *cert); 173 174 /* 175 * Start tracking the given attribute. 176 * 177 * The tracked attributes are stored in ll_head. 178 * 179 * @param ll_head The x509_track to store tracked attributes in 180 * @param name Name of the attribute to track 181 * @param msglevel Message level for errors 182 * @param gc Garbage collection arena for temp data 183 * 184 */ 185 void x509_track_add(const struct x509_track **ll_head, const char *name, 186 int msglevel, struct gc_arena *gc); 187 188 /* 189 * Save X509 fields to environment, using the naming convention: 190 * 191 * X509_{cert_depth}_{name}={value} 192 * 193 * This function differs from setenv_x509 below in the following ways: 194 * 195 * (1) Only explicitly named attributes in xt are saved, per usage 196 * of --x509-track program options. 197 * (2) Only the level 0 cert info is saved unless the XT_FULL_CHAIN 198 * flag is set in xt->flags (corresponds with prepending a '+' 199 * to the name when specified by --x509-track program option). 200 * (3) This function supports both X509 subject name fields as 201 * well as X509 V3 extensions. 202 * 203 * @param xt 204 * @param es Environment set to save variables in 205 * @param cert_depth Depth of the certificate 206 * @param cert Certificate to set the environment for 207 */ 208 void x509_setenv_track(const struct x509_track *xt, struct env_set *es, 209 const int depth, openvpn_x509_cert_t *x509); 210 211 /* 212 * Check X.509 Netscape certificate type field, if available. 213 * 214 * @param cert Certificate to check. 215 * @param usage One of \c NS_CERT_CHECK_CLIENT, \c NS_CERT_CHECK_SERVER, 216 * or \c NS_CERT_CHECK_NONE. 217 * 218 * @return \c SUCCESS if NS_CERT_CHECK_NONE or if the certificate has 219 * the expected bit set. \c FAILURE if the certificate does 220 * not have NS cert type verification or the wrong bit set. 221 */ 222 result_t x509_verify_ns_cert_type(openvpn_x509_cert_t *cert, const int usage); 223 224 /* 225 * Verify X.509 key usage extension field. 226 * 227 * @param cert Certificate to check. 228 * @param expected_ku Array of valid key usage values 229 * @param expected_len Length of the key usage array 230 * 231 * @return \c SUCCESS if one of the key usage values matches, \c FAILURE 232 * if key usage is not enabled, or the values do not match. 233 */ 234 result_t x509_verify_cert_ku(openvpn_x509_cert_t *x509, const unsigned *const expected_ku, 235 int expected_len); 236 237 /* 238 * Verify X.509 extended key usage extension field. 239 * 240 * @param cert Certificate to check. 241 * @param expected_oid String representation of the expected Object ID. May be 242 * either the string representation of the numeric OID 243 * (e.g. \c "1.2.3.4", or the descriptive string matching 244 * the OID. 245 * 246 * @return \c SUCCESS if one of the expected OID matches one of the 247 * extended key usage fields, \c FAILURE if extended key 248 * usage is not enabled, or the values do not match. 249 */ 250 result_t x509_verify_cert_eku(openvpn_x509_cert_t *x509, const char *const expected_oid); 251 252 /* 253 * Store the given certificate in pem format in a temporary file in tmp_dir 254 * 255 * @param cert Certificate to store 256 * @param tmp_dir Temporary directory to store the directory 257 * @param gc gc_arena to store temporary objects in 258 * 259 * 260 */ 261 result_t x509_write_pem(FILE *peercert_file, openvpn_x509_cert_t *peercert); 262 263 /** 264 * Return true iff a CRL is configured, but is not loaded. This can be caused 265 * by e.g. a CRL parsing error, a missing CRL file or CRL file permission 266 * errors. (These conditions are checked upon startup, but the CRL might be 267 * updated and reloaded during runtime.) 268 */ 269 bool tls_verify_crl_missing(const struct tls_options *opt); 270 271 #endif /* SSL_VERIFY_BACKEND_H_ */ 272