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) 2016-2018 Fox Crypto B.V. <openvpn@fox-it.com> 9 * 10 * This program is free software; you can redistribute it and/or modify 11 * it under the terms of the GNU General Public License version 2 12 * as published by the Free Software Foundation. 13 * 14 * This program is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 17 * GNU General Public License for more details. 18 * 19 * You should have received a copy of the GNU General Public License along 20 * with this program; if not, write to the Free Software Foundation, Inc., 21 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 22 */ 23 24 /** 25 * @defgroup tls_crypt Control channel encryption (--tls-crypt, --tls-crypt-v2) 26 * @ingroup control_tls 27 * @{ 28 * 29 * Control channel encryption uses a pre-shared static key (like the --tls-auth 30 * key) to encrypt control channel packets. 31 * 32 * Encrypting control channel packets has three main advantages: 33 * - It provides more privacy by hiding the certificate used for the TLS 34 * connection. 35 * - It is harder to identify OpenVPN traffic as such. 36 * - It provides "poor-man's" post-quantum security, against attackers who 37 * will never know the pre-shared key (i.e. no forward secrecy). 38 * 39 * --tls-crypt uses a tls-auth-style group key, where all servers and clients 40 * share the same group key. --tls-crypt-v2 adds support for client-specific 41 * keys, where all servers share the same client-key encryption key, and each 42 * clients receives a unique client key, both in plaintext and in encrypted 43 * form. When connecting to a server, the client sends the encrypted key to 44 * the server in the first packet (P_CONTROL_HARD_RESET_CLIENT_V3). The server 45 * then decrypts that key, and both parties can use the same client-specific 46 * key for tls-crypt packets. See doc/tls-crypt-v2.txt for more details. 47 * 48 * @par On-the-wire tls-crypt packet specification 49 * @parblock 50 * Control channel encryption is based on the SIV construction [0], to achieve 51 * nonce misuse-resistant authenticated encryption: 52 * 53 * \code{.unparsed} 54 * msg = control channel plaintext 55 * header = opcode (1 byte) || session_id (8 bytes) || packet_id (8 bytes) 56 * Ka = authentication key (256 bits) 57 * Ke = encryption key (256 bits) 58 * (Ka and Ke are pre-shared keys, like with --tls-auth) 59 * 60 * auth_tag = HMAC-SHA256(Ka, header || msg) 61 * IV = 128 most-significant bits of auth_tag 62 * ciph = AES256-CTR(Ke, IV, msg) 63 * 64 * output = Header || Tag || Ciph 65 * \endcode 66 * 67 * This boils down to the following on-the-wire packet format: 68 * 69 * \code{.unparsed} 70 * - opcode - || - session_id - || - packet_id - || auth_tag || * payload * 71 * \endcode 72 * 73 * Where 74 * <tt>- XXX -</tt> means authenticated, and 75 * <tt>* XXX *</tt> means authenticated and encrypted. 76 * 77 * @endparblock 78 */ 79 80 #ifndef TLSCRYPT_H 81 #define TLSCRYPT_H 82 83 #include "base64.h" 84 #include "buffer.h" 85 #include "crypto.h" 86 #include "session_id.h" 87 #include "ssl_common.h" 88 89 #define TLS_CRYPT_TAG_SIZE (256/8) 90 #define TLS_CRYPT_PID_SIZE (sizeof(packet_id_type) + sizeof(net_time_t)) 91 #define TLS_CRYPT_BLOCK_SIZE (128/8) 92 93 #define TLS_CRYPT_OFF_PID (1 + SID_SIZE) 94 #define TLS_CRYPT_OFF_TAG (TLS_CRYPT_OFF_PID + TLS_CRYPT_PID_SIZE) 95 #define TLS_CRYPT_OFF_CT (TLS_CRYPT_OFF_TAG + TLS_CRYPT_TAG_SIZE) 96 97 #define TLS_CRYPT_V2_MAX_WKC_LEN (1024) 98 #define TLS_CRYPT_V2_CLIENT_KEY_LEN (2048 / 8) 99 #define TLS_CRYPT_V2_SERVER_KEY_LEN (sizeof(struct key)) 100 #define TLS_CRYPT_V2_TAG_SIZE (TLS_CRYPT_TAG_SIZE) 101 #define TLS_CRYPT_V2_MAX_METADATA_LEN (unsigned)(TLS_CRYPT_V2_MAX_WKC_LEN \ 102 - (TLS_CRYPT_V2_CLIENT_KEY_LEN + TLS_CRYPT_V2_TAG_SIZE \ 103 + sizeof(uint16_t))) 104 #define TLS_CRYPT_V2_MAX_B64_METADATA_LEN \ 105 OPENVPN_BASE64_LENGTH(TLS_CRYPT_V2_MAX_METADATA_LEN - 1) 106 107 /** 108 * Initialize a key_ctx_bi structure for use with --tls-crypt. 109 * 110 * @param key The key context to initialize 111 * @param key_file The file to read the key from or the key itself if 112 * key_inline is true. 113 * @param key_inline True if key_file contains an inline key, False 114 * otherwise. 115 * @param tls_server Must be set to true is this is a TLS server instance. 116 */ 117 void tls_crypt_init_key(struct key_ctx_bi *key, const char *key_file, 118 bool key_inline, bool tls_server); 119 120 /** 121 * Returns the maximum overhead (in bytes) added to the destination buffer by 122 * tls_crypt_wrap(). 123 */ 124 int tls_crypt_buf_overhead(void); 125 126 /** 127 * Adjust frame parameters for --tls-crypt overhead. 128 */ 129 void tls_crypt_adjust_frame_parameters(struct frame *frame); 130 131 /** 132 * Wrap a control channel packet (both authenticates and encrypts the data). 133 * 134 * @param src Data to authenticate and encrypt. 135 * @param dst Any data present in this buffer is first authenticated, then 136 * the wrapped packet id and data from the src buffer are appended. 137 * Must have at least tls_crypt_buf_overhead()+BLEN(src) headroom. 138 * @param opt The crypto state for this --tls-crypt instance. 139 * 140 * @returns true iff wrapping succeeded. 141 */ 142 bool tls_crypt_wrap(const struct buffer *src, struct buffer *dst, 143 struct crypto_options *opt); 144 145 /** 146 * Unwrap a control channel packet (decrypts, authenticates and performs 147 * replay checks). 148 * 149 * @param src Data to decrypt and authenticate. 150 * @param dst Returns the decrypted data, if unwrapping was successful. 151 * @param opt The crypto state for this --tls-crypt instance. 152 * 153 * @returns true iff unwrapping succeeded (data authenticated correctly and was 154 * no replay). 155 */ 156 bool tls_crypt_unwrap(const struct buffer *src, struct buffer *dst, 157 struct crypto_options *opt); 158 159 /** 160 * Initialize a tls-crypt-v2 server key (used to encrypt/decrypt client keys). 161 * 162 * @param key Key structure to be initialized. Must be non-NULL. 163 * @parem encrypt If true, initialize the key structure for encryption, 164 * otherwise for decryption. 165 * @param key_file File path of the key file to load or the key itself if 166 * key_inline is true. 167 * @param key_inline True if key_file contains an inline key, False 168 * otherwise. 169 * 170 */ 171 void tls_crypt_v2_init_server_key(struct key_ctx *key_ctx, bool encrypt, 172 const char *key_file, bool key_inline); 173 174 /** 175 * Initialize a tls-crypt-v2 client key. 176 * 177 * @param key Key structure to be initialized with the client 178 * key. 179 * @param wrapped_key_buf Returns buffer containing the wrapped key that will 180 * be sent to the server when connecting. Caller must 181 * free this buffer when no longer needed. 182 * @param key_file File path of the key file to load or the key itself 183 * if key_inline is true. 184 * @param key_inline True if key_file contains an inline key, False 185 * otherwise. 186 */ 187 void tls_crypt_v2_init_client_key(struct key_ctx_bi *key, 188 struct buffer *wrapped_key_buf, 189 const char *key_file, bool key_inline); 190 191 /** 192 * Extract a tls-crypt-v2 client key from a P_CONTROL_HARD_RESET_CLIENT_V3 193 * message, and load the key into the supplied tls wrap context. 194 * 195 * @param buf Buffer containing a received P_CONTROL_HARD_RESET_CLIENT_V3 196 * message. 197 * @param ctx tls-wrap context to be initialized with the client key. 198 * 199 * @returns true if a key was successfully extracted. 200 */ 201 bool tls_crypt_v2_extract_client_key(struct buffer *buf, 202 struct tls_wrap_ctx *ctx, 203 const struct tls_options *opt); 204 205 /** 206 * Generate a tls-crypt-v2 server key, and write to file. 207 * 208 * @param filename Filename of the server key file to create. 209 */ 210 void tls_crypt_v2_write_server_key_file(const char *filename); 211 212 /** 213 * Generate a tls-crypt-v2 client key, and write to file. 214 * 215 * @param filename Filename of the client key file to create. 216 * @param b64_metadata Base64 metadata to be included in the client key. 217 * @param key_file File path of the server key to use for wrapping the 218 * client key or the key itself if key_inline is true. 219 * @param key_inline True if key_file contains an inline key, False 220 * otherwise. 221 */ 222 void tls_crypt_v2_write_client_key_file(const char *filename, 223 const char *b64_metadata, 224 const char *key_file, bool key_inline); 225 226 /** @} */ 227 228 #endif /* TLSCRYPT_H */ 229