On 04/12/2016 07:27 AM, Alex Bligh wrote: > * Call out TLS into a separate section > > * Add details of the TLS protocol itself > > * Emphasise that actual TLS session initiation (i.e. the TLS handshake) can > be initiated from either side (as required by the TLS standard I believe > and as actually works in practice) > > * Clarify what is a requirement on servers, and what is a requirement on > clients, separately, specifying their behaviour in a single place > in the document. > > * Document the three possible modes of operation of a server. > > * Add text defining what 'terminate the session' means during > negotiation, and when it is available. > > Signed-off-by: Alex Bligh <alex@...872...> > --- > @@ -286,6 +303,287 @@ S: (*length* bytes of data if the request is of type `NBD_CMD_READ`) > This reply type MUST NOT be used except as documented by the > experimental `STRUCTURED_REPLY` extension; see below. > > +## TLS support > + This is appropriate as an H2 header... > + > +### Server-side requirements ...this is appropriate as H3... > + > +## Client-side requirements ...but this should also be H3. s/##/###/ > + > +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 terminate the session 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 session to TLS. If it receives `NBD_REP_ERR_UNSUP`, > +`NBD_REP_ERR_POLICY` or any other error in response, it indicates > +that the server cannot or will not upgrade the session to TLS, > +and therefore the client MUST either continue the session > +without TLS, or terminate the session. > + > +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 possibility of options being > +compromised by a Man-in-the-Middle attack. Note that the > +`NBD_OPT_STARTTLS` itself may be compromised - see 'downgrade > +attacks' for more details. For this reason, a client which only > +wishes to use TLS SHOULD terminate the session 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 terminate the > +session as by this stage it is too late to continue without TLS. > + > +If the client receives an `NBD_REP_ERR_TLS_REQD` in response > +to any option, it implies that this option cannot be executed > +unless a TLS upgrade is performed. If the option is any > +option other than `NBD_OPT_INFO` or `NBD_OPT_GO`, this > +indicates that no option will succeed unless a TLS upgrade > +is performed; the client MAY therefore choose to issue > +an `NBD_OPT_STARTTLS`, or MAY terminate the session (if > +for instance it does not support TLS or does not have > +appropriate credentials for this server). If the client > +receives `NBD_REP_ERR_TLS_REQD` in response to > +`NBD_OPT_INFO` or `NBD_OPT_GO` this indicates that the > +export referred to within the option is either non-existent > +or requires TLS; the client MAY therefore choose to issue > +an `NBD_OPT_STARTTLS`, MAY terminate the session (if > +for instance it does not support TLS or does not have > +appropriate credentials for this server), or MAY continue > +in another manner without TLS, for instance by querying > +or using other exports. > + > +If a client supports TLS, it SHOULD also support the INFO > +extension, and SHOULD use `NBD_OPT_GO` if available in place > +of `NBD_OPT_EXPORT_NAME`. The reason for this is set out in > +the final paragraphs of the sections under 'FORCEDTLS' > +and 'SELECTIVETLS': this gives an opportunity for the > +server to transmit that an error going into transmission > +mode is due to the client's failure to initiate TLS, > +and the fact that the client may obtain information about > +which exports are TLS-only through `NBD_OPT_INFO`. > + > +### Security considerations > + > +#### TLS versions > + > +NBD implementations supporting TLS MUST support TLS version 1.2, > +SHOULD support any later versions. NBD implementations > +MAY support older versions but SHOULD NOT do so by default > +(i.e. they SHOULD only be available by a configuration change). > +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. > + > +#### Protocol downgrade attacks > + > +A danger inherent in any scheme relying on the negotiation > +of whether TLS should be employed is downgrade attacks within > +the NBD protocol. > + > +There are two main dangers: > + > +* A Man-in-the-Middle (MitM) hijacks a session and impersonates > + the server (possibly by proxying it) claiming not to support > + TLS. In this manner, the client is confused into operating > + in a plain-text manner with the MitM (with the session possibly > + being proxied in plain-text to the server using the method > + below). > + > +* The MitM hijacks a session and impersonates the client > + (possibly by proxying it) claiming not to support TLS. In > + this manner the server is confused into operating in a plain-text > + manner with the MitM (with the session being possibly > + proxied to the client with the method above). > + > +With regard to the first, any client that does not wish > +to be subject to potential downgrade attack SHOULD ensure > +that if a TLS endpoint is specified by the client, it > +ensures that TLS is negotiated prior to sending or > +requesting sensitive data. To recap, the client MAY send > +`NBD_OPT_STARTTLS` at any point during option haggling, > +and MAY terminate the session if `NBD_REP_ACK` is not > +provided. > + > +With regard to the second, any server that does not wish > +to be subject to a potential downgrade attack SHOULD either > +used FORCEDTLS mode, or should force TLS on those exports > +it is concerned about using SELECTIVE mode and TLS-only > +exports. It is not possible to avoid downgrade attacks > +on exports which may be served either via TLS or in plain > +text unless the client insists on TLS. > + > +### Status > + > +This functionality has not yet been implemented by the reference > +implementation, but was implemented by qemu and subsequently > +by other users, so has been moved out of the "experimental" section. > + > ## Values > > This section describes the value and meaning of constants (other than > @@ -366,7 +664,7 @@ of the newstyle negotiation. > Data: String, name of the export, as free-form text. > The length of the name is determined from the option header. If the > chosen export does not exist or requirements for the chosen export > - are not met (e.g., the client did not negotiate TLS for an export > + are not met (e.g., the client did not initiate TLS for an export > where the server requires it), the server should close the > connection. > > @@ -391,7 +689,9 @@ of the newstyle negotiation. > - `NBD_OPT_LIST` (3) > > Return a number of `NBD_REP_SERVER` replies, one for each export, > - followed by `NBD_REP_ACK`. > + followed by `NBD_REP_ACK`. The server SHOULD omit entries from this > + list if TLS has not been negotiated, the server is operating in > + SELECTIVETLS mode, and the entry concerned is a TLS-only export. > > - `NBD_OPT_PEEK_EXPORT` (4) > > @@ -400,21 +700,15 @@ of the newstyle negotiation. > > - `NBD_OPT_STARTTLS` (5) > > - The client wishes to initiate TLS. If the server replies with > - `NBD_REP_ACK`, then the client should immediately initiate a TLS > - handshake and continue the negotiation in the encrypted channel. If > - the server is unwilling to perform TLS, it should reply with > - `NBD_REP_ERR_POLICY`. For backwards compatibility, a client should > - also be prepared to handle `NBD_REP_ERR_UNSUP`. If the client sent > - along any data with the request, the server should send back > - `NBD_REP_ERR_INVALID`. The client MUST NOT send this option if > - it has already negotiated TLS; if the server receives > - `NBD_OPT_STARTTLS` when TLS has already been negotiated, the server > - MUST send back `NBD_REP_ERR_INVALID`. > - > - This functionality has not yet been implemented by the reference > - implementation, but was implemented by qemu so has been moved out of > - the "experimental" section. > + The client wishes to initiate TLS. > + > + The server MUST either reply with `NBD_REP_ACK` after which > + point the connection is upgraded to TLS, or reply with > + `NBD_REP_ERR_POLICY` (or if it does not support the option > + at all, `NBD_REP_ERR_UNSUP`, or if TLS has already been > + negotiated, `NBD_REP_ERR_INVALID`). > + > + See the section on TLS above for further details. > > - `NBD_OPT_INFO` (6) > > @@ -489,20 +783,10 @@ case that data is an error message string suitable for display to the user. > * `NBD_REP_ERR_TLS_REQD` (2^31 + 5) > > The server is unwilling to continue negotiation unless TLS is > - negotiated first. A server MUST NOT send this error if it has one or > - more exports that do not require TLS; not even if the client indicated > - interest (by way of `NBD_OPT_PEEK_EXPORT`) in an export which requires > - TLS. > - > - If this reply is used, servers SHOULD send it in reply to each and every > - unencrypted `NBD_OPT_*` message (apart from `NBD_OPT_STARTTLS`). > - > - This functionality has not yet been implemented by the reference > - implementation, but was implemented by qemu so has been moved out of > - the "experimental" section. > - > - The experimental `INFO` extension makes small but compatible > - changes to the semantics of this error message; see below. > + initiated first. In the case of `NBD_OPT_INFO` and `NBD_OPT_GO` > + this unwillingness MAY (depending on the TLS mode) be limited > + to the export in question. See the section on TLS above for > + further details. > > * `NBD_REP_ERR_UNKNOWN` (2^31 + 6) > > @@ -735,13 +1019,13 @@ Therefore these commands share common documentation. > - `NBD_REP_ERR_UNKNOWN`: The chosen export does not exist on this > server. > - `NBD_REP_ERR_TLS_REQD`: The server does not wish to export this > - block device unless the client negotiates TLS first. > + block device unless the client initiates TLS first. > - `NBD_REP_SERVER`: The server accepts the chosen export. > > - Additionally, if TLS has not been negotiated, the server MAY reply > + Additionally, if TLS has not been initiated, the server MAY reply > with `NBD_REP_ERR_TLS_REQD` (instead of `NBD_REP_ERR_UNKNOWN`) > to requests for exports that are unknown. This is so that clients > - that have not negotiated TLS cannot enumerate exports. > + that have not initiated TLS cannot enumerate exports. > > In the case of `NBD_REP_SERVER`, the message's data takes on a different > interpretation than the default (so as to provide additional > -- Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
Attachment:
signature.asc
Description: OpenPGP digital signature