From c1aa0626165307a8f0988e04a89b7febd04d59c8 Mon Sep 17 00:00:00 2001 From: Vincent Breitmoser Date: Wed, 7 Jun 2017 01:48:16 +0200 Subject: [PATCH] Created OpenPGP Key Transfer (markdown) --- OpenPGP-Key-Transfer.md | 60 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 OpenPGP-Key-Transfer.md diff --git a/OpenPGP-Key-Transfer.md b/OpenPGP-Key-Transfer.md new file mode 100644 index 0000000..6e10756 --- /dev/null +++ b/OpenPGP-Key-Transfer.md @@ -0,0 +1,60 @@ +# OpenPGP Secret Key Transfer + +This document describes a mechanism for securely transferring OpenPGP secret key material between two devices. +The devices must be able to communicate on a local network, and at least one of the devices must be able to scan a QR-Code displayed by the other. +These requirements are typically fulfilled in a scenario where key material should be transferred from a desktop machine to a phone or vice versa. + +This mechanism relies on two techniques: First, a QR-Code is used for out-of-band communication of authentication and network discovery information. +The actual connection then relies on TLS-PSK for mutually authenticated, forward-secure transport encryption. + +## Session Setup + +A secure session between two devices is set up as follows: + +1. One device generates a preshared key, then opens a TCP port to listen for a single incoming TLS-PSK session. +This device is the "server" device. +2. While in the listening state, the server device displays a QR code that encodes the necessary data to connect to it (see below). +3. Another device scans the QR code, then establishes a TLS-PSK connection to the server device. +This device is the "client" device. + +### Connection Details + +The choice of port the server device listens on is left to the implementation, it is RECOMMENDED to use an automatically assigned one. +The connection MUST be secured with the TLS-PSK protocol. +It MUST also use one of the PSK-authenticated Diffie-Hellman ciphersuites (TLS\_DHE\_PSK\_\* or TLS\_ECDHE\_PSK\_\*). +The preshared key consists of 128 bits of random data, which MUST be obtained from a CSPRNG. +For compatibility, the client SHOULD use the identity hint provided by the server during the TLS handshake as their client identity, or empty string if none was provided. + +The connection details displayed in the QR-Code are encoded as a URI, as such: + +uri = "OPENPGP+SKT://" hex-psk "@" address ":" port +hex-psk = 32HEXDIG +address = IPv4address / "[" IPv6address "]" +port = *DIGIT + +The IPv4address and IPv6address grammars are defined as in https://tools.ietf.org/html/rfc3986#section-3.2.2 +For efficient encoding, all letters (and hexadecimal numbers) in the URI SHOULD be uppercase. + +## Transmitting Data + +The only data that may be sent through an SKT session are ASCII armored secret key blocks, terminated by two newlines. +Both the client and server device are allowed to send data first; the device that first sends data becomes the /active/ device of the session, the other becomes the /passive/ one. +The active device may send further key blocks after the first one, the passive device MUST NOT send any. +The session SHOULD be kept open by the passive device, until dismissed by the user. +Note that the race condition in this behavior is not an issue in practice, since data sent by the then-active device is triggered directly by user input (see below). + +This way of handling sessions enables two distinct user flows: + +- Establish a session, then wait for user input to select keys to send. When keys are received, switch to list of received keys and allow user to import. +- Ask for user input before the connection is established, then send keys immediately after session has been established. + +The former user flow yields an (arguably) better user experience: Establishing a session first not only makes it more transparent to the user how the transfer mechanism works, but also moves most modes of failure to a point in time /before/ the user selects their keys to send. +It also makes expectations more clear in the scenario where the passive device is the server device, since scanning a QR code is typically perceived as an action that receives data, rather than sends. +An implementation that follows the former approach is automatically compatible with the second. +It is RECOMMENDED that implementations take the first approach, unless implementation constraints prescribe the second. + +## Security Considerations + +- transfer is secure, still: designed for usability and compatibility +- only TLS\_DHE\_\* or TLS\_ECDHE\_\* +- doesn't work (by definition) on airgapped devices \ No newline at end of file