856 lines
27 KiB
Plaintext
856 lines
27 KiB
Plaintext
#########
|
|
## TODO
|
|
# * scrolls
|
|
# *
|
|
#########
|
|
|
|
|
|
#use wml::std::grid
|
|
|
|
<define-tag keyword endtag=required><strong>%body</strong></define-tag>
|
|
<define-tag mvar endtag=required><em>%body</em></define-tag>
|
|
|
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<!--
|
|
NOTE! This file uses WML 2.0.1
|
|
|
|
PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
|
|
it's more important for you since your changes will be LOST FOREVER
|
|
if you edit the .HTML files.
|
|
-->
|
|
|
|
<html>
|
|
<head>
|
|
<title>GZigZag networking: ZigZag Transfer Protocol</title>
|
|
|
|
#include '../wmlinc/catart.wml'
|
|
|
|
<H1>GZigZag networking: ZigZag Transfer Protocol</H1>
|
|
<pre>$Id: ztp.wml,v 1.3 2001/02/06 12:12:17 ajk Exp $</pre>
|
|
|
|
Written by <br>
|
|
<b>Antti-Juhani Kaijanaho</b> <br>
|
|
(add your name here if you do any significant modification)
|
|
|
|
<p>
|
|
{#MYTOC#}
|
|
|
|
<s1>On naming</s1>
|
|
|
|
<p>The name of this protocol is the ZigZag Transfer Protocol, or ZTP,
|
|
as suggested by Tuomas Lukka. Early versions of this protocol were
|
|
called the Subspace Transfer Protocol, or STP, which we did not like.
|
|
|
|
<p>Note that the acronym ZTP stands also for Zangelding Transfer
|
|
Protocol. Due to the different usages for the two protocols, we don't
|
|
expect that serious confusion will result from this.
|
|
|
|
<s1>On subspaces</s1>
|
|
|
|
<p>A subspace S' of a ZigZag space S is a ZigZag space with the
|
|
following properties:
|
|
|
|
<ol>
|
|
<li>The set of cells in S' is a subset of the set of cells in S
|
|
<li>The set of connections in S' is a subset of the set of connection in S
|
|
</ol>
|
|
|
|
<p>A subspace selector is a function mapping ZigZag spaces into their
|
|
subspaces. A subspace selector can be described by the triplet
|
|
<C, H, S>, where
|
|
|
|
<dl>
|
|
|
|
<DT>C</DT>
|
|
<dd>is a set of cells,</dd>
|
|
|
|
<dt>H</dt>
|
|
<dd>is a set of dimensions, and</dd>
|
|
|
|
<dt>S</dt>
|
|
<dd>is a set of dimensions</dd>
|
|
|
|
</dl>
|
|
|
|
<p>and where H and S are disjoint.
|
|
|
|
<p>Given a ZigZag space Z, a subspace selector chooses a subspace as
|
|
follows: the set of cells is constructed as the set of cells reachable
|
|
from the cells in C through connections along dimensions in H; and the
|
|
set of connections is constructed as the set of those connections from
|
|
Z whose both ends are in the subspace and whose dimension is in H or S.
|
|
|
|
<S1>User access privilege management</s1>
|
|
|
|
<p>Once the user is authenticated, her actions are limited by her
|
|
access privileges. There are four types of privileges:
|
|
|
|
<ul>
|
|
<li>space administrator privileges (SAP)
|
|
<li>subspace operator privileges (SOP)
|
|
<li>subspace write privileges (SWP)
|
|
<li>subspace read privileges (SRP)
|
|
</ul>
|
|
|
|
<p>
|
|
All but SAP are associated with a subspace. The subspace privileges
|
|
apply to the subspace itself and any subspaces of that subspace.
|
|
|
|
<p> If a user has SOP, SWP or SRP in a subspace S and the same
|
|
privileges in a subspace T of S, and the privileges to T are revoked,
|
|
the privilege to S is unaffected by the revocation.
|
|
|
|
<s2>Space Administrator Privileges (SAP)</s2>
|
|
|
|
<p>A user having SAP is authorized to create, delete, suspend and
|
|
resume users, and give and revoke users their SOP to any subspace, and
|
|
give and revoke users their SAP. A user having SAP is also authorized
|
|
to revoke any user's SOP, SWP or SRP to any subspace.
|
|
|
|
<s2>Subspace Operator Privileges (SOP)</s2>
|
|
|
|
<p>A user having SOP on a subspace S is authorized to give or revoke
|
|
any user their SOP, SWP or SRP to any subspace of S, including S
|
|
itself.
|
|
|
|
<s2>Subspace Write Privileges (SWP)</s2>
|
|
|
|
<p>A user having SWP on a subspace S is authorized to initiate
|
|
transfer of any subspace of S, inclusing S itself, from the client to
|
|
the server.
|
|
|
|
<s2>Subspace Read Privileges (SRP)</s2>
|
|
|
|
<p>A user having SRP on a subspace S is authorized to initiate
|
|
transfer of any subspace of S, including S itself, from the server to
|
|
the client.
|
|
|
|
<s1>Protocol overview</s1>
|
|
|
|
<p>
|
|
ZTP is actually two similar protocols for the same purpose. One
|
|
operates over a reliable stream; we call this ZTP/TCP. The other
|
|
operates over a datagram service; we call this ZTP/UDP. Note that
|
|
other underlying protocols than TCP or UDP are possible; the names are
|
|
chosen for their mnemonic value, not for their accuracy.
|
|
|
|
<p>
|
|
The datagram service used by ZTP/UDP is assumed to fail only in that
|
|
sent datagrams may be lost en route and that datagrams may arrive out
|
|
of order, and datagrams may be duplicated. In particular, it is
|
|
assumed that any arriving datagrams are uncorrupted.
|
|
|
|
<p>
|
|
All transfer protocols used by ZTP/TCP and ZTP/UDP are assumed to
|
|
provide for confidentiality and integrity. However, the transfer
|
|
protocols are not necessarily assumed to provide for authentication.
|
|
|
|
<p>Thus, good transfer protocols to use with ZTP/TCP are
|
|
<ul>
|
|
<li>TLS over TCP over IP
|
|
<li>SSL over TCP over IP
|
|
<li>TCP over IPSec
|
|
<li>SSH protocol
|
|
</ul>
|
|
|
|
<p>UDP over IPSec is a good protocol to use with ZTP/UDP.
|
|
|
|
<p>In a trusted environment, also TCP over IP with ZTP/TCP and UDP
|
|
over IP in ZTP/TCP can be used. Hovewer, <strong>using ZTP/TCP over
|
|
TCP over plain IP and using ZTP/UDP over UDP over plain IP on the
|
|
global Internet is DANGEROUS</strong>.
|
|
|
|
<p>The ZTP protocol consists of several modules. The modules are:
|
|
<ul>
|
|
<li>authentication
|
|
<li>user administration
|
|
<li>subspace administration
|
|
<li>subspace naming
|
|
<li>subspace transfer
|
|
<li>SEQ scheme
|
|
</ul>
|
|
|
|
<p>The authentication module actually consists of several alternative
|
|
modules. <dfn>Pre-authentication</dfn> is used when ZTP operates over
|
|
authenticating underlying protocols. It is also useful for
|
|
anonymous-access-only read-only servers, where there is no need for
|
|
real authentication. <dfn>Password authentication</dfn> is used when
|
|
the underlying protocol provides for data integrity and
|
|
confidentiality but not authentication, and in trusted unencrypted
|
|
environments. <dfn>Cryptographic authentication</dfn> will use
|
|
cryptographic means to authenticate the user and is meant to be used
|
|
in hostile environments. This specification will not define any
|
|
cryptographic authentication methods.
|
|
|
|
<p>User administration module handles such things as adding, deleting,
|
|
suspending and resuming users. It is all things that require SAP.
|
|
|
|
<p>Subspace administration module allows a user having SOP to a
|
|
subspace S give and revoke SOP, SWP and SRP to any subspace of S,
|
|
including S itself.
|
|
|
|
<p>Subspace naming module uses the SEQ scheme to define a subspace and
|
|
then gives a name for it. All other subspace operations use that
|
|
name.
|
|
|
|
<p>Subspace tranfer module uses the SEQ scheme to transfer a subspace
|
|
from the client to the server (which requires SWP) and from the server
|
|
to the client (which requires SRP).
|
|
|
|
<p>The SEQ scheme is a method for dumping a subspace content from the
|
|
sender (either the client or the server) to the receiver (either the
|
|
client or the server, the one which is not the sender). The scheme is
|
|
simple in ZTP/TCP. In ZTP/UDP, the scheme is optimized for
|
|
transmission paths with low packet loss, allowing for information to
|
|
be used as the packets arrive, even if they come out of order.
|
|
|
|
<s2>Protocol walkthrough</s2>
|
|
|
|
<p>An ZTP protocol instance starts by establishing a session. In
|
|
ZTP/TCP, this is handled by the underlying protocol, so in ZTP/TCP
|
|
this phase consists of no messages. In ZTP/UDP, a session is
|
|
identified by an octet negotiated by the parties in a handshake
|
|
roundtrip.
|
|
|
|
<p>After session has been established, user authentication is
|
|
performed. This is initiated by the client who sends a request for
|
|
authentication specifying which authentication method is desired. The
|
|
rest of the exchange depends on the authentication method; the
|
|
authentication phase is ended by an okaying or rejecting message from
|
|
the server.
|
|
|
|
<p>After successful authentication, the client in the session is
|
|
assumed to be controlled by the authenticated user. It can then
|
|
initiate any process for which the user has sufficient privileges.
|
|
|
|
<p>XXX Use cases
|
|
|
|
<p>Connection can be closed at any time. It is preferred that the
|
|
connection closure scheme is used. The closure can be initiated by
|
|
either party at any time. In case connection is not properly closed,
|
|
a connection shall have a timeout of at least ten minutes for forcibly
|
|
closing the connection if no messages are exchanged in that time.
|
|
|
|
<s1>Authentication schemes</s1>
|
|
|
|
There are three schmes for authentication in ZTP. Preauthentication
|
|
presupposes that the underlying protocol provides authentication in
|
|
some implementation-defined manner. Password authentication uses a
|
|
trivial shared secret protocol to establish the authenticity of the
|
|
user. A slot for future amendment of the protocol is reserved; it is
|
|
expected that cryptographic authentication will be preferred over
|
|
password authentication in the future. This protocol specification
|
|
does not define any cryptographic authentication methods.
|
|
|
|
<s2>Preauthentication</s2>
|
|
|
|
<p>In preauthentication, the underlying protocol provides for enough
|
|
information to determine the authencity of the user at the client end.
|
|
The mechanism for that is beyond the scope of this specification.
|
|
|
|
<p>The client requesting preauthentication shall send an AUTH REQ/PRE
|
|
message containing the user name for which authentication is desired.
|
|
If the server determines that the client is sufficiently authenticated
|
|
by the underlying protocol to be that user name, and the named user
|
|
exists and is not suspended, it shall respond with the AUTH OK
|
|
message. Otherwise it shall respond with an AUTH ERR message and
|
|
initiate connection closure.
|
|
|
|
<s2>Password authentication</s2>
|
|
|
|
<p>In password authentication the client provides the server with a
|
|
user name / password pair, which the server compares with its own
|
|
records. If the pair matches, the user is successfully authenticated.
|
|
The password is a shared secret; however, the server may use one-way
|
|
functions to store the information it needs of the password.
|
|
|
|
<p>The client requesting password authentication shall send an AUTH
|
|
REQ/PASS message containing the user name for which authentication is
|
|
desired and the related password. If the password is determined to be
|
|
the same as the password for the user name stored in the server's
|
|
records, and the user is not suspended, the server shall respond with
|
|
the AUTH OK message. If there is no such user name, or the password
|
|
does not match, or the user is suspended, the server MUST respond with
|
|
an AUTH ERR message and initiate connection closure.
|
|
|
|
<s2>AUTH message details</s2>
|
|
|
|
<s3 authreqresponses>Responses to AUTH REQ messages</s3>
|
|
|
|
<p>The server MUST respond to an <keyword>AUTH REQ</keyword> message
|
|
with either the message <keyword>AUTH OK</keyword> or the message
|
|
<keyword>AUTH ERR</keyword>, based on the following rules:
|
|
|
|
<ul>
|
|
|
|
<li>If the server does not support the requested authentication type
|
|
at all, it MUST respond with <keyword>AUTH ERR</keyword>.
|
|
|
|
<li>If the <mvar>username</mvar> is the name of an nonexistent user,
|
|
or it is an existing user who is not properly authenticated, the
|
|
server MUST respond with <keyword>AUTH ERR</keyword>. The message
|
|
sent MUST be identical between the different reasons in this item for
|
|
issuing the message. In other words, it MUST NOT be possible for the
|
|
client to determine based on the form of the message whether the user
|
|
name exists or not. An example of a proper explanation text for the
|
|
message is "Access denied".
|
|
|
|
<li>If the <mvar>username</mvar> is properly authenticated and the
|
|
named user is disabled, the server MUST respond with <keyword>AUTH
|
|
ERR</keyword>. An example of a proper explanation text for the
|
|
message is "User disabled". Note that this kind of a message MUST NOT
|
|
be sent if the user is not properly authenticated.
|
|
|
|
<li>If the <mvar>username</mvar> exists and is properly authenticated
|
|
and it is not disabled, the server SHOULD respond with <keyword>AUTH
|
|
OK</keyword>. However, the server MAY also respond with <keyword>AUTH
|
|
ERR</keyword> (for example, if there are local limits on the number of
|
|
simultaneous users and the limit is exceeded), in which case the
|
|
explanation text for the message SHOULD make it clear why the
|
|
authentication was rejected.
|
|
|
|
</ul>
|
|
|
|
|
|
<s3>AUTH REQ/PRE</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p>
|
|
<keyword>AUTH REQ/PRE</keyword> <mvar>username</mvar>
|
|
</p>
|
|
|
|
<ul>
|
|
<li><mvar>username</mvar> : <keyword>string</keyword>
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message MUST be sent immediately after the connection has been
|
|
established by a client wishing for preauthentication. The
|
|
<mvar>username</mvar> is the name of the user for which the
|
|
authentication is requested.
|
|
|
|
<p>The server responses to this message are defined in <ref
|
|
authreqresponses>
|
|
|
|
<s3>AUTH REQ/PASS</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p><keyword>AUTH REQ/PASS</keyword> <mvar>username</mvar> <mvar>password</mvar></p>
|
|
|
|
<ul>
|
|
<li><mvar>username</mvar>, <mvar>password</mvar> : <keyword>string</keyword>
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message MUST be sent immediately after the connection has been
|
|
established by a client wishing for password authentication. The
|
|
<mvar>username</mvar> is the name of the user for which the
|
|
authentication is requested.
|
|
|
|
<p>The server verifies the authenticity of the user by verifying that
|
|
the <mvar>password</mvar> is the same as the valid password for the
|
|
<mvar>username</mvar> according to the server's records. Note that
|
|
the server MAY store only the result of a one-way hashing of the
|
|
password instead of the password itself, if this information can be
|
|
used to reliably ascertain the validity of a given
|
|
<mvar>password</mvar>.
|
|
|
|
<p>The server responses to this message are defined in <ref
|
|
authreqresponses>
|
|
|
|
<s3>AUTH OK</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p><keyword>AUTH OK</keyword></p>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message indicates that the server has accepted the
|
|
authenticity of the client as the username given in the earlier
|
|
<keyword>AUTH REQ</keyword> message. This message concludes the
|
|
authentication phase.
|
|
|
|
<s3>AUTH ERR</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p><keyword>AUTH ERR</keyword> <mvar>explanation</mvar></p>
|
|
|
|
<ul>
|
|
|
|
<li><mvar>explanation</mvar> : <keyword>string</keyword>
|
|
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message indicates that the server has not accepted the
|
|
authenticity of the client as the username given in the earlier
|
|
<keyword>AUTH REQ</keyword> message. The server, after sending this
|
|
message, SHOULD immediately initiate connection closure.
|
|
|
|
<p>The <mvar>explanation</mvar> SHOULD be a human-readable description
|
|
of the reason for the authenticity rejection. Note that the server
|
|
SHOULD word the explanation so that the client cannot determine
|
|
whether it was failed authentication or a nonexistent username that
|
|
prompted the <keyword>AUTH ERR</keyword> message.
|
|
|
|
<s1>User administration</s1>
|
|
|
|
<p>The purpose of the user administration module in ZTP is to allow the
|
|
administrator to administrate users remotely without needing to resort
|
|
to implementation-defined behaviour.
|
|
|
|
<p>Users have the following characteristics tunable using ZTP:
|
|
|
|
<ul>
|
|
<li>User name (<mvar>UNAME</mvar> : <keyword>string</keyword>)
|
|
<li>Permission to be preauthenticated (<mvar>AUTH/PRE</mvar> : <keyword>boolean</keyword>)
|
|
<li>Permission to be password-authenticated (<mvar>AUTH/PASS</mvar> : <keyword>boolean</keyword>)
|
|
<li>Is suspended or not (<mvar>SUSP</mvar> : <keyword>boolean</keyword>)
|
|
<li>Permission to change password (<mvar>CHPASS</mvar>: <keyword>boolean</keyword>)
|
|
<li>Password (<mvar>PASS</mvar> : <keyword>string</keyword>)
|
|
<li>Has SAP or doesn't have SAP (<mvar>SAP</mvar> : <keyword>boolean</keyword>)
|
|
</ul>
|
|
|
|
<p>The user administration module consists of one scheme for editing
|
|
and one scheme for viewing all these user data. The edition scheme
|
|
can be also used for adding and deleting new users.
|
|
|
|
<p>A user can view their own data regardless of permissions. The user
|
|
can change the password if their <mvar>CHPASS</mvar> flag is set to
|
|
true.
|
|
|
|
<s2>The server side user management concept</s2>
|
|
|
|
<p>This section defines a conceptual model for the server side user
|
|
management for ZTP. Server implementations MAY use other
|
|
implementation strategies so long as the effects observable by the
|
|
clients are the same as with this model.
|
|
|
|
<p>In the server, there is a table of users. The table consists of
|
|
records containing the following information:
|
|
|
|
<ul>
|
|
<li><mvar>username</mvar> : <keyword>string</keyword>
|
|
<li><mvar>password</mvar> : <keyword>string</keyword>
|
|
<li><mvar>status</mvar> : <keyword>userstatus</keyword>
|
|
</ul>
|
|
|
|
<p>A particular record may be written as a triplet
|
|
<<mvar>username</mvar>, <mvar>password</mvar>,
|
|
<mvar>status</mvar>>.
|
|
|
|
<p>The third element, <mvar>status</mvar> is an octet-length bit
|
|
vector with the following structure:
|
|
|
|
<grid layout="8x2" width="100%" border="1">
|
|
<cell>Bit 7</cell>
|
|
<cell>Bit 6</cell>
|
|
<cell>Bit 5</cell>
|
|
<cell>Bit 4</cell>
|
|
<cell>Bit 3</cell>
|
|
<cell>Bit 2</cell>
|
|
<cell>Bit 1</cell>
|
|
<cell>Bit 0</cell>
|
|
|
|
<cell>Reserved</cell>
|
|
<cell>Reserved</cell>
|
|
<cell>Reserved</cell>
|
|
<cell>AUTH/PASS</cell>
|
|
<cell>AUTH/PRE</cell>
|
|
<cell>SAP</cell>
|
|
<cell>CHPASS</cell>
|
|
<cell>SUSP</cell>
|
|
</grid>
|
|
|
|
<p>This data type is referred to in type definitions as
|
|
<keyword>userstatus</keyword>. Note that the elements marked as
|
|
Reserved MUST have the value <keyword>false</keyword>.
|
|
|
|
<p>The table of users is indexed by user names. There may be at most
|
|
one record with a given <mvar>username</mvar> in the table.
|
|
|
|
<p>In the table, the following operations are allowed:
|
|
|
|
<ul>
|
|
|
|
<li>insertion of a new user record;
|
|
|
|
<li>replacement of a user record;
|
|
|
|
<li>deletion of a user record; and
|
|
|
|
<li>accessing a complete user record.
|
|
|
|
</ul>
|
|
|
|
<p>All of them are atomic. This means that, for the forementioned
|
|
operations, the following are true:
|
|
|
|
<ul>
|
|
|
|
<li>If an operation fails, the table will remain in the state it was
|
|
before the attempt.
|
|
|
|
<li>Operations never overlap; thus at most one operation is in
|
|
progress at any time.
|
|
|
|
</ul>
|
|
|
|
<p>A user exists, if and only if there is a record with that username
|
|
on the table. A user is disabled if and only if there is a record
|
|
with that username on the table and the <mvar>SUSP</mvar> element of
|
|
the <mvar>status</mvar> element of that record has the value
|
|
<keyword>true</keyword>. A user has SAP if and only if there is a
|
|
record with that username on the table and the <mvar>SAP</mvar>
|
|
element of the <mvar>status</mvar> element of that record has the
|
|
value <keyword>true</keyword>
|
|
|
|
<s2>UADM message details</s2>
|
|
|
|
<s3>UADM NEW</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p><keyword>UADM NEW</keyword> <mvar>stat</mvar> <mvar>uname</mvar> <mvar>passwd</mvar>
|
|
</p>
|
|
|
|
<ul>
|
|
<li><mvar>stat</mvar> : <keyword>userstatus</keyword>
|
|
<li><mvar>uname</mvar>, <mvar>passwd</mvar> : <keyword>string</keyword>
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message is sent by the client when it wants to create a new
|
|
user.</p>
|
|
|
|
<p>After receiving this message, the server MUST follow the following
|
|
step-by-step algorithm (the term "client user" refers to the user
|
|
authenticated to control the session where the message was sent):
|
|
|
|
<ul>
|
|
|
|
<li>Check whether the client user has SAP. If not, the server MUST
|
|
send in response the <keyword>UADM E/NOPERM</keyword> message, and end
|
|
the processing of the message here.
|
|
|
|
<li>Check whether the user <mvar>uname</mvar> exists. If it does, the
|
|
server MUST send in response the <keyword>UADM E/EXISTS</keyword>
|
|
message and end the processing of the message here.
|
|
|
|
<li>The server SHOULD check that it has enough resources to handle
|
|
this new user (the criteria are implementation-defined and MAY include
|
|
local considerations). If it determines that it doesn't have the
|
|
resources, the server MUST send in response the <keyword>UADM
|
|
E/NORES</keyword> message and end the processing of the message here.
|
|
|
|
<li>The server MUST insert the record <<mvar>uname</mvar>,
|
|
<mvar>passwd</mvar>, <mvar>stat</mvar>> into the user table. If
|
|
this fails, it MUST respond with the message <keyword>UADM
|
|
E/PROB</keyword>, otherwise it MUST respond with the message
|
|
<keyword>UADM OK</keyword>.
|
|
|
|
</ul>
|
|
|
|
|
|
<s1>Payload transfer: the SEQ scheme</s1>
|
|
|
|
<p>
|
|
The actual payload of the protocol, the subspace data, is transferred
|
|
over by the SEQ scheme.
|
|
|
|
<p>The SEQ scheme consists of five SEQ data messages and four SEQ
|
|
control messages. The data messages are
|
|
|
|
<dl>
|
|
|
|
<dt>SEQ CELL</dt>
|
|
<dd>Specifies a root cell for a subspace</dd>
|
|
|
|
<dt>SEQ HARDDIM</dt>
|
|
<dd>Specifies a hard dimension for a subspace</dd>
|
|
|
|
<dt>SEQ SOFTDIM</dt>
|
|
<dd>Specifies a soft dimension for a subspace</dd>
|
|
|
|
<dt>SEQ CONTENT</dt>
|
|
<dd>Transfers over the content of a subspace</dd>
|
|
|
|
<dt>SEQ RANK</dt>
|
|
<dd>Specifies a subrank in the subspace</dd>
|
|
|
|
</dl>
|
|
|
|
<p>
|
|
The SEQ control messages are listed below.
|
|
|
|
<dl>
|
|
|
|
<dt>SEQ FIN</dt>
|
|
<dd>Initiates finalization phase of the SEQ scheme</dd>
|
|
|
|
<dt>SEQ REQ</dt>
|
|
<dd>Requests that a SEQ data message is resent</dd>
|
|
|
|
<dt>SEQ ERR</dt>
|
|
<dd>Response for a broken SEQ REQ.</dd>
|
|
|
|
<dt>SEQ END</dt>
|
|
<dd>Ends the SEQ scheme instance</dd>
|
|
|
|
</dl>
|
|
|
|
<p>A SEQ scheme instance has a sending end and a receiving end. When
|
|
the server is the sending end, the client is the receiving end and
|
|
vice versa.
|
|
|
|
<p>In ZTP/TCP, the SEQ scheme consists of a number of SEQ data
|
|
messages and is finished by a SEQ END message.
|
|
|
|
<p>In ZTP/UDP, the SEQ scheme consists of two phases: the data
|
|
transfer phase and the finalization phase. The data transfer phase
|
|
consists of a number of SEQ data messages and is ended by a SEQ FIN
|
|
message which also starts the finalization phase. Then the receiver
|
|
end of the SEQ scheme sends one or more SEQ REQ messages and the
|
|
sender end responds with an appropriate SEQ data message. The
|
|
finalization phase is ended by a SEQ END by both parties.
|
|
|
|
<s2>SEQ message details</s2>
|
|
|
|
<s3>SEQ/DATA message template</s3>
|
|
|
|
<s3>SEQ/CTL message template</s3>
|
|
|
|
<s3>SEQ CELL</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p>
|
|
<keyword>SEQ/DATA</keyword> <keyword>CELL</keyword> <mvar>cellid</mvar><br>
|
|
<ul>
|
|
<li><mvar>cellid</mvar> : <keyword>string</keyword>
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message defines that the cell <mvar>cellid</mvar> is a root
|
|
cell for the subspace being described.
|
|
|
|
<s3>SEQ HARDDIM</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p>
|
|
<keyword>SEQ/DATA</keyword> <keyword>HARDDIM</keyword> <mvar>dimid</mvar>
|
|
</p>
|
|
|
|
<ul>
|
|
<li><mvar>dimid</mvar>: <keyword>string</keyword>
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p> This message defines that the dimension <mvar>dimid</mvar> is one
|
|
of the defining dimensions for the subspace being described. In other
|
|
words, this defines that any cell connected to any cell in the
|
|
subspace along dimension <mvar>dimid</mvar> also is in the subspace.
|
|
|
|
<p>If in a SEQ scheme instance a dimension is specified using
|
|
<keyword>SEQ HARDDIM</keyword>, it SHOULD NOT be specified in the same
|
|
SEQ scheme instance using <keyword>SEQ SOFTDIM</keyword>.
|
|
|
|
<s3>SEQ SOFTDIM</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p>
|
|
<keyword>SEQ/DATA</keyword> <keyword>SOFTDIM</keyword> <mvar>dimid</mvar>
|
|
</p>
|
|
<ul>
|
|
<li><mvar>dimid</mvar>: <keyword>string</keyword>
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message defines that any connections along dimension
|
|
<mvar>dimid</mvar> between cells that are in the subspace are included
|
|
in the subspace. However, this dimension will not take part in the
|
|
definition of the cell set of the subspace.
|
|
|
|
<p>If in a SEQ scheme instance a dimension is specified using
|
|
<keyword>SEQ SOFTDIM</keyword>, it SHOULD NOT be specified in the same
|
|
SEQ scheme instance using <keyword>SEQ HARDDIM</keyword>.
|
|
|
|
<s3>SEQ CONTENT</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p> <keyword>SEQ/DATA</keyword> <keyword>CONTENT</keyword>
|
|
<mvar>content-type</mvar> <mvar>cellid</mvar> <mvar>content</mvar>
|
|
</p>
|
|
<ul>
|
|
<li><mvar>content-type</mvar>: <keyword>octet</keyword>
|
|
<li><mvar>cellid</mvar>: <keyword>string</keyword>
|
|
<li><mvar>content</mvar>: <keyword>octet</keyword>[]
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This command transfers the content of a cell, which this protocol
|
|
treats as an octet stream with no underlying structure. The type of
|
|
the content is indicated in this messages; the following content types
|
|
are now established:
|
|
|
|
|
|
<grid layout="2x3" width="100%">
|
|
|
|
<cell>0</cell>
|
|
<cell>Octet stream, ie. unknown format</cell>
|
|
|
|
<cell>1</cell>
|
|
<cell>Unicode text in UTF-8 encoding</cell>
|
|
|
|
<cell>2</cell>
|
|
<cell>A span</cell>
|
|
|
|
</grid>
|
|
|
|
<s3>SEQ RANK</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p><keyword>SEQ/DATA</keyword> <keyword>RANK</keyword>
|
|
<mvar>dimid</mvar> <mvar>cellarray</mvar>
|
|
|
|
<ul>
|
|
<li><mvar>dimid</mvar> : <keyword>string</keyword>
|
|
<li><mvar>cellarray</mvar> : <keyword>string</keyword>[]
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message denotes a subrank along dimension <mvar>dimid</mvar>.
|
|
|
|
<p>The precise definition of this is as follows:
|
|
<mvar>cellarray</mvar>[<mvar>n</mvar>] is connected posward to
|
|
<mvar>cellarray</mvar>[<mvar>n</mvar>+1] for all <mvar>n</mvar>
|
|
between zero, inclusive, and the length of <mvar>cellarray</mvar>
|
|
minus one, exclusive. More than one <keyword>SEQ RANK</keyword>
|
|
message MAY define the same connection. Two <keyword>SEQ
|
|
RANK</keyword> messages MUST NOT define two conflicting connections
|
|
(that is, a connection posward or negward from the same cell to two
|
|
different cells).
|
|
|
|
<s3>SEQ FIN</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p><keyword>SEQ/CTL</keyword> <keyword>FIN</keyword> <mvar>dmcount</mvar>
|
|
|
|
<ul>
|
|
<li><mvar>dmcount</mvar>: <keyword>uint32</keyword>
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message closes the data transfer phase of a SEQ scheme
|
|
instance and opens its finalization phase.
|
|
|
|
<p>The parameter <mvar>dmcount</mvar> MUST specify the number of
|
|
unique SEQ data messages sent during the data transfer phase of the
|
|
SEQ scheme instance.
|
|
|
|
<p>In ZTP/UDP, the sending end of the SEQ scheme instance MUST send
|
|
this message repeatedly after sending the last SEQ data message in the
|
|
data transfer phase, until it receives either a SEQ REQ or a SEQ END
|
|
message.
|
|
|
|
<p>When the receiving end of the SEQ scheme instance first receives
|
|
this message, it SHOULD check which data messages it did receive and
|
|
issue SEQ REQ messages for each missing message. When it has received
|
|
all data messages, it MUST send a SEQ END message. It should ignore
|
|
all further SEQ FIN messages associated with that SEQ scheme instance.
|
|
|
|
<p>This message MUST NOT be sent in ZTP/TCP.
|
|
|
|
<s3>SEQ REQ</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p>
|
|
<keyword>SEQ/CTL</keyword> <keyword>REQ</keyword> <mvar>seq</mvar>
|
|
</p>
|
|
|
|
<ul>
|
|
<li><mvar>seq</mvar> : <keyword>uint32</keyword>
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message is sent by the receiving end of the SEQ scheme
|
|
instance to request that the sending end resend the SEQ data message
|
|
with the SEQ message identity number <mvar>seq</mvar>.
|
|
|
|
<p>The receiving end MUST repeatedly resend this message if it is
|
|
sending it at all, until it receives the data message it's asking for
|
|
or a corresponding <keyword>SEQ ERR</keyword>.
|
|
|
|
<p>The sending end MUST respond to each <keyword>SEQ REQ</keyword>
|
|
message it receives (even duplicates) by resending the message being
|
|
requested, or with a <keyword>SEQ ERR</keyword> message.
|
|
|
|
<p>This message MUST NOT be sent in ZTP/TCP
|
|
|
|
<s3>SEQ ERR</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p>
|
|
<keyword>SEQ/CTL</keyword> <keyword>ERR</keyword> <mvar>seq</mvar>
|
|
</p>
|
|
|
|
<ul>
|
|
<li><mvar>seq</mvar> : <keyword>uint32</keyword>
|
|
</ul>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message is a response to an invalid <keyword>SEQ REQ</keyword>
|
|
message. It is to be sent in response to every received invalid
|
|
<keyword>SEQ REQ</keyword> message, even to duplicates.
|
|
|
|
<p>This message MUST NOT be sent in ZTP/TCP.
|
|
|
|
<s3>SEQ END</s3>
|
|
|
|
<s4>Synopsis</s4>
|
|
|
|
<p>
|
|
<keyword>SEQ/CTL</keyword> <keyword>END</keyword>
|
|
</p>
|
|
|
|
<s4>Description</s4>
|
|
|
|
<p>This message ends the SEQ scheme instance.
|
|
|
|
<p>In ZTP/UDP, the receiving end MUST send this message repeatedly
|
|
after receiving <keyword>SEQ FIN</keyword> and receiving all the data
|
|
it needs, until it receives a <keyword>SEQ END</keyword> message. The
|
|
sending end MUST respond to every <keyword>SEQ END</keyword> message,
|
|
even duplicates, with a <keyword>SEQ END</keyword> message.
|
|
|
|
<p>In ZTP/TCP, the sending end MUST send a single <keyword>SEQ
|
|
END</keyword> message after sending all the SEQ data messages it's
|
|
going to send. The receiving end MUST NOT respond to the <keyword>SEQ
|
|
END</keyword> message.
|
|
|