From c612fb7075a8662590ec26e275ce8f94884458d4 Mon Sep 17 00:00:00 2001 From: Jean-Paul Calderone Date: Mon, 14 May 2018 14:30:34 -0400 Subject: [PATCH] initial pass over security section --- docs/proposed/http-storage-node-protocol.rst | 105 +++++++++++++++++++ docs/proposed/index.rst | 1 + 2 files changed, 106 insertions(+) create mode 100644 docs/proposed/http-storage-node-protocol.rst diff --git a/docs/proposed/http-storage-node-protocol.rst b/docs/proposed/http-storage-node-protocol.rst new file mode 100644 index 000000000..60e1afd9e --- /dev/null +++ b/docs/proposed/http-storage-node-protocol.rst @@ -0,0 +1,105 @@ +.. -*- coding: utf-8 -*- + +HTTP Storage Node Protocol +========================== + +The target audience for this document is Tahoe-LAFS developers. +After reading this document, +one should expect to understand how Tahoe-LAFS clients interact over the network with Tahoe-LAFS storage nodes. + +Security +-------- + +Requirements +~~~~~~~~~~~~ + +A client node relies on a storage node to persist certain data until a future retrieval request is made. +In this way, the node is vulnerable to attacks which cause the data not to be persisted. +Though this vulnerability can be mitigated by including redundancy in the share encoding parameters for stored data, it is still sensible to attempt to minimize unnecessary vulnerability to this attack. + +One way to do this is for the client to be confident it the storage node with which it is communicating is really the expected node. +Therefore, the protocol must include some means for cryptographically verifying the identify of the storage node. +The initialization of the client with the correct identity information is out of scope for this protocol +(the system may be trust-on-first-use, there may be a third-party identity broker, etc). + +With confidence that communication is proceeding with the intended storage node, +it must also be possible to trust that data is exchanged without modification. +That is, the protocol must include some means to cryptographically verify the integrity of exchanged messages. + +Solutions +~~~~~~~~~ + +Communication with the storage node will take place using TLS 1.2 [#]_. + + * The storage node will present a certificate proving its identity. + * The certificate will include a ``subjectAltName`` containing ... [#]_. + * The certificate will be signed by an entity known to and trusted by the client. + This entity will *not* be a standard web-focused Certificate Authority. + +When connecting to a storage node, +the client will take the following steps to gain confidence it has reached the intended peer: + + * It will perform the usual cryptographic verification of the certificate presented by the storage server + (that is, + that the certificate itself is well-formed, + that the signature it carries is valid, + that the signature was created by a "trusted entity"). + * It will consider the only "trusted entity" to be an entity explicitly configured for the intended storage node + (specifically, it will not considered the standard web-focused Certificate Authorities to be trusted). + * It will check the ``subjectAltName`` against ... [#]_. + +To further clarify, consider this example. +Alice operates a storage node. +Alice generates a Certificate Authority certificate and secures the private key appropriately. +Alice generates a Storage Node certificate and signs it with the Certificate Authority certificate's private key. +Alice prints out the Certificate Authority certificate and storage node URI [#]_ and hands it to Bob. +Bob creates a client node. +Bob configures the client node with the storage node URI and the Certificate Authority certificate received from Alice. + +Bob's client node can now perform a TLS handshake with a server at the address indicated by the storage node URI. +Following the above described validation procedures, +Bob's client node can determine whether it has reached Alice's storage node or not. + +Additionally, +by continuing to interact using TLS, +Bob's client and Alice's storage node are assured of the integrity of the communication. + +Transition +~~~~~~~~~~ + +Storage nodes already possess an x509 certificate. +This is used with Foolscap to provide the same security properties described in the above requirements section. +There are some differences. + + * The certificate is self-signed. + * The certificate has a ``commonName`` of "newpb_thingy". + * The validity of the certificate is determined by checking the certificate digest against a value carried in the fURL. + Only a correctly signed certificate with a matching digest is accepted. + +A mixed-protocol storage node should: + + * Start the Foolscap server as it has always done. + * Start a TLS server dispatching to an HTTP server. + * Use the same certificate as the Foolscap server uses. + * Accept anonymous client connections. + +A mixed-protocol client node should: + + * If it is configured with a storage URI, connect using HTTP over TLS. + * If it is configured with a storage fURL, connect using Foolscap. + If the server version indicates support for the new protocol: + * Attempt to connect using the new protocol. + * Drop the Foolscap connection if this new connection succeeds. + +Client node implementations could cache a successful protocol upgrade. +This would avoid the double connection on subsequent startups. +This is left as a decision for the implementation, though. + +.. [#] What are best practices regarding TLS version? + Would a policy of "use the newest version shared between the two endpoints" be better? + Is it necessary to specify more than a TLS version number here? + For example, should we be specifying a set of ciphers as well? + Or is that a quality of implementation issue rather than a protocol specification issue? +.. [#] TODO +.. [#] TODO +.. [#] URL? IRI? diff --git a/docs/proposed/index.rst b/docs/proposed/index.rst index 3211b317f..a052baeff 100644 --- a/docs/proposed/index.rst +++ b/docs/proposed/index.rst @@ -18,3 +18,4 @@ index only lists the files that are in .rst format. magic-folder/remote-to-local-sync magic-folder/user-interface-design magic-folder/multi-party-conflict-detection + http-storage-node-protocol