[Nbd] Thoughts about the handshake protocol

[Goswin v. B. <gos...@we...>]

Hi,

revently it was mentioned that the new-style handshake has some problems
and needs some fixing up for the future. So I wanted to collect some
thoughts about this to maybe spark a redesign. Turned out to describe
pretty much the complete handshake. Let me know what you think:

----------------------------------------------------------------------
Currently the handshake starts with:

S: "NBDMAGIC" (as in the old style handshake)
S: 0x49484156454F5054 (note different magic number)
S: 16 bits of zero (reserved for future use)
C: 32 bits of zero (reserved for future use)

So the server identifies itself as NBD server. The client though does
not identify itself but just starts sending payload.

Now what are those 16/32 bit of zero for? Some sort of version number or
bitfield of options? The problem I have with them is that they allow no
room for compromise. If the client is not at least as new as the server
it will not understand all the bits the server sends. The only option
the client then has it to give up.

Next the option haggling is a good idea. But it lacks a way for the
server to say when it doesn't understand an option and for the client to
say there are no more option comming.

----------------------------------------------------------------------
So I would like to get a bit more flexibility into this:

S: "NBDMAGIC" (as in the old style handshake)
S: 8 byte magic number
S: 16 bits required features
S: 48 bits offer optional features

C: "NBDMAGIC"
C: 8 byte magic number
C: 16 bits ACK required features
C: 48 bits enable optional features

A client MUST understand all required features set by the server. For
now all bits would be reserved and 0 and any incompatible change would
allocate one bit and set it. Hopefully there won't be any. Bit 15 of
required features can be reserved to indicate another 8 byte of feature
bits follow. The client acknowledges that it understands all the
required features by echoing them back. Again bit 15 of the required
features would indicate another 8 byte of feature bits follow the reply
just like in the servers hello.

Optional features will be set by the server to indicate it supports a
certain feature (e.g. FUA or FLUSH). The client responds with a bitfield
indicating those features it wishes to use. Any unknown feature must be
disabled (set to 0) and this must be safe to do so. Only bits set by the
server might be returned set by the client. Only those features set by
both server and client MAY be used.

Example:
Required features: AUTH (user/pass authentication required, see below)
Optional features: FLUSH, FUA, SYNC, READ_ONLY, AUTOSYNC (sync until
first FLUSH/FUA)


This completes the first part of the handshake and now server and client
know how to talk to each other. It also takes care of any trivial
options without arguments (like FUA/FLUSH).

Next the client negotiates with the server. This is more flexible doing
one option as a time and allowing for additional arguments to each
option and reply:

C: 8 byte magic
C: 16 bit option number
C: 16 bit MUST be zero
C: 32 bit length of option data
C: len byte of data

S: 8 byte magic
S: 16 bit option number
S: 16 bit error code
S: 32 bit length of reply
S: len byte of data

On success error code must be 0 and the data contains the responce data
if any. On error the data optionally contains text describing the error
in more detail. The client can decide wether this is fatal or if it
wishes to continue without. The possible error codes should include
UNKNOWN_OPTION so the server can indicate it doesn't know about it.

List of options:

* NBD_OPT_EXPORT_NAME (required before NBD_OPT_END/START)
  Payload is the name of the export the client wishes to access

  Reply contains the size of the export in bytes, prefered blocksize and
  flags (e.g. read-only, sync).

* NBD_OPT_LIST_EXPORTS
  No payload.

  Reply with list of available exports. (name, size, blocksize, flags?)

* NBD_OPT_USER (required if AUTH option is set)
  Payload is user name.

  Reply is salt for PASS.

* NBD_OPT_PASS (required if AUTH option is set)
  Payload is hash of password using given salt.

  Reply has no payload.

* NBD_OPT_END/START
  No payload. The client is ready to start the device.

  Reply has no payload. Can fail with EINVAL "export name missing".

  On success no further options MUST be send and the protocol switches
  over to NBD device operations.

A server MAY process one option at a time, blocking till the responce
has been send, and a client MAY pipeline options if it does so
non-blocking.

Note: the AUTH and user/pass thing is just to show what could be
done. Don't take that seriously.

MfG
        Goswin