Re: [Qemu-devel] [PATCHv9] Improve documentation for TLS

[Eric Blake]

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 <address@hidden>
> ---

> @@ -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

signature.asc
Description: OpenPGP digital signature