From patchwork Sun Aug 5 22:02:33 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Steffan Karger X-Patchwork-Id: 438 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director7.mail.ord1d.rsapps.net ([172.30.191.6]) by backend30.mail.ord1d.rsapps.net (Dovecot) with LMTP id 2whzOFsBaFtabAAAIUCqbw for ; Mon, 06 Aug 2018 04:05:47 -0400 Received: from proxy15.mail.ord1d.rsapps.net ([172.30.191.6]) by director7.mail.ord1d.rsapps.net (Dovecot) with LMTP id p48YC1sBaFs4DgAAovjBpQ ; Mon, 06 Aug 2018 04:05:47 -0400 Received: from smtp7.gate.ord1d ([172.30.191.6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy15.mail.ord1d.rsapps.net with LMTP id kPUPOFsBaFuRZgAAAY1PeQ ; Mon, 06 Aug 2018 04:05:47 -0400 X-Spam-Threshold: 95 X-Spam-Score: 0 X-Spam-Flag: NO X-Virus-Scanned: OK X-Orig-To: openvpnslackdevel@openvpn.net X-Originating-Ip: [216.105.38.7] Authentication-Results: smtp7.gate.ord1d.rsapps.net; iprev=pass policy.iprev="216.105.38.7"; spf=pass smtp.mailfrom="openvpn-devel-bounces@lists.sourceforge.net" smtp.helo="lists.sourceforge.net"; dkim=fail (signature verification failed) header.d=sourceforge.net; dkim=fail (signature verification failed) header.d=sf.net; dmarc=none (p=nil; dis=none) header.from=fox-it.com X-Suspicious-Flag: YES X-Classification-ID: 867a1d8c-994f-11e8-8664-525400d28ed9-1-1 Received: from [216.105.38.7] ([216.105.38.7:46814] helo=lists.sourceforge.net) by smtp7.gate.ord1d.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id 66/F3-26547-B51086B5; Mon, 06 Aug 2018 04:05:47 -0400 Received: from [127.0.0.1] (helo=sfs-ml-4.v29.lw.sourceforge.com) by sfs-ml-4.v29.lw.sourceforge.com with esmtp (Exim 4.90_1) (envelope-from ) id 1fmaVU-0006L6-8d; Mon, 06 Aug 2018 08:04:48 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-4.v29.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.90_1) (envelope-from ) id 1fmaVO-0006Kz-5t for openvpn-devel@lists.sourceforge.net; Mon, 06 Aug 2018 08:04:42 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sourceforge.net; s=x; h=Content-Type:MIME-Version:References:In-Reply-To: Message-ID:Date:Subject:CC:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=3d4wiss5YVts++d0lXqd9YsA4yxbDaF5bL/Pf44FP1g=; b=VCxfSHXDDfKU1MGfLcSr+r+Zj2 LAM1G2pmGTxnZ9c5eLxGLUiuc9A7CA3w9v8CDzyB4RqbhV+6UhaKiskAyYaHBvA2DH0Wg4fxRVlKI gw5WyV1BBvTKncqg7YkZjzOuVpPWrVKVz4/4PpWbUIo1gjpeS5inIxHrhq/ZDe9ZMrs8=; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sf.net; s=x ; h=Content-Type:MIME-Version:References:In-Reply-To:Message-ID:Date:Subject: CC:To:From:Sender:Reply-To:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=3d4wiss5YVts++d0lXqd9YsA4yxbDaF5bL/Pf44FP1g=; b=WyyQvxPMwobrK4LysurW4ebvri ouCz45dhn5OirmMAA+7NoA1LAVcCypwm8SZAOzYaivskKaUHwi1Ucx6DL8hVzh6ozPI4+S2lPaYOL 0doGpvRer4AtD57wlRHj+NiCzkiCw16WWnLNKnvE1NvWCJz3pCCDQIkniEACEXYrkNV8=; Received: from ns2.fox-it.com ([178.250.144.131]) by sfi-mx-3.v28.lw.sourceforge.com with esmtps (TLSv1:ECDHE-RSA-AES256-SHA:256) (Exim 4.90_1) id 1fmaVM-009VCO-GO for openvpn-devel@lists.sourceforge.net; Mon, 06 Aug 2018 08:04:42 +0000 Received: from FOXDFT52.FOX.local (unknown [10.0.0.129]) by ns2.fox-it.com (Postfix) with ESMTPS id 5CC7E1AF843 for ; Mon, 6 Aug 2018 10:04:32 +0200 (CEST) Received: from steffan-fox.fox.local (10.0.3.178) by FOXDFT52.FOX.local (10.0.0.129) with Microsoft SMTP Server (TLS) id 15.0.1293.2; Mon, 6 Aug 2018 10:04:32 +0200 From: Steffan Karger To: Date: Mon, 6 Aug 2018 10:02:33 +0200 Message-ID: <1533542553-7383-1-git-send-email-steffan.karger@fox-it.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: <4ff9b515-b65c-ddb4-30e5-03660cd9f245@unstable.cc> References: <4ff9b515-b65c-ddb4-30e5-03660cd9f245@unstable.cc> MIME-Version: 1.0 X-ClientProxiedBy: FOXDFT52.FOX.local (10.0.0.129) To FOXDFT52.FOX.local (10.0.0.129) X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. See http://spamassassin.org/tag/ for more details. -0.0 SPF_PASS SPF: sender matches SPF record X-Headers-End: 1fmaVM-009VCO-GO Subject: [Openvpn-devel] [PATCH v5 1/7] Introduce buffer_write_file() X-BeenThere: openvpn-devel@lists.sourceforge.net X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: openvpn-devel-bounces@lists.sourceforge.net X-getmail-retrieved-from-mailbox: Inbox Rewrite buf_write_string_file to buffer_write_file, which is simpler to use and can deal with not-null-terminated strings. Mostly implemented so this can be easily reused for tls-crypt-v2 (client) key files. Signed-off-by: Steffan Karger Acked-by: Antonio Quartulli Tested-by: Antonio Quartulli --- v3: split change out of "generate client key", reuse in write_key_file() v4: improve doxygen and error handling (thanks to ordex) v5: do not print close error if open fails (thanks to ordex) src/openvpn/buffer.c | 31 ++++++++++++++++++++++++------- src/openvpn/buffer.h | 12 ++++++++---- src/openvpn/crypto.c | 33 ++++++--------------------------- src/openvpn/crypto.h | 5 +++++ src/openvpn/init.c | 4 ++++ 5 files changed, 47 insertions(+), 38 deletions(-) diff --git a/src/openvpn/buffer.c b/src/openvpn/buffer.c index 0972139..7630ff7 100644 --- a/src/openvpn/buffer.c +++ b/src/openvpn/buffer.c @@ -343,16 +343,33 @@ convert_to_one_line(struct buffer *buf) } } -/* NOTE: requires that string be null terminated */ -void -buf_write_string_file(const struct buffer *buf, const char *filename, int fd) +bool +buffer_write_file(const char *filename, const struct buffer *buf) { - const int len = strlen((char *) BPTR(buf)); - const int size = write(fd, BPTR(buf), len); - if (size != len) + bool ret = false; + int fd = platform_open(filename, O_CREAT | O_TRUNC | O_WRONLY, + S_IRUSR | S_IWUSR); + if (fd == -1) + { + msg(M_ERRNO, "Cannot open file '%s' for write", filename); + return false; + } + + const int size = write(fd, BPTR(buf), BLEN(buf)); + if (size != BLEN(buf)) { - msg(M_ERR, "Write error on file '%s'", filename); + msg(M_ERRNO, "Write error on file '%s'", filename); + goto cleanup; + } + + ret = true; +cleanup: + if (close(fd) < 0) + { + msg(M_ERRNO, "Close error on file %s", filename); + ret = false; } + return ret; } /* diff --git a/src/openvpn/buffer.h b/src/openvpn/buffer.h index 6b6025e..704129a 100644 --- a/src/openvpn/buffer.h +++ b/src/openvpn/buffer.h @@ -469,11 +469,15 @@ const char *skip_leading_whitespace(const char *str); void string_null_terminate(char *str, int len, int capacity); -/* - * Write string in buf to file descriptor fd. - * NOTE: requires that string be null terminated. +/** + * Write buffer contents to file. + * + * @param filename The filename to write the buffer to. + * @param buf Thu buffer to write to the file. + * + * @return true on success, false otherwise. */ -void buf_write_string_file(const struct buffer *buf, const char *filename, int fd); +bool buffer_write_file(const char *filename, const struct buffer *buf); /* * write a string to the end of a buffer that was diff --git a/src/openvpn/crypto.c b/src/openvpn/crypto.c index 5381ef2..c8d95f3 100644 --- a/src/openvpn/crypto.c +++ b/src/openvpn/crypto.c @@ -1418,36 +1418,24 @@ read_key_file(struct key2 *key2, const char *file, const unsigned int flags) gc_free(&gc); } -/* - * Write key to file, return number of random bits - * written. - */ int write_key_file(const int nkeys, const char *filename) { struct gc_arena gc = gc_new(); - int fd, i; - int nbits = 0; + int nbits = nkeys * sizeof(struct key) * 8; /* must be large enough to hold full key file */ struct buffer out = alloc_buf_gc(2048, &gc); - struct buffer nbits_head_text = alloc_buf_gc(128, &gc); /* how to format the ascii file representation of key */ const int bytes_per_line = 16; - /* open key file */ - fd = platform_open(filename, O_CREAT | O_TRUNC | O_WRONLY, S_IRUSR | S_IWUSR); - - if (fd == -1) - { - msg(M_ERR, "Cannot open shared secret file '%s' for write", filename); - } - + /* write header */ + buf_printf(&out, "#\n# %d bit OpenVPN static key\n#\n", nbits); buf_printf(&out, "%s\n", static_key_head); - for (i = 0; i < nkeys; ++i) + for (int i = 0; i < nkeys; ++i) { struct key key; char *fmt; @@ -1463,9 +1451,6 @@ write_key_file(const int nkeys, const char *filename) "\n", &gc); - /* increment random bits counter */ - nbits += sizeof(key) * 8; - /* write to holding buffer */ buf_printf(&out, "%s\n", fmt); @@ -1476,16 +1461,10 @@ write_key_file(const int nkeys, const char *filename) buf_printf(&out, "%s\n", static_key_foot); - /* write number of bits */ - buf_printf(&nbits_head_text, "#\n# %d bit OpenVPN static key\n#\n", nbits); - buf_write_string_file(&nbits_head_text, filename, fd); - /* write key file, now formatted in out, to file */ - buf_write_string_file(&out, filename, fd); - - if (close(fd)) + if(!buffer_write_file(filename, &out)) { - msg(M_ERR, "Close error on shared secret file %s", filename); + nbits = -1; } /* zero memory which held file content (memory will be freed by GC) */ diff --git a/src/openvpn/crypto.h b/src/openvpn/crypto.h index 9417fa1..0dc597f 100644 --- a/src/openvpn/crypto.h +++ b/src/openvpn/crypto.h @@ -271,6 +271,11 @@ struct crypto_options #define RKF_INLINE (1<<1) void read_key_file(struct key2 *key2, const char *file, const unsigned int flags); +/** + * Write nkeys 1024-bits keys to file. + * + * @returns number of random bits written, or -1 on failure. + */ int write_key_file(const int nkeys, const char *filename); int read_passphrase_hash(const char *passphrase_file, diff --git a/src/openvpn/init.c b/src/openvpn/init.c index f432106..2933d55 100644 --- a/src/openvpn/init.c +++ b/src/openvpn/init.c @@ -1041,6 +1041,10 @@ do_genkey(const struct options *options) } nbits_written = write_key_file(2, options->shared_secret_file); + if (nbits_written < 0) + { + msg(M_FATAL, "Failed to write key file"); + } msg(D_GENKEY | M_NOPREFIX, "Randomly generated %d bit key written to %s", nbits_written, From patchwork Sun Aug 5 22:05:07 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Steffan Karger X-Patchwork-Id: 439 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director7.mail.ord1d.rsapps.net ([172.31.255.6]) by backend30.mail.ord1d.rsapps.net (Dovecot) with LMTP id lCF6DokBaFtVbAAAIUCqbw for ; Mon, 06 Aug 2018 04:06:33 -0400 Received: from proxy17.mail.iad3b.rsapps.net ([172.31.255.6]) by director7.mail.ord1d.rsapps.net (Dovecot) with LMTP id odPvCIkBaFsHDAAAovjBpQ ; Mon, 06 Aug 2018 04:06:33 -0400 Received: from smtp14.gate.iad3b ([172.31.255.6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy17.mail.iad3b.rsapps.net with LMTP id gKJ9GYkBaFsoVQAA5ccGVQ ; Mon, 06 Aug 2018 04:06:33 -0400 X-Spam-Threshold: 95 X-Spam-Score: 0 X-Spam-Flag: NO X-Virus-Scanned: OK X-Orig-To: openvpnslackdevel@openvpn.net X-Originating-Ip: [216.105.38.7] Authentication-Results: smtp14.gate.iad3b.rsapps.net; iprev=pass policy.iprev="216.105.38.7"; spf=pass smtp.mailfrom="openvpn-devel-bounces@lists.sourceforge.net" smtp.helo="lists.sourceforge.net"; dkim=fail (signature verification failed) header.d=sourceforge.net; dkim=fail (signature verification failed) header.d=sf.net; dmarc=none (p=nil; dis=none) header.from=fox-it.com X-Suspicious-Flag: YES X-Classification-ID: a153bee2-994f-11e8-a5f3-52540057873d-1-1 Received: from [216.105.38.7] ([216.105.38.7:37743] helo=lists.sourceforge.net) by smtp14.gate.iad3b.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id 80/B2-17107-881086B5; Mon, 06 Aug 2018 04:06:33 -0400 Received: from [127.0.0.1] (helo=sfs-ml-1.v29.lw.sourceforge.com) by sfs-ml-1.v29.lw.sourceforge.com with esmtp (Exim 4.90_1) (envelope-from ) id 1fmaW2-0004so-VZ; Mon, 06 Aug 2018 08:05:22 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-1.v29.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.90_1) (envelope-from ) id 1fmaW1-0004rz-74 for openvpn-devel@lists.sourceforge.net; Mon, 06 Aug 2018 08:05:21 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sourceforge.net; s=x; h=Content-Type:MIME-Version:References:In-Reply-To: Message-ID:Date:Subject:CC:To:From:Sender:Reply-To:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=NYm0yv34KiRxkDEzzLLNI07sy4N51XzZGXLsOurtbII=; b=TrfZKBTiR3jPsfHp6rsZFl3X4s x8d0s/3+A6rIPUfHLMIGCQtu753MWr8dF8lNFSFERmVresvfV0DTFRXrpst5eJYWrUXFdykoKrETF LaRGZ+x9NE6MmlsR24OUoe0HMVgnrxPY+mZ19GoXVQo14hDecrub+utgPDWpIT1BTFaw=; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sf.net; s=x ; h=Content-Type:MIME-Version:References:In-Reply-To:Message-ID:Date:Subject: CC:To:From:Sender:Reply-To:Content-Transfer-Encoding:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=NYm0yv34KiRxkDEzzLLNI07sy4N51XzZGXLsOurtbII=; b=JeVGDyrefxT/EOj4h+OkwYFJuz azBt8kL2l2V4b4rC7miUt+BjQmnQECEa/6HEsqRJh4A3cpTfnn1qV/cIgXA9ntKOvmwx/rA/K2oHM 1Wy5yK1bt04oMvxKaRdxPdh15mZtftQo3+0WPQiu0XwNKI3qwZMVd1WJLMyKLrP2R/o4=; Received: from ns2.fox-it.com ([178.250.144.131]) by sfi-mx-1.v28.lw.sourceforge.com with esmtps (TLSv1:ECDHE-RSA-AES256-SHA:256) (Exim 4.90_1) id 1fmaVz-00B39a-9X for openvpn-devel@lists.sourceforge.net; Mon, 06 Aug 2018 08:05:21 +0000 Received: from FOXDFT52.FOX.local (unknown [10.0.0.129]) by ns2.fox-it.com (Postfix) with ESMTPS id DCFB91AF843 for ; Mon, 6 Aug 2018 10:05:12 +0200 (CEST) Received: from steffan-fox.fox.local (10.0.3.178) by FOXDFT52.FOX.local (10.0.0.129) with Microsoft SMTP Server (TLS) id 15.0.1293.2; Mon, 6 Aug 2018 10:05:12 +0200 From: Steffan Karger To: Date: Mon, 6 Aug 2018 10:05:07 +0200 Message-ID: <1533542707-9100-1-git-send-email-steffan.karger@fox-it.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: References: MIME-Version: 1.0 X-ClientProxiedBy: FOXDFT52.FOX.local (10.0.0.129) To FOXDFT52.FOX.local (10.0.0.129) X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. See http://spamassassin.org/tag/ for more details. -0.0 SPF_PASS SPF: sender matches SPF record X-Headers-End: 1fmaVz-00B39a-9X Subject: [Openvpn-devel] [PATCH v5 2/7] tls-crypt-v2: add specification to doc/ X-BeenThere: openvpn-devel@lists.sourceforge.net X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: openvpn-devel-bounces@lists.sourceforge.net X-getmail-retrieved-from-mailbox: Inbox This is a preliminary description of tls-crypt-v2. It should give a good impression about the reasoning and design behind tls-crypt-v2, but might need some polishing and updating. Signed-off-by: Steffan Karger --- v3: Include length in WKc v4: Clarify metadata handling v5: Typo fixes (thanks tincanteksup) doc/tls-crypt-v2.txt | 182 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 doc/tls-crypt-v2.txt diff --git a/doc/tls-crypt-v2.txt b/doc/tls-crypt-v2.txt new file mode 100644 index 0000000..ec13443 --- /dev/null +++ b/doc/tls-crypt-v2.txt @@ -0,0 +1,182 @@ +Client-specific tls-crypt keys (--tls-crypt-v2) +=============================================== + +This document describes the ``--tls-crypt-v2`` option, which enables OpenVPN +to use client-specific ``--tls-crypt`` keys. + +Rationale +--------- + +``--tls-auth`` and ``tls-crypt`` use a pre-shared group key, which is shared +among all clients and servers in an OpenVPN deployment. If any client or +server is compromised, the attacker will have access to this shared key, and it +will no longer provide any security. To reduce the risk of losing pre-shared +keys, ``tls-crypt-v2`` adds the ability to supply each client with a unique +tls-crypt key. This allows large organisations and VPN providers to profit +from the same DoS and TLS stack protection that small deployments can already +achieve using ``tls-auth`` or ``tls-crypt``. + +Also, for ``tls-crypt``, even if all these peers succeed in keeping the key +secret, the key lifetime is limited to roughly 8000 years, divided by the +number of clients (see the ``--tls-crypt`` section of the man page). Using +client-specific keys, we lift this lifetime requirement to roughly 8000 years +for each client key (which "Should Be Enough For Everybody (tm)"). + + +Introduction +------------ + +``tls-crypt-v2`` uses an encrypted cookie mechanism to introduce +client-specific tls-crypt keys without introducing a lot of server-side state. +The client-specific key is encrypted using a server key. The server key is the +same for all servers in a group. When a client connects, it first sends the +encrypted key to the server, such that the server can decrypt the key and all +messages can thereafter be encrypted using the client-specific key. + +A wrapped (encrypted and authenticated) client-specific key can also contain +metadata. The metadata is wrapped together with the key, and can be used to +allow servers to identify clients and/or key validity. This allows the server +to abort the connection immediately after receiving the first packet, rather +than performing an entire TLS handshake. Aborting the connection this early +greatly improves the DoS resilience and reduces attack service against +malicious clients that have the ``tls-crypt`` or ``tls-auth`` key. This is +particularly relevant for large deployments (think lost key or disgruntled +employee) and VPN providers (clients are not trusted). + +To allow for a smooth transition, ``tls-crypt-v2`` is designed such that a +server can enable both ``tls-crypt-v2`` and either ``tls-crypt`` or +``tls-auth``. This is achieved by introducing a P_CONTROL_HARD_RESET_CLIENT_V3 +opcode, that indicates that the client wants to use ``tls-crypt-v2`` for the +current connection. + +For an exact specification and more details, read the Implementation section. + + +Implementation +-------------- + +When setting up a tls-crypt-v2 group (similar to generating a tls-crypt or +tls-auth key previously): + +1. Generate a tls-crypt-v2 server key using OpenVPN's ``--genkey``. This key + contains 4 512-bit keys, of which we use: + + * the first 256 bits of key 1 as AES-256-CTR encryption key ``Ke`` + * the first 256 bits of key 2 as HMAC-SHA-256 authentication key ``Ka`` + +2. Add the tls-crypt-v2 server key to all server configs + (``tls-crypt-v2 /path/to/server.key``) + + +When provisioning a client, create a client-specific tls-crypt key: + +1. Generate 2048 bits client-specific key ``Kc`` + +2. Optionally generate metadata + + The first byte of the metadata determines the type. The initial + implementation supports the following types: + + 0x00 (USER): User-defined free-form data. + 0x01 (TIMESTAMP): 64-bit network order unix timestamp of key generation. + + The timestamp can be used to reject too-old tls-crypt-v2 client keys. + + User metadata could for example contain the users certificate serial, such + that the incoming connection can be verified against a CRL. + + If no metadata is supplied during key generation, openvpn defaults to the + TIMESTAMP metadata type. + +3. Create a wrapped client key ``WKc``, using the same nonce-misuse-resistant + SIV construction we use for tls-crypt: + + ``len = len(Kc || metadata)`` (16 bit, network byte order) + + ``T = HMAC-SHA256(Ka, len || Kc || metadata)`` + + ``IV = 128 most significant bits of T`` + + ``WKc = T || AES-256-CTR(Ke, IV, Kc || metadata) || len`` + +4. Create a tls-crypt-v2 client key: PEM-encode ``Kc || WKc`` and store in a + file, using the header ``-----BEGIN OpenVPN tls-crypt-v2 client key-----`` + and the footer ``-----END OpenVPN tls-crypt-v2 client key-----``. (The PEM + format is simple, and following PEM allows us to use the crypto lib function + for en/decoding.) + +5. Add the tls-crypt-v2 client key to the client config + (``tls-crypt-v2 /path/to/client-specific.key``) + + +When setting up the openvpn connection: + +1. The client reads the tls-crypt-v2 key from its config, and: + + 1. loads ``Kc`` as its tls-crypt key, + 2. stores ``WKc`` in memory for sending to the server. + +2. To start the connection, the client creates a P_CONTROL_HARD_RESET_CLIENT_V3 + message, wraps it with tls-crypt using ``Kc`` as the key, and appends + ``WKc``. (``WKc`` must not be encrypted, to prevent a chicken-and-egg + problem.) + +3. The server receives the P_CONTROL_HARD_RESET_CLIENT_V3 message, and + + 1. reads the WKc length field from the end of the message, and extracts WKc + from the message + 2. unwraps ``WKc`` + 3. uses unwrapped ``Kc`` to verify the remaining + P_CONTROL_HARD_RESET_CLIENT_V3 message's (encryption and) authentication. + + The message is dropped and no error response is sent when either 3.1, 3.2 or + 3.3 fails (DoS protection). + +4. Server optionally checks metadata using a --tls-crypt-v2-verify script + + This allows early abort of connection, *before* we expose any of the + notoriously dangerous TLS, X.509 and ASN.1 parsers and thereby reduces the + attack surface of the server. + + The metadata is checked *after* the OpenVPN three-way handshake has + completed, to prevent DoS attacks. (That is, once the client has proved to + the server that it possesses Kc, by authenticating a packet that contains the + session ID picked by the server.) + + A server should not send back any error messages if metadata verification + fails, to reduce attack surface and maximize DoS resilience. + +6. Client and server use ``Kc`` for (un)wrapping any following control channel + messages. + + +Considerations +-------------- + +To allow for a smooth transition, the server implementation allows +``tls-crypt`` or ``tls-auth`` to be used simultaneously with ``tls-crypt-v2``. +This specification does not allow simultaneously using ``tls-crypt-v2`` and +connections without any control channel wrapping, because that would break DoS +resilience. + +WKc includes a length field, so we leave the option for future extension of the +P_CONTROL_HEAD_RESET_CLIENT_V3 message open. (E.g. add payload to the reset to +indicate low-level protocol features.) + +``tls-crypt-v2`` uses fixed crypto algorithms, because: + + * The crypto is used before we can do any negotiation, so the algorithms have + to be predefined. + * The crypto primitives are chosen conservatively, making problems with these + primitives unlikely. + * Making anything configurable adds complexity, both in implementation and + usage. We should not add any more complexity than is absolutely necessary. + +Potential ``tls-crypt-v2`` risks: + + * Slightly more work on first connection (``WKc`` unwrap + hard reset unwrap) + than with ``tls-crypt`` (hard reset unwrap) or ``tls-auth`` (hard reset auth). + * Flexible metadata allow mistakes + (So we should make it easy to do it right. Provide tooling to create client + keys based on cert serial + CA fingerprint, provide script that uses CRL (if + available) to drop revoked keys.)