From patchwork Tue Apr 5 16:38:56 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alex Bligh X-Patchwork-Id: 8753481 Return-Path: X-Original-To: patchwork-qemu-devel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id E59F7C0553 for ; Tue, 5 Apr 2016 16:39:12 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id DF2E420382 for ; Tue, 5 Apr 2016 16:39:11 +0000 (UTC) Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id C1D002037E for ; Tue, 5 Apr 2016 16:39:10 +0000 (UTC) Received: from localhost ([::1]:38309 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1anU0T-0007NP-Te for patchwork-qemu-devel@patchwork.kernel.org; Tue, 05 Apr 2016 12:39:09 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:46527) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1anU0M-0007NH-74 for qemu-devel@nongnu.org; Tue, 05 Apr 2016 12:39:03 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1anU0H-0000x8-RN for qemu-devel@nongnu.org; Tue, 05 Apr 2016 12:39:02 -0400 Received: from mail.avalus.com ([89.16.176.221]:41199) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1anU0H-0000wh-IR for qemu-devel@nongnu.org; Tue, 05 Apr 2016 12:38:57 -0400 Received: by mail.avalus.com (Postfix) with ESMTPSA id 6CA25C5609B; Tue, 5 Apr 2016 17:38:55 +0100 (BST) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=alex.org.uk; s=mail; t=1459874335; bh=FOCXSxViU49noquoKeIoVCxL+eulCe+OEjOczexyKwA=; h=From:To:Cc:Subject:Date; b=Vu7FfRwecqNZ0lPaXecoTWXlag4/KsGLFojOUT2KXHzIn/N+ZBlPz7VAG8XnO+jd3 yflbH5h8Y2kHJxnRmDQU8P23n93nmEvEwm6+sPCRXcjAnnesT6K1llhkd+WtsBvqHR xILyoEAuQRmcxWPemkbuSa8guCZaz1ByrCGXtjuk= From: Alex Bligh To: Eric Blake , Wouter Verhelst Date: Tue, 5 Apr 2016 17:38:56 +0100 Message-Id: <1459874336-16936-1-git-send-email-alex@alex.org.uk> X-Mailer: git-send-email 1.9.1 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 89.16.176.221 Cc: "nbd-general@lists.sourceforge.net" , "qemu-devel@nongnu.org" , Alex Bligh Subject: [Qemu-devel] [PATCH] Amend NBD_OPT_SELECT and NBD_OPT_GO documentation X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org Sender: qemu-devel-bounces+patchwork-qemu-devel=patchwork.kernel.org@nongnu.org X-Spam-Status: No, score=-6.8 required=5.0 tests=BAYES_00,DKIM_SIGNED, RCVD_IN_DNSWL_HI, T_DKIM_INVALID, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP Amend the NBD_OPT_SELECT and NBD_OPT_GO documentation as follows: * Allow a name to be specified on NBD_OPT_GO * Make clear the rules for default device selection * Remove the provision concerning TLS resetting device selection * Remove NBD_REP_ERR_INVALID as a reply to NBD_OPT_GO as there is now no necessity for a prior NBD_OPT_SELECT * Make it clear NBD_OPT_GO is in effect a better alternative for NBD_OPT_EXPORT_NAME * Make it clear the NBD_OPT_SELECT and NBD_OPT_GO are in essence the same command, save that NBD_OPT_GO puts you into transmission mode if successful. * Clarify permitted option returns outside TLS to prevent export enumeration. * Controversial: remove 'length' 32 bit quantity from NBD_OPT_SELECT (and don't copy it into NBD_OPT_GO) so it looks exactly like NBD_OPT_EXPORT_NAME bar the reply. This length is unnecessary as it's in the option header anyway. Signed-off-by: Alex Bligh --- doc/proto.md | 123 ++++++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 83 insertions(+), 40 deletions(-) diff --git a/doc/proto.md b/doc/proto.md index 35a3266..06601fb 100644 --- a/doc/proto.md +++ b/doc/proto.md @@ -659,6 +659,8 @@ To remedy this, a `SELECT` extension is envisioned. This extension adds two option requests and one error reply type, and extends one existing option reply type. +Both options have identical formats for requests and replies. + * `NBD_OPT_SELECT` The client wishes to select the export with the given name for use @@ -667,8 +669,12 @@ option reply type. Data: - - 32 bits, length of name (unsigned) - - Name of the export + - Name of the export (as with `NBD_OPT_EXPORT_NAME`, the length + comes from the option header). + + If no name is specified (i.e. a zero length string is provided), + the default export (if any) is specified, as with + `NBD_OPT_EXPORT_NAME`. The server replies with one of the following: @@ -676,21 +682,36 @@ option reply type. server. - `NBD_REP_ERR_TLS_REQD`: The server does not wish to export this block device unless the client negotiates TLS first. - - `NBD_REP_SERVER`: The server accepts the chosen export. In this - case, the `NBD_REP_SERVER` message's data takes on a different + - `NBD_REP_SERVER`: The server accepts the chosen export. + + Additionally, the server MAY reply `NBD_REP_ERR_TLS_REQD` to + requests for exports that are unknown if TLS has not been + negotiated. This is so that clients cannot without TLS + 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 binary information normally sent in reply to `NBD_OPT_EXPORT_NAME`, in place of the default UTF-8 free-form string); this layout is shared with the successful response to - `NBD_OPT_GO`. The option reply length MUST be *length of - name* + 14, and the option data has the following layout: - - - 32 bits, length of name (unsigned) - - Name of the export. This name MAY be different from the one - given in the `NBD_OPT_SELECT` option in case the server has - multiple alternate names for a single export. - - 64 bits, size of the export in bytes (unsigned) - - 16 bits, transmission flags + `NBD_OPT_GO`. The option reply length MUST be + *length of name* + 14, and the option data has the following layout: + + - 32 bits, length of name (unsigned) + - Name of the export. This name MAY be different from the one + given in the `NBD_OPT_SELECT` option in case the server has + multiple alternate names for a single export, or a default + export was specified. + - 64 bits, size of the export in bytes (unsigned) + - 16 bits, transmission flags. The values of the transmission flags + MAY differ from what was sent earlier in response to + an earlier `NBD_OPT_SELECT` (if any), based on other options + that were negotiated in the meantime. + + The values of the transmission flags + MAY differ from what was sent earlier in response to + `NBD_OPT_SELECT`, based on other options that were negotiated in + the meantime. - For backwards compatibility, clients should be prepared to also handle `NBD_REP_ERR_UNSUP`. In this case, they should fall back to @@ -699,34 +720,56 @@ option reply type. * `NBD_OPT_GO` The client wishes to terminate the negotiation phase and progress to - the transmission phase. Possible replies from the server include: + the transmission phase. This client MAY issue this command after + an `NBD_OPT_SELECT`, or MAY issue it without a previous + `NBD_OPT_SELECT`. - - `NBD_REP_SERVER`: The server acknowledges, using the same format - for the reply as in `NBD_OPT_SELECT` (thus allowing the client - to receive the same transmission flags as would have been sent - by `NBD_OPT_EXPORT_NAME`). The values of the transmission flags - MAY differ from what was sent earlier in response to - `NBD_OPT_SELECT`, based on other options that were negotiated in - the meantime. The server MUST NOT send any zero padding bytes - after the `NBD_REP_SERVER` data, whether or not the client - negotiated the `NBD_FLAG_C_NO_ZEROES` flag. After receiving - this reply, the client and the server have both moved to the - transmission phase; therefore, the server MUST NOT send this - particular reply until all other pending option requests have - had their final reply. - - `NBD_REP_ERR_INVALID`: No `NBD_OPT_SELECT` command was - previously issued during this negotiation (there is no default); - or, the most recent `NBD_OPT_SELECT` command resulted in an error - reply (selecting a different export clears the currently selected - export, even if the new export does not exist on the server); or, - the most recent `NBD_OPT_SELECT` command issued during this - negotiation occurred before TLS was successfully negotiated - (negotiating TLS clears the selected export). - - Servers MAY also choose to send `NBD_REP_ERR_TLS_REQD` rather than - `NBD_REP_ERR_INVALID` if no non-TLS exports are supported. - - Servers MUST NOT send `NBD_REP_ERR_UNSUP` as a reply to this - message if they do not also send it as a reply to the - `NBD_OPT_SELECT` message. + Data: + + - Name of the export (as with `NBD_OPT_EXPORT_NAME`, the length + comes from the option header). + + If no name is specified (i.e. a zero length string is provided) + then the export selected with the immediately previous valid + `NBD_OPT_SELECT` will be selected (if any), or if no previous + `NBD_OPT_SELECT` valid has been issued, the default export will be + selected. + + `NBD_OPT_GO` can thus be used as a substitute for `NBD_OPT_EXPORT_NAME` + that returns errors. + + The server replies with one of the following: + + - `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. + - `NBD_REP_SERVER`: The server accepts the chosen export. + - For backwards compatibility, clients should be prepared to also + handle `NBD_REP_ERR_UNSUP`. In this case, they should fall back to + using `NBD_OPT_EXPORT_NAME`. + + Additionally, the server MAY reply `NBD_REP_ERR_TLS_REQD` to + requests for exports that are unknown if TLS has not been + negotiated. This is so that clients cannot without TLS + enumerate exports. + + The format of `NBD_REP_SERVER` is identical to the reply + for `NBD_OPT_SELECT`, except for the fact that both client + and server subseequently enter the transmission phase. By using this + reply the server acknowledges the connection, using the same + format for the reply as in `NBD_OPT_SELECT` (thus allowing the client + to receive the same transmission flags as would have been sent + by `NBD_OPT_EXPORT_NAME`); as per the note therein these + transmission flags MAY differ from those returned by any + previous `NBD_OPT_SELECT`. The server MUST NOT send any zero + padding bytes after the `NBD_REP_SERVER` data, whether or not the + client negotiated the `NBD_FLAG_C_NO_ZEROES` flag. After sending + this reply the server MUST immediately move to the transmission + phase, and after receiving this reply, the MUST immediately move + to the transmission phase; therefore, the server MUST NOT send this + particular reply until all other pending option requests have + had their final reply. ### `WRITE_ZEROES` extension