From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:48523) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aoExK-0001OG-88 for qemu-devel@nongnu.org; Thu, 07 Apr 2016 14:47:06 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aoEtp-0007xV-OO for qemu-devel@nongnu.org; Thu, 07 Apr 2016 14:43:30 -0400 Received: from lists.gnu.org ([2001:4830:134:3::11]:47221) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aoEtp-0007xM-KJ for qemu-devel@nongnu.org; Thu, 07 Apr 2016 14:43:25 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:56276) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aoEBb-0002g4-Vn for qemu-devel@nongnu.org; Thu, 07 Apr 2016 13:57:45 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aoEBX-0003Em-6J for qemu-devel@nongnu.org; Thu, 07 Apr 2016 13:57:43 -0400 Received: from mx1.redhat.com ([209.132.183.28]:59978) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aoEBW-0003Ea-Us for qemu-devel@nongnu.org; Thu, 07 Apr 2016 13:57:39 -0400 References: <1460043181-62255-1-git-send-email-alex@alex.org.uk> From: Eric Blake Message-ID: <57069F90.7050003@redhat.com> Date: Thu, 7 Apr 2016 11:57:36 -0600 MIME-Version: 1.0 In-Reply-To: <1460043181-62255-1-git-send-email-alex@alex.org.uk> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="qNeXrFSrs0eQMQEva1OpiHBpWVG22sfkB" Subject: Re: [Qemu-devel] [PATCHv2] Improve documentation for TLS List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Alex Bligh , Wouter Verhelst Cc: "nbd-general@lists.sourceforge.net" , "qemu-devel@nongnu.org" , "Daniel P. Berrange" This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --qNeXrFSrs0eQMQEva1OpiHBpWVG22sfkB Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 04/07/2016 09:33 AM, Alex Bligh wrote: > * Call out TLS into a separate section >=20 > * Add details of the TLS protocol itself >=20 > * Emphasise that actual TLS session initiation (i.e. the TLS handshake)= can > be initiated from either side (as required by the TLS standard I beli= eve > and as actually works in practice) >=20 > * Clarify what is a requirement on servers, and what is a requirement o= n > clients, separately, specifying their behaviour in a single place > in the document. >=20 > * Document the four possible modes of operation of a server. >=20 > Signed-off-by: Alex Bligh > --- > doc/proto.md | 336 +++++++++++++++++++++++++++++++++++++++++++++++++++= ++------ > 1 file changed, 302 insertions(+), 34 deletions(-) > +++ b/doc/proto.md > @@ -286,6 +286,289 @@ S: (*length* bytes of data if the request is of t= ype `NBD_CMD_READ`) > This reply type MUST NOT be used except as documented by the > experimental `STRUCTURED_REPLY` extension; see below. > =20 > +## TLS support > + > +The NBD protocol supports TLS via negotiation with the `NBD_OPT_STARTT= LS` Worth spelling out the TLS acronym here, and/or making this a link to a relevant web page? Not sure what the best page would be, though. > +option. This is performed as an in-session upgrade. Below the term > +'negotiation' is used to refer to the sending and receiving of > +NBD commands, and the term 'initiation' of TLS is used to refer to > +the actual upgrade to TLS. > + > +### Certificates, authentication and authorisation > + > +This standard does not specify what encryption, certification > +and signature algorithms are used. This standard does not > +specify authentication and authorisation (for instance > +whether client and/or server certificates are required and > +what they should contain); this is implementation dependent. > + > +TLS requires fixed newstyle negotiation to have completed. Sounds awkward - fixed newstyle flags are advertised by the server and replied by the client, but overall negotiation is not completed until all client options have been sent. Maybe: TLS requires both server and client to support fixed newstyle negotiation= =2E > + > +### Server-side requirements > + > +There are four modes of operation for a server. The > +server MUST support one of these modes. > + > +The server MUST operate in NOTLS mode unless the server > +set flag NBD_FLAG_FIXED_NEWSTYLE and the client replied > +with NBD_FLAG_C_FIXED_NEWSTYLE in the fixed newstyle > +negotiation. Good. > + > +These modes of operations are described in detail below. > + > +#### NOTLS mode > + > +If the server receives `NBD_OPT_STARTTLS` it MUST respond with > +`NBD_REP_ERR_UNSUP`. The server MUST NOT respond to any > +command with `NBD_REP_ERR_TLS_REQD`. Is 'option request' a better word than 'command'? > +#### FORCEDTLS mode > + > +If the server receives `NBD_OPT_STARTTLS` it MUST reply with > +`NBD_REP_ACK` and initiate TLS as set out under 'OPTIONALTLS' > +above. > + > +If the server receives any other option, including `NBD_OPT_INFO`, > +and unsupported options, it SHOULD reply with `NBD_REP_ERR_TLS_REQD` I'm thinking MUST is better than SHOULD in this mode (and matches qemu's implementation). no comma after `NBD_OPT_INFO` > +if TLS has not been initiated; `NBD_OPT_INFO` is included as in this s/;/./ > +mode, all exports are TLS-only. If the server receives a request to > +enter transmission mode via `NBD_OPT_EXPORT_NAME` when TLS has not > +been initiated, then as this request cannot error, it MUST > +disconnect the connection. If the server receives a request to > +enter transmission mode via `NBD_OPT_GO` when TLS has not been > +initiated, it MUST error with `NBD_REP_ERR_TLS_REQD`. > +#### SELECTIVETLS mode > + > +If the server receives `NBD_OPT_STARTTLS` it MUST reply with > +`NBD_REP_ACK` and initiate TLS as set out under 'OPTIONALTLS' > +above. > + > +If the server receives any other option except `NBD_OPT_INFO`, > +it MUST NOT reply with `NBD_REP_ERR_TLS_REQD`. If the Should that be `NBD_OPT_INFO` or `NBD_OPT_GO`, since we want to allow NBD_OPT_GO to fail with ERR_TLS_REQD on a TLS-required export? > +server receives `NBD_OPT_INFO` and TLS has not been > +initiated, it MAY reply with `NBD_REP_ERR_TLS_REQD` if that > +export is non-existent, and MUST reply with `NBD_REP_ERR_TLS_REQD` > +if that export is TLS-only. > + > +If the server receives a request to enter transmission mode > +via `NBD_OPT_EXPORT_NAME` on a TLS-only export when TLS has not > +been initiated, then as this request cannot error, it MUST > +disconnect the connection. If the server receives a request to > +enter transmission mode via `NBD_OPT_GO` when TLS has not been via `NBD_OPT_GO` on a TLS-only export > +initiated, it MUST error with `NBD_REP_ERR_TLS_REQD`. Maybe put this paragraph before the one about "any other option", and then that paragraph can limit its exclusion to NBD_OPT_INFO. > + > +The server MUST NOT send `NBD_REP_ERR_TLS_REQD` in reply to > +any command if TLS has already been neogitated. The server s/neogitated/negotiated/ > +MUST NOT send `NBD_REP_ERR_TLS_REQD` in response to any > +option other than `NBD_OPT_INFO` or `NBD_OPT_GO`, and > +only in those cases in respect of a TLS-only or non-existent > +export. > + > + > +## Client-side requirements > + > +If the client supports TLS at all, it MUST be prepared > +to deal with servers operating in any of the above modes. > +Notwithstanding, a client MAY always disconnect or > +refuse to connect to a particular export if TLS is > +not available and the user requires TLS. > + > +The client MUST NOT issue `NBD_OPT_STARTTLS` unless the server > +set flag NBD_FLAG_FIXED_NEWSTYLE and the client replied > +with NBD_FLAG_C_FIXED_NEWSTYLE in the fixed newstyle > +negotiation. > + > +The client MUST NOT issue `NBD_OPT_STARTTLS` if TLS has already > +been initiated. > + > +Subject to the above two limitations, the client MAY send > +`NBD_OPT_STARTTLS` at any time to initiate a TLS session. If the > +client receives `NBD_REP_ACK` in response, it MUST immediately > +upgrade the connection to TLS. If it receives `NBD_ERR_REP_UNSUP` > +in response or any other error, it indicates that the server cannot > +or will not upgrade the connection to TLS and therefore MUST either > +continue the connection without TLS, or disconnect. > + > +A client that prefers to use TLS irrespective of whether > +the server makes TLS mandatory SHOULD send `NBD_OPT_STARTTLS` > +as the first option. This will ensure option haggling is subject > +to TLS, and will thus prevent the possibilty of options being s/possibilty/possibility/ > +compromised by a MitM attack. Note that the `NBD_OPT_STARTTLS` You spell out MitM later so I'm not too worried, but maybe it's worth floating the definition up higher. > +itself may be compromised - see 'downgrade attacks' for > +more details. For this reasons a client which only wishes s/reasons/reason/ > +to use TLS SHOULD disconnect if the `NBD_OPT_STARTTLS` > +replies with an error. > + > +If the TLS handshake is unsuccessful (for instance the server's > +certificate does not validate) the client MUST disconnect as > +by this stage it is too late to continue without TLS. > + > + > +### Security considerations > + > +#### TLS versions > + We crossed mail; I had some reviews on the security implications that still need fixing in v3, which I won't repeat here. > +NBD implementations supporting TLS MUST support TLS version 1.2, > +SHOULD support any later versions, and MAY support older versions. > +Older versions SHOULD NOT be used where there is a risk of security > +problems with those older versions or of a downgrade attack > +against TLS versions. > + --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --qNeXrFSrs0eQMQEva1OpiHBpWVG22sfkB Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJXBp+QAAoJEKeha0olJ0Nq728H/3nFYnVb0Oy0q45Uky6Kvn+A L0qAPt4e/NwUMA701nlMOC9TcaZPSczHNVpjNg0l0+o0sT0GvpqG2y0bt0EL6THy iYwF9PaH1Ls7qaIVrbEOgdDq568dT4neLWUPDlMCXcWkl9rYPqf7FS/sLHpanijz 63XDKn1ZChG1UvZqxPt7PQTuB+kfkpfQMFSDgjNu2z0bZBUbDYdszsAFDAoaQMFC TWaO4uLzfZdh04NYHQE/KrCB3kTATidQNW0MpqKiZpoiFbQyWzD3rXjKCk2K0OK+ rVM5P/nMTabHW7l09fwDAXFRw0gtGxnlCxBg0SDRMYeD+ApfVXiw95nYb9Pac6k= =JEDE -----END PGP SIGNATURE----- --qNeXrFSrs0eQMQEva1OpiHBpWVG22sfkB--