Re: [Qemu-devel] [Nbd] [PATCHv8] Improve documentation for TLS

[Alex Bligh]

Wouter,

On 11 Apr 2016, at 07:10, Wouter Verhelst <address@hidden> wrote:

> Mostly there. Final note:
> 
> On Sun, Apr 10, 2016 at 01:47:32PM +0100, Alex Bligh wrote:
>> diff --git a/doc/proto.md b/doc/proto.md
>> index f117394..5005552 100644
>> --- a/doc/proto.md
>> +++ b/doc/proto.md
>> @@ -195,6 +195,13 @@ request before sending the next one of the same type. 
>> The server MAY
>> send replies in the order that the requests were received, but is not
>> required to.
>> 
>> +There is no requirement for the client or server to complete a negotiation
>> +if it does not wish to do so. If the client does not find an export it
>> +is looking for (for instance) it may simply close the TCP connection.
>> +Under certain circumstances either the client or the server may be required
>> +by this document to close the TCP connection. In each case, this is
>> +referred to as 'terminate the session'.
>> +
>> ### Transmission
> 
> NAK. If we have disconnect messages (NBD_OPT_ABORT and NBD_CMD_DISC), it
> makes sense to say that clients should use them. Protocol violations by
> peers are a different matter; but in the general case you should drop a
> connection properly, i.e., by using the relevant "close the connection"
> command.
> 
> (I realize I didn't comment on this earlier, but I changed my mind
> during the discussion about DISC).

This section only relates to the negotiation phase, so really this is
about use (or not) or NBD_OPT_ABORT, not NBD_OPT_DISC.

Your statement is a bit surprising though as far as NBD_OPT_ABORT
is concerned. 

Firstly, there is no way to the *server* to send NBD_OPT_ABORT.
That's what this paragraph was primarily aimed at.

Secondly proto.md has:

> The phase continues until either side closes the connection.

That implies that either the client or the server can initiate the
close.

I thought on this basis its use was entirely optional.

NBD_OPT_ABORT says:

> - `NBD_OPT_ABORT` (2)
> 
>     The client desires to abort the negotiation and close the
>     connection.
> 

I *presume* it has a reply (all the others do). Should a client
wait for the undocumented reply before closing its end of
the connection or not? I must admit the semantics are sufficiently
opaque though I support it server side (with a reply) I would
never sent it client side.

Note also that in some circumstances where I document 'terminate
the session' it's not possible for the client to send an NBD_OPT_ABORT.
The two obvious ones are:

* After NBD_OPT_EXPORTNAME has been issued - if for instance
  the client does not like the flags.

* After NBD_OPT_STARTTLS has been issued and the NBD_REP_ACK
  has been sent, but the TLS handshake itself fails client
  side (for instance the server cert does not work).

Obviously NBD_OPT_ABORT and aborting the connection needs
more clearing up, but I'm loathe to do it in the TLS patch.

In order not to make things worse, how about:

> There is no requirement for the client or server to complete a
> negotiation if it does not wish to do so. Either end may simply
> close the TCP connection (though see below re prior use
> of NBD_OPT_ABORT). Under certain circumstances either
> the client or the server may be required by this document to close
> the TCP connection. In each case, this is referred to as 'terminate
> the session'.
> 
> If the client wishes to terminate the session in the negotiation
> phase, and is not doing so because it is required to do so
> by this document, it SHOULD send NBD_OPT_ABORT first if the protocol
> permits. There are instances where this is impossible, such as after
> an NBD_OPT_EXPORTNAME has been issued, or on an unsuccessful
> negotiation of TLS.  For instance, if the client does not find an
> export it is looking for, it may simply send an NBD_OPT_ABORT
> and close the TCP connection.


-- 
Alex Bligh