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-2010 OpenVPN Technologies, Inc. <sales@openvpn.net> 9 * Copyright (C) 2010 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 21 * along with this program (see the file COPYING included with this 22 * distribution); if not, write to the Free Software Foundation, Inc., 23 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 24 */ 25 26/** 27 * @file Control Channel Verification Module library-specific backend interface 28 */ 29 30#ifndef SSL_VERIFY_BACKEND_H_ 31#define SSL_VERIFY_BACKEND_H_ 32 33/** 34 * Result of verification function 35 */ 36typedef enum { SUCCESS=0, FAILURE=1 } result_t; 37 38/* 39 * Backend support functions. 40 * 41 * The following functions are needed by the backend, but defined in the main 42 * file. 43 */ 44 45/* 46 * Verify certificate for the given session. Performs OpenVPN-specific 47 * verification. 48 * 49 * This function must be called for every certificate in the certificate 50 * chain during the certificate verification stage of the handshake. 51 * 52 * @param session TLS Session associated with this tunnel 53 * @param cert Certificate to process 54 * @param cert_depth Depth of the current certificate 55 * 56 * @return \c SUCCESS if verification was successful, \c FAILURE on failure. 57 */ 58result_t verify_cert(struct tls_session *session, openvpn_x509_cert_t *cert, int cert_depth); 59 60/* 61 * Remember the given certificate hash, allowing the certificate chain to be 62 * locked between sessions. 63 * 64 * Must be called for every certificate in the verification chain, whether it 65 * is valid or not. 66 * 67 * @param session TLS Session associated with this tunnel 68 * @param cert_depth Depth of the current certificate 69 * @param sha1_hash Hash of the current certificate 70 */ 71void cert_hash_remember (struct tls_session *session, const int cert_depth, 72 const unsigned char *sha1_hash); 73 74/* 75 * Library-specific functions. 76 * 77 * The following functions must be implemented on a library-specific basis. 78 */ 79 80/* 81 * Retrieve certificate's subject name. 82 * 83 * @param cert Certificate to retrieve the subject from. 84 * @param gc Garbage collection arena to use when allocating string. 85 * 86 * @return a string containing the subject 87 */ 88char *x509_get_subject (openvpn_x509_cert_t *cert, struct gc_arena *gc); 89 90/* Retrieve the certificate's SHA1 hash. 91 * 92 * @param cert Certificate to retrieve the hash from. 93 * @param gc Garbage collection arena to use when allocating string. 94 * 95 * @return a string containing the SHA1 hash of the certificate 96 */ 97unsigned char *x509_get_sha1_hash (openvpn_x509_cert_t *cert, struct gc_arena *gc); 98 99/* 100 * Retrieve the certificate's username from the specified field. 101 * 102 * If the field is prepended with ext: and ENABLE_X509ALTUSERNAME is enabled, 103 * it will be loaded from an X.509 extension 104 * 105 * @param cn Buffer to return the common name in. 106 * @param cn_len Length of the cn buffer. 107 * @param x509_username_field Name of the field to load from 108 * @param cert Certificate to retrieve the common name from. 109 * 110 * @return \c FAILURE, \c or SUCCESS 111 */ 112result_t x509_get_username (char *common_name, int cn_len, 113 char * x509_username_field, openvpn_x509_cert_t *peer_cert); 114 115/* 116 * Return the certificate's serial number. 117 * 118 * The serial number is returned as a string, since it might be a bignum. 119 * 120 * @param cert Certificate to retrieve the serial number from. 121 * @param gc Garbage collection arena to use when allocating string. 122 * 123 * @return The certificate's serial number. 124 */ 125char *x509_get_serial (openvpn_x509_cert_t *cert, struct gc_arena *gc); 126 127/* 128 * Save X509 fields to environment, using the naming convention: 129 * 130 * X509_{cert_depth}_{name}={value} 131 * 132 * @param es Environment set to save variables in 133 * @param cert_depth Depth of the certificate 134 * @param cert Certificate to set the environment for 135 */ 136void x509_setenv (struct env_set *es, int cert_depth, openvpn_x509_cert_t *cert); 137 138#ifdef ENABLE_X509_TRACK 139 140/* 141 * Start tracking the given attribute. 142 * 143 * The tracked attributes are stored in ll_head. 144 * 145 * @param ll_head The x509_track to store tracked atttributes in 146 * @param name Name of the attribute to track 147 * @param msglevel Message level for errors 148 * @param gc Garbage collection arena for temp data 149 * 150 */ 151void x509_track_add (const struct x509_track **ll_head, const char *name, 152 int msglevel, struct gc_arena *gc); 153 154/* 155 * Save X509 fields to environment, using the naming convention: 156 * 157 * X509_{cert_depth}_{name}={value} 158 * 159 * This function differs from setenv_x509 below in the following ways: 160 * 161 * (1) Only explicitly named attributes in xt are saved, per usage 162 * of --x509-track program options. 163 * (2) Only the level 0 cert info is saved unless the XT_FULL_CHAIN 164 * flag is set in xt->flags (corresponds with prepending a '+' 165 * to the name when specified by --x509-track program option). 166 * (3) This function supports both X509 subject name fields as 167 * well as X509 V3 extensions. 168 * 169 * @param xt 170 * @param es Environment set to save variables in 171 * @param cert_depth Depth of the certificate 172 * @param cert Certificate to set the environment for 173 */ 174void x509_setenv_track (const struct x509_track *xt, struct env_set *es, 175 const int depth, openvpn_x509_cert_t *x509); 176 177#endif 178 179/* 180 * Check X.509 Netscape certificate type field, if available. 181 * 182 * @param cert Certificate to check. 183 * @param usage One of \c NS_CERT_CHECK_CLIENT, \c NS_CERT_CHECK_SERVER, 184 * or \c NS_CERT_CHECK_NONE. 185 * 186 * @return \c SUCCESS if NS_CERT_CHECK_NONE or if the certificate has 187 * the expected bit set. \c FAILURE if the certificate does 188 * not have NS cert type verification or the wrong bit set. 189 */ 190result_t x509_verify_ns_cert_type(const openvpn_x509_cert_t *cert, const int usage); 191 192#if OPENSSL_VERSION_NUMBER >= 0x00907000L || ENABLE_CRYPTO_POLARSSL 193 194/* 195 * Verify X.509 key usage extension field. 196 * 197 * @param cert Certificate to check. 198 * @param expected_ku Array of valid key usage values 199 * @param expected_len Length of the key usage array 200 * 201 * @return \c SUCCESS if one of the key usage values matches, \c FAILURE 202 * if key usage is not enabled, or the values do not match. 203 */ 204result_t x509_verify_cert_ku (openvpn_x509_cert_t *x509, const unsigned * const expected_ku, 205 int expected_len); 206 207/* 208 * Verify X.509 extended key usage extension field. 209 * 210 * @param cert Certificate to check. 211 * @param expected_oid String representation of the expected Object ID. May be 212 * either the string representation of the numeric OID 213 * (e.g. \c "1.2.3.4", or the descriptive string matching 214 * the OID. 215 * 216 * @return \c SUCCESS if one of the expected OID matches one of the 217 * extended key usage fields, \c FAILURE if extended key 218 * usage is not enabled, or the values do not match. 219 */ 220result_t x509_verify_cert_eku (openvpn_x509_cert_t *x509, const char * const expected_oid); 221 222#endif 223 224/* 225 * Store the given certificate in pem format in a temporary file in tmp_dir 226 * 227 * @param cert Certificate to store 228 * @param tmp_dir Temporary directory to store the directory 229 * @param gc gc_arena to store temporary objects in 230 * 231 * 232 */ 233result_t x509_write_pem(FILE *peercert_file, openvpn_x509_cert_t *peercert); 234 235/* 236 * Check the certificate against a CRL file. 237 * 238 * @param crl_file File name of the CRL file 239 * @param cert Certificate to verify 240 * @param subject Subject of the given certificate 241 * 242 * @return \c SUCCESS if the CRL was not signed by the issuer of the 243 * certificate or does not contain an entry for it. 244 * \c FAILURE otherwise. 245 */ 246result_t x509_verify_crl(const char *crl_file, openvpn_x509_cert_t *cert, 247 const char *subject); 248 249#endif /* SSL_VERIFY_BACKEND_H_ */ 250