NotifyRemoteClient from this Server acknowledges the Request or asks
that it be retransmitted or reports an error. A retransmission of the
Request from the Client causes a NotifyVmtpClient to be returned to the
Client if APG is set. The CSR leaves the Forwarded state after timing
out in the absence of NotifyRemoteClient operations from the forward
Server or on receipt of a NotifyRemoteClient operation indicating the
forward Server has sent a Response and received an acknowledgement. It
then enters the ResponseDiscarded state.
Receipt of a new Request from the same Client aborts the current
transaction, independent of its state, and initiates a new transaction
unless the new Request is part of a run of message transactions. If it
is part of a run of message transactions, the handling follows the state
diagram except the new Request is not Processed until there has been a
response sent to the previous transaction.
5.4. User Interface
The RPC or user interface to VMTP is implementation-dependent and may
use systems calls, functions or some other mechanism. The list of
requests that follow is intended to suggest the basic functionality that
should be available.
AcceptMessage( reqmcb, segptr, segsize, client, transid, timeout )
Accept a new Request message in the specified reqmcb
area, placing the segment data, if any, in the area
described by segptr and segsize. This returns the
Server in the entityId field of the reqmcb and actual
segment size in the segsize parameters. It also returns
the Client and Transaction for this message transaction
in the corresponding parameters. This procedure
supports message semantics for request processing. When
a server process executes this call, it blocks until a
Request message has been queued for the server.
AcceptMessage returns after the specified timeout period
if a message has not been received by that time.
RespondMessage( responsemcb, client, transid, segptr )
Cheriton [page 69]
RFC1045 VMTP February 1988
Respond to the client with the specified response
message and segment, again with message semantics.
RespondCall( responsemcb, segptr )
Respond to the client with the specified response
message and segment, with remote procedure call
semantics. This procedure does not return. The
lightweight process that executes this procedure is
matched to a stack, program counter, segment area and
priority from the information provided in a
ModifyService call, as specified in Appendix III.
ForwardMessage( requestmcb, transid, segptr, segsize, forwardserver )
Forward the client to the specified forwardserver with
the request specified in mcb.
ForwardCall( requestmcb, segptr, segsize, forwardserver )
Forward the client transaction to the specified
forwardserver with the request specified by requestmcb.
This procedure does not return.
GetRemoteClientId()
Return the entityId for the remote client on whose
behave the process is executing. This is only
applicable in the procedure call model of request
handling.
GetForwarder( client )
Return the entity that forwarded this Request, if any.
GetProcess( client )
Return an identifier for the process associated with
this client entity-id.
GetPrincipal( client )
Return the principal associated with this client
entity-id.
5.5. Event Processing
The following events may occur in VMTP servers.
- User Requests
* Receive
Cheriton [page 70]
RFC1045 VMTP February 1988
* Respond
* Forward
* GetForwarder
* GetProcess
* GetPrincipal
- Packet Arrival
* Request Packet
- Management Operations
* NotifyVmtpServer
- Timeouts
* Client State Record Timeout
The handling of these events is described in detail in the following
subsections. The conventions of the previous chapter are followed,
including the use of the various subroutines in the description.
5.6. Server User-invoked Events
A user event occurs when a VMTP server invokes one of the VMTP interface
procedures.
5.6.1. Receive
AcceptMessage(reqmcb, segptr, segsize, client, transid, timeout)
Locate server's request queue.
if request is queued then
Remember CSR associated with this Request.
return Request in reqmcb, segptr and segsize
and client and transaction id.
Wait on server's request queue for next request
up time timeout seconds.
end ReceiveCall
Notes:
Cheriton [page 71]
RFC1045 VMTP February 1988
1. If a multi-packet Request is partially received at the time
of the AcceptMessage, the process waits until it completes.
2. The behavior of a process accepting a Request as a
lightweight thread is similar except that the process
executes using the Request data logically as part of the
requesting Client process.
5.6.2. Respond
RespondCall is described as one case of the Respond transmission
procedure; RespondMessage is similar.
RespondCall( responsemcb, responsesegptr )
Locate csr for this client.
Check segment data accessible, if any
if local client then
Handle locally
return
endif
if responsemcb.Code is RESPONSE_DISCARDED then
Mark as RESPONSE_DISCARDED
return
SendPacketGroup( csr )
set csr.State to Responded.
if DGM reply then { Idempotent }
release segment data
Timeout( csr, TS4(csr.Client), FreeCsr );
else { Await acknowledgement or new Request else ask for ack. }
Timeout( csr, TS5(csr.Client), RemoteClientTimeout )
end RespondCall
Notes:
1. RespondMessage is similar except the Server process must be
synchronized with the release of the segment data (if any).
2. The non-idempotent Response with segment data is sent first
without a request for an acknowledgement. The Response is
retransmitted after time TS5(client) if no acknowledgment or
new Request is received from the client in the meantime. At
this point, the APG bit is sent.
3. The MCB of the Response is buffered in the client CSR, which
remains for TS4 seconds, sufficient to filter old duplicates.
The segment data (if any) must be retained intact until: (1)
Cheriton [page 72]
RFC1045 VMTP February 1988
after transmission if idempotent or (2) after acknowledged or
timeout has occurred if not idempotent. Techniques such as
copy-on-write might be used to keep a copy of the Response
segment data without incurring the cost of a copy.
5.6.3. Forward
Forwarding is logically initiating a new message transaction between the
Server (now acting as a Client) and the server to which the Request is
forwarded. When the second server returns a Response, the same Response
is immediately returned to the Client. The forwarding support in VMTP
preserves these semantics while providing some performance optimizations
in some cases.
ForwardCall( req, segptr, segsize, forwardserver )
Locate csr for this client.
Check segment data accessible, if any
if local client or Request was multicast or secure
or csr.ForwardCount == 15 then
Handle as a new Send operation
return
if forwardserver is local then
Handle locally
return
Set csr.funccode to Request
Increment csr.ForwardCount
Set csr.State to Responded
SendPacketGroup( csr ) { To ForwardServer }
Timeout( csr, TS4(csr.Client), FreeAlien )
end ForwardCall
Notes:
1. A Forward is logically a new call or message transaction. It
must be really implemented as a new message transaction if
the original Request was multicast or secure (with the
optional further refinement that it can be used with a secure
message transaction when the Server and ForwardServer are the
same principal and the Request was not multicast).
2. A Forward operation is never handled as an idempotent
operation because it requires knowledge that the
ForwardServer will treat the forwarded operation as
idempotent as well. Thus, a Forward operation that includes
a segment should set APG on the first transmission of the
Cheriton [page 73]
RFC1045 VMTP February 1988
forwarded Request to get an acknowledgement for this data.
Once the acknowledgement is received, the forwarding Server
can discard the segment data, leaving only the basic CSR to
handle retransmissions from the Client.
5.6.4. Other Functions
GetRemoteClient is a simple local query of the CSR. GetProcess and
GetPrincipal also extract this information from the CSR. A server
module may defer the Probe callback to the Client to get that
information until it is requested by the Server (assuming it is not
using secure communication and duplicate suppression is adequate without
callback.) GetForwarder is implemented as a callback to the Client,
using a GetRequestForwarder VMTP management operation. Additional
management procedures for VMTP are described in Appendix III.
5.7. Request Packet Arrival
The basic packet reception follows that described for the Client
routines. A Request packet is handled by the procedure HandleRequest.
HandleRequest( csr, p, psize )
if LocalClient(csr) then
{ Forwarded Request on local Client }
if csr.LocalTransaction != p.Transaction then return
if csr.State != AwaitingResponse then return
if p.ForwardCount < csr.ForwardCount then
Discard Request and return.
Find a CSR for Client as a remote Client.
if not found then
if packet group complete then
handle as a local message transaction
return
Allocate and init CSR
goto newTransaction
{ Otherwise part of current transaction }
{ Handle directly below. }n
if csr.RemoteTransaction = p.Transaction then
{ Matches current transaction }
if OldForward(p.ForwardCount,csr.ForwardCount) then
return
if p.ForwardCount > csr.ForwardCount then
{ New forwarded transaction }
goto newTransaction
Cheriton [page 74]
RFC1045 VMTP February 1988
{ Otherwise part of current transaction }
if csr.State = ReceivingRequest then
if new segment data then retain in CSR segment area.
if Request not complete then
Timeout( csr, TS1(p.Client), RemoteClientTimeout )
return;
endif
goto endPacketGroup
endif
if csr.State is Responded then
{ Duplicate }
if csr.Code is RESPONSE_DISCARDED
and Multicast(p) then
return
endif
if not DGM(csr) then { Not idempotent }
if SegmentData(csr) then set APG
{ Resend Response or Request, if Forwarded }
SendPacketGroup( csr )
timeout=if SegmentData(csr) then TS5(csr.Client)
else TS4(csr.Client)
Timeout( csr, timeout, RemoteClientTimeout )
return
{ Else idempotent - fall thru to newTransaction }
else { Presume it is a retransmission }
NotifyClient( csr, p, OK )
return
else if OldTransaction(csr.RemoteTransact,p.Transaction) then
return
{ Otherwise, a new message transaction. }
newTransaction:
Abort handling of previous transactions for this Client.
if (NSRset(p) or NERset(p)) and NoStreaming then
NotifyClient( csr, p, STREAMING_NOT_SUPPORTED )
return
| if NSRset(p) then { Streaming }
| { Check that consecutive with previous packet group }
| Find last packet group CSR from this client.
| if p.Transaction not lastcsr.RemoteTransaction+1 mod 2**32
| and not STIset(lastcsr) or
| p.Transaction not lastcsr.RemoteTransaction+256 mod **32
| then
| { Out of order packet group }
| NotifyClient(csr, p, BAD_TRANSACTION_ID )
| return
| endif
Cheriton [page 75]
RFC1045 VMTP February 1988
| if lastcsr not completed then
| NotifyClient( lastcsr, p, RETRY )
| endif
| if lastcsr available then use it for this packet group
| else allocate and initialize new CSR
| if CMG(lastcsr) then
| Add segment data to lastcsr Request
| Keep csr as record of this packet group.
| Clear lastcsr.VerifyInterval
| endif
| else { First packet group }
if MultipleRemoteClients(csr) then ScavengeCsrs(p.Client)
Set csr.RemoteTransaction, csr.Priority
Copy message and segment data to csr's segment area
and set csr.PacketDelivery to that delivered.
Clear csr.PacketDelivery
Clear csr.VerifyInterval
SaveNetworkAddress( csr, p )
endif
if packetgroup not complete then
Timeout( csr, TS3(p.Client), RemoteClientTimeout )
return;
endif
endPacketGroup:
{ We have received complete packet group. }
if APG(p) then NotifyClient( csr, p, OK )
endif
| if NERset(p) and CMG(p) then
| Queue waiting for continuation packet group.
| Timeout( csr, TS3(csr.Client), RemoteClientTimeout )
| return
| endif
{ Deliver request message. }
if GroupId(csr.Server) then
For each server identified by csr.Server
Replicate csr and associated data segment.
if CMDset(csr) and Server busy then
Discard csr and data
else
Deliver or invoke csr for each Server.
if not DGMset(csr) then queue for Response
else Timeout( csr, TS4(csr.Client), FreeCsr )
endfor
else
if CMDset(csr) and Server busy then
Discard csr and data
else
Cheriton [page 76]
RFC1045 VMTP February 1988
Deliver or invoke csr for this server.
if not DGMset(csr) then queue for Response
else Timeout( csr, TS4(csr.Client), FreeCsr )
endif
end HandleRequest
Notes:
1. A Request received that specifies a Client that is a local
entity should be a Request forwarded by a remote server to a
local Server.
2. An alternative structure for handling a Request sent to a
group when there are multiple local group members is to
create a remote CSR for each group member on reception of the
first packet and deliver a copy of each packet to each such
remote CSR as each packet arrives.
Cheriton [page 77]
RFC1045 VMTP February 1988
5.8. Management Operations
VMTP uses management operations (invoked as remote procedure calls) to
effectively acknowledge packet groups and request retransmissions. The
following routine is invoked by the Server's management module on
request from the Client.
NotifyVmtpServer(server,clientId,transact,delivery,code)
Find csr with same RemoteTransaction and RemoteClient
as clientId and transact.
if not found or csr.State not Responded then return
if DGMset(csr) then
if transmission of Response in progress then
Abort transmission
if code is migrated then
restart transmission with new host addr.
if Retry then Report protocol error
return
endif
select on code
case RETRY:
if csr.RetransCount > MaxRetrans(clientId) then
if response data segment then
Discard data and mark as RESPONSE_DISCARDED
| if NERset(csr) and subsequent csr then
| Deallocate csr and use later csr for
| future duplicate suppression
| endif
return
endif
increment csr.RetransCount
Set csr.TransmissionMask to missing segment blocks,
as specified by delivery
SendPacketGroup( csr )
Timeout( csr, TS3(csr.Client), RemoteClientTimeout )
case BUSY:
if csr.TimeLimit exceeded then
if response data segment then
Discard data and mark as RESPONSE_DISCARDED
| if NERset(csr) and subsequent csr then
| Deallocate csr and use later csr for
| future duplicate suppression
| endif
endif
endif
Set csr.TransmissionMask for full retransmission
Clear csr.RetransCount
Cheriton [page 78]
RFC1045 VMTP February 1988
Timeout( csr, TS3(csr.Server), RemoteClientTimeout )
return
case ENTITY_MIGRATED:
Get new host address for entity
Set csr.TransmissionMask for full retransmission
Clear csr.RetransCount
SendPacketGroup( csr )
Timeout( csr, TS3(csr.Server), RemoteClientTimeout )
return
case default:
Abort transmission of Response if in progress.
if response data segment then
Discard data and mark as RESPONSE_DISCARDED
if NERset(csr) and subsequent csr then
Deallocate csr and use later csr for
future duplicate suppression
endif
return
endselect
end NotifyVmtpServer
Notes:
1. A NotifyVmtpServer operation requesting retransmission of
the Response is acceptable only if the Response was not
idempotent. When the Response is idempotent, the Client must
be prepared to retransmit the Request to effectively request
retransmission of the Response.
2. A NotifyVmtpServer operation may be received while the
Response is being transmitted. If an error return, as an
efficiency, the transmission should be aborted, as suggested
when the Response is a datagram.
3. A NotifyVmtpServer operation indicating OK or an error
allows the Server to discard segment data and not provide for
subsequent retransmission of the Response.
5.8.1. HandleRequestNoCSR
When a Request is received from a Client for which the node has no CSR,
the node allocates and initializes a CSR for this Client and does a
callback to the Client's VMTP management module to get the Principal,
Process and other information associated with this Client. It also
Cheriton [page 79]
RFC1045 VMTP February 1988
checks that the TransactionId is correct in order to filter out
duplicates.
HandleRequestNoCSR( p, psize )
| if Secure(p) then
| Allocate and init CSR
| SaveSourceHostAddr( csr, p )
| ProbeRemoteClient( csr, p, AUTH_PROBE )
| if no response or error then
| delete CSR
| return
| Decrypt( csr.Key, p, psize )
| if p.Checksum not null then
| if not VerifyChecksum(p, psize) then return;
| if OppositeByteOrder(p) then ByteSwap( p, psize )
| if psize not equal sizeof(VmtpHeader) + 4*p.Length then
| NotifyClient(NULL, p, VMTP_ERROR )
| return
| HandleRequest( csr, p, psize )
| return
if Server does not exist then
NotifyClient( csr, p, NONEXISTENT_ENTITY )
return
endif
if security required by server then
NotifyClient(csr, p, SECURITY_REQUIRED )
return
endif
Allocate and init CSR
SaveSourceHostAddr( csr, p );
if server requires Authentication then
ProbeRemoteClient( csr, p, AUTH_PROBE )
if no response or error then
delete CSR
return
endif
{ Setup immediately as a new message transaction }
set csr.Server to p.Server
set csr.RemoteTransaction to p.Transaction-1
HandleRequest( csr, p, psize )
endif
Notes:
1. A Probe request is always handled as a Request not requiring
authentication so it never generates a callback Probe to the
Cheriton [page 80]
RFC1045 VMTP February 1988
Client.
2. If the Server host retains remote client CSR's for longer
than the maximum packet lifetime and the Request
retransmission time, and the host has been running for at
least that long, then it is not necessary to do a Probe
callback unless the Request is secure. A Probe callback can
take place when the Server asks for the Process or
PrincipalId associated with the Client.
Cheriton [page 81]
RFC1045 VMTP February 1988
5.9. Timeouts
The server must implement a timeout for remote client CSRs. There is a
timeout for each CSR in the server.
RemoteClientTimeout( csr )
select on csr.State
case Responded:
if RESPONSE_DISCARDED then
mark as timed out
Make a candidate for reuse.
return
if csr.RetransCount > MaxRetrans(Client) then
discard Response
mark CSR as RESPONSE_DISCARDED
Timeout(csr, TS4(Client), RemoteClientTimeout)
return
increment csr.RetransCount
{ Retransmit Response or forwarded Request }
Set APG to get acknowledgement.
SendPacketGroup( csr )
Timeout( csr, TS3(Client), RemoteClientTimeout )
return
case ReceivingRequest:
if csr.RetransCount > MaxRetrans(csr.Client)
or DGMset(csr) or NRTset(csr) then
Modify csr.segmentSize and csr.MsgDelivery
to indicate packets received.
if MDMset(csr) then
Invoke processing on Request
return
else
discard Request and reuse CSR
(Note: Need not remember Request discarded.)
return
increment csr.RetransCount
NotifyClient( csr, p, RETRY )
Timeout( csr, TS3(Client), RemoteClientTimeout )
return
default:
Report error - invalid state for RemoteClientTimeout
endselect
end RemoteClientTimeout
Notes:
1. When a CSR in the Responded state times out after discarding
Cheriton [page 82]
RFC1045 VMTP February 1988
the Response, it can be made available for reuse, either by
the same Client or a different one. The CSR should be kept
available for reuse by the Client for as long as possible to
avoid unnecessary callback Probes.
Cheriton [page 83]
RFC1045 VMTP February 1988
6. Concluding Remarks
This document represents a description of the current state of the VMTP
design. We are currently engaged in several experimental
implementations to explore and refine all aspects of the protocol.
Preliminary implementations are running in the UNIX 4.3BSD kernel and in
the V kernel.
Several issues are still being discussed and explored with this
protocol. First, the size of the checksum field and the algorithm to
use for its calculation are undergoing some discussion. The author
believes that the conventional 16-bit checksum used with TCP and IP is
too weak for future high-speed networks, arguing for at least a 32-bit
checksum. Unfortunately, there appears to be limited theory covering
checksum algorithms that are suitable for calculation in software.
Implementation of the streaming facilities of VMTP is still in progress.
This facility is expected to be important for wide-area, long delay
communication.
Cheriton [page 84]
RFC1045 VMTP February 1988
I. Standard VMTP Response Codes
The following are the numeric values of the response codes used in VMTP.
0 OK
1 RETRY
2 RETRY_ALL
3 BUSY
4 NONEXISTENT_ENTITY
5 ENTITY_MIGRATED
6 NO_PERMISSION
7 NOT_AWAITING_MSG
8 VMTP_ERROR
9 MSGTRANS_OVERFLOW
10 BAD_TRANSACTION_ID
11 STREAMING_NOT_SUPPORTED
12 NO_RUN_RECORD
13 RETRANS_TIMEOUT
14 USER_TIMEOUT
15 RESPONSE_DISCARDED
16 SECURITY_NOT_SUPPORTED
17 BAD_REPLY_SEGMENT
18 SECURITY_REQUIRED
19 STREAMED_RESPONSE
20 TOO_MANY_RETRIES
21 NO_PRINCIPAL
Cheriton [page 85]
RFC1045 VMTP February 1988
22 NO_KEY
23 ENCRYPTION_NOT_SUPPORTED
24 NO_AUTHENTICATOR
25-63 Reserved for future VMTP assignment.
Other values of the codes are available for use by higher level
protocols. Separate protocol documents will specify further standard
values.
Applications are free to use values starting at 0x00800000 (hex) for
application-specific return values.
Cheriton [page 86]
RFC1045 VMTP February 1988
II. VMTP RPC Presentation Protocol
For complete generality, the mapping of the procedures and the
parameters onto VMTP messages should be defined by a RPC presentation
protocol. In the absence of an accepted standard protocol, we define an
RPC presentation protocol for VMTP as follows.
Each procedure is assigned an identifying Request Code. The Request
code serves effectively the same as a tag field of variant record,
identifying the format of the Request and associated Response as a
variant of the possible message formats.
The format of the Request for a procedure is its Request Code followed
by its parameters sequentially in the message control block until it is
full.
The remaining parameters are sent as part of the message segment data
formatted according to the XDR protocol (RFC??). In this case, the
size of the segment is specified in the SegmentSize field.
The Response for a procedure consists of a ResponseCode field followed
by the return parameters sequentially in the message control block,
except if there is a parameter returned that must be transmitted as
segment data, its size is specified in the SegmentSize field and the
parameter is stored in the SegmentData field.
Attributes associated with procedure definitions should indicate the
Flags to be used in the RequestCode. Request Codes are assigned as
described below.
II.1. Request Code Management
Request codes are divided into Public Interface Codes and
application-specific, according to whether the PIC value is set. An
interface is a set of request codes representing one service or module
function. A public interface is one that is to be used in multiple
independently developed modules. In VMTP, public interface codes are
allocated in units of 256 structured as
+-------------+----------------+-------------------+
| ControlFlags| Interface | Version/Procedure |
+-------------+----------------+-------------------+
8 bits 16 bits 8 bits
An interface is free to allocate the 8 bits for version and procedure as
desired. For example, all 8 bits can be used for procedures. A module
requiring more than 256 Version/Procedure values can be allocated
Cheriton [page 87]
RFC1045 VMTP February 1988
multiple Interface values. They need not be consecutive Interface
values.
Cheriton [page 88]
RFC1045 VMTP February 1988
III. VMTP Management Procedures
Standard procedures are defined for VMTP management, including creation,
deletion and query of entities and entity groups, probing to get
information about entities, and updating message transaction information
at the client or the server.
The procedures are implemented by the VMTP manager that constitutes a
portion of every complete VMTP module. Each procedure is invoked by
sending a Request to the VMTP manager that handles the entity specified
in the operation or the local manager. The Request sent using the
normal Send operation with the Server specified as the well-known entity
group VMTP_MANGER_GROUP, using the CoResident Entity mechanism to direct
the request to the specific manager that should handle the Request.
(The ProbeEntity operation is multicast to the VMTP_MANAGER_GROUP if the
host address for the entity is not known locally and the host address is
determined as the host address of the responder. For all other
operations, a ProbeEntity operation is used to determine the host
address if it is not known.) Specifying co-resident entity 0 is
interpreted as the co-resident with the invoking process. The
co-resident entity identifier may also specify a group in which case,
the Request is sent to all managers with members in this group.
The standard procedures with their RequestCode and parameters are listed
below with their semantics. (The RequestCode range 0xVV000100 to
0xVV0001FF is reserved for use by the VMTP management routines, where VV
is any choice of control flags with the PIC bit set. The flags are set
below as required for each procedure.)
0x05000101 - ProbeEntity(CREntity, entityId, authDomain) -> (code,
<staterec>)
Request and return information on the specified entity
in the specified authDomain, sending the Request to the
VMTP management module coresident with CREntity. An
error return is given if the requested information
cannot be provided in the specified authDomain. The
<staterec> returned is structured as the following
fields.
Transaction identifier
The current or next transaction
identifier being used by the probed
entity.
ProcessId: 64 bits
Identifier for client process. The
meaning of this is specified as part of
Cheriton [page 89]
RFC1045 VMTP February 1988
the Domain definition.
PrincipalId The identifier for the principal or
account associated with the process
specified by ProcessId. The meaning of
this field is specified as part of the
Domain definition.
EffectivePrincipalId
The identifier for the principal or
account associated with the Client port,
which may be different from the
PrincipalId especially if this is an
nested call. The meaning of this field
is specified as part of the Domain
definition.
The code field indicates whether this is an error
response or not. The codes and their interpretation
are:
OK
No error. Probe was completed OK.
NONEXISTENT_ENTITY
Specified entity does not exist.
ENTITY_MIGRATED
The entity has migrated and is no longer at the host to
which the request was sent.
NO_PERMISSION
Entity has refused to provide ProbeResponse.
VMTP_ERROR
The Request packet group was in error relative to the
VMTP protocol specification.
"default"
Some type of error - discard ProbeResponse.
0x0D000102 - AuthProbeEntity(CREntity,entityId,authDomain,randomId) ->
(code,ProbeAuthenticator,EncryptType,EntityAuthenticator)
Request authentication of the entity specified by
entityId from the VMTP manager coresident with CREntity
in authDomain authentication domain, returning the
Cheriton [page 90]
RFC1045 VMTP February 1988
information contained in the return parameters. The
fields are set the same as that specified for the basic
ProbeResponse except as noted below.
ProbeAuthenticator
20 bytes consisting of the EntityId, the
randomId and the probed Entity's current
Transaction value plus a 32-bit checksum
for these two fields (checksummed using
the standard packet Checksum algorithm),
all encrypted with the Key supplied in
the Authenticator.
EncryptType An identifier that identifies the
variant of encryption method being used
by the probed Entity for packets it
transmits and packets it is able to
receive. (See Appendix V.) The
high-order 8 bits of the EncryptType
contain the XOR of the 8 octets of the
PrincipalId associated with private key
used to encrypt the EntityAuthenticator.
This value is used by the requestor or
Client as an aid in locating the key to
decrypt the authenticator.
EntityAuthenticator
(returned as segment data) The
ProcessId, PrincipalId,
EffectivePrincipal associated with the
ProbedEntity plus the private
encryption/decryption key and its
lifetime limit to be used for
communication with the Entity. The
authenticator is encrypted with a
private key associated with the Client
entity such that it can be neither read
nor forged by a party not trusted by the
Client Entity. The format of the
Authenticator in the message segment is
shown in detail in Figure III-1.
Key: 64 bits Encryption key to be used for encrypting
and decrypting packets sent to and
received from the probed Entity. This
is the "working" key for packet
transmissions. VMTP only uses private
Cheriton [page 91]
RFC1045 VMTP February 1988
+-----------------------------------------------+
| ProcessId (8 octets) |
+-----------------------------------------------+
| PrincipalId (8 octets) |
+-----------------------------------------------+
| EffectivePrincipalId (8 octets) |
+-----------------------------------------------+
| Key (8 octets) |
+-----------------------------------------------+
| KeyTimeLimit |
+-----------------------------------------------+
| AuthDomain |
+-----------------------------------------------+
| AuthChecksum |
+-----------------------------------------------+
Figure III-1: Authenticator Format
key encryption for data transmission.
KeyTimeLimit: 32 bits
The time in seconds since Dec. 31st,
1969 GMT at which one should cease to
use the Key.
AuthDomain: 32 bits
The authentication domain in which to
interpret the principal identifiers.
This may be different from the
authDomain specified in the call if the
Server cannot provide the authentication
information in the request domain.
AuthChecksum: 32 bits
Contains the checksum (using the same
Checksum algorithm as for packet) of
KeyTimeLimit, Key, PrincipalId and
EffectivePrincipalId.
Notes:
1. A authentication Probe Request and Response
are sent unencrypted in general because it is
used prior to there being a secure channel.
Therefore, specific fields or groups of
fields checksummed and encrypted to prevent
unauthorized modification or forgery. In
Cheriton [page 92]
RFC1045 VMTP February 1988
particular, the ProbeAuthenticator is
checksummed and encrypted with the Key.
2. The ProbeAuthenticator authenticates the
Response as responding to the Request when
its EntityId, randomId and Transaction values
match those in the Probe request. The
ProbeAutenticator is bound to the
EntityAutenticator by being encrypted by the
private Key contained in that authenticator.
3. The authenticator is encrypted such that it
can be decrypted by a private key, known to
the Client. This authenticator is presumably
obtained from a key distribution center that
the Client trusts. The AuthChecksum prevents
undetected modifications to the
authenticator.
0x05000103 - ProbeEntityBlock( entityId ) -> ( code, entityId )
Check whether the block of 256 entity identifiers
associated with this entityId are in use. The entityId
returned should match that being queried or else the
return value should be ignored and the operation redone.
0x05000104 - QueryVMTPNode( entityId ) -> (code, MTU, flags, authdomain,
domains, authdomains, domainlist)
Query the VMTP management module for entityId to get
various module- or node-wide parameters, including: (1)
MTU - Maximum transmission unit or packet size handled
by this node. (2) flags- zero or more of the following
bit fields:
1 Handles streamed Requests.
2 Can issue streamed message transactions
for clients.
4 Handles secure Requests.
8 Can issue secure message transactions.
The authdomain indicates the primary authentication
domain supported. The domains and authdomains
parameters indicate the number of entity domains and
authentication domains supported by this node, which are
listed in the data segment parameter domainlist if
Cheriton [page 93]
RFC1045 VMTP February 1988
either parameter is non-zero. (All the entity domains
precede the authentication domains in the data segment.)
0x05000105 - GetRequestForwarder( CREntity, entityId1 ) -> (code,
entityId2, principal, authDomain)
Return the forwarding server's entity identifer and
principal for the forwarder of entityId1. CREntity
should be zero to get the local VMTP management module.
0x05000106 - CreateEntity( entityId1 ) -> ( code, entityId2 )
Create a new entity and return its entity identifier in
entityId2. The entity is created local to the entity
specified in entityId1 and local to the requestor if
entityId1 is 0.
0x05000107 - DeleteEntity( entityId ) -> ( code )
Delete the entity specified by entityId, which may be a
group. If a group, the deletion is only on a best
efforts basis. The client must take additional measures
to ensure complete deletion if required.
0x0D000108 -QueryEntity( entityId ) -> ( code, descriptor )
Return a descriptor of entityId in arg of a maximum of
segmentSize bytes.
0x05000109 - SignalEntity( entityId, arg )->( code )
Send the signal specified by arg to the entity specified
by entityId. (arg is 32 bits.)
0x0500010A - CreateGroup(CREntity,entityGroupId,entityId,perms)->(code)
Request that the VMTP manager local to CREntity create
an new entity group, using the specified entityGroupId
with entityId as the first member and permissions
"perms", a 32-bit field described later. The invoker is
registered as a manager of the new group, giving it the
permissions to add or remove members. (Normally
CREntity is 0, indicating the VMTP manager local to the
requestor.)
0x0500010B - AddToGroup(CREntity, entityGroupId, entityId,
perms)->(code)
Request that the VMTP manager local to CREntity add the
specified entityId to the entityGroupId with the
specified permissions. If entityGroupId specifies a
restricted group, the invoker must have permission to
add members to the group, either because the invoker is
Cheriton [page 94]
RFC1045 VMTP February 1988
a manager of the group or because it was added to the
group with the required permissions. If CREntity is 0,
then the local VMTP manager checks permissions and
forwards the request with CREntity set to entityId and
the entityId field set to a digital signature (see
below) of the Request by the VMTP manager, certifying
that the Client has the permissions required by the
Request. (If entityGroupId specifies an unrestricted
group, the Request can be sent directly to the handling
VMTP manager by setting CREntity to entityId.)
0x0500010C - RemoveFromGroup(CREntity, entityGroupId, entityId)->(code)
Request that the VMTP manager local to CREntity remove
the specified entityId from the group specified by
entityGroupId. Normally CREntity is 0, indicating the
VMTP manager local to the requestor. If CREntity is 0,
then the local VMTP manager checks permissions and
forwards the request with CREntity set to entityId and
the entityId field a digital signature of the Request by
the VMTP manager, certifying that the Client has the
permissions required by the Request.
0x0500010D - QueryGroup( entityId )->( code, record )...
Return information on the specified entity. The
Response from each responding VMTP manager is (code,
record). The format of the record is (memberCount,
member1, member2, ...). The Responses are returned on a
best efforts basis; there is no guarantee that responses
from all managers with members in the specified group
will be received.
0x0500010E - ModifyService(entityId,flags,count,pc,threadlist)->(code,
count)
Modify the service associated with the entity specified
by entityId. The flags may indicate a message service
model, in which case the call "count" parameter
indicates the maximum number of queued messages desired;
the return "count" parameter indicates the number of
queued message allowed. Alternatively, the "flags"
parameters indicates the RPC thread service model, in
which case "count" threads are requested, each with an
inital program counter as specified and stack, priority
and message receive area indicated by the threadlist.
In particular, "threadlist" consists of "count" records
of the form
(priority,stack,stacksize,segment,segmentsize), each one
assigned to one of the threads. Flags defined for the
Cheriton [page 95]
RFC1045 VMTP February 1988
"flags" parameter are:
1 THREAD_SERVICE - otherwise the message
model.
2 AUTHENTICATION_REQUIRED - Sent a Probe
request to determine principal
associated with the Client, if not
known.
4 SECURITY_REQUIRED - Request must be
encrypted or else reject.
8 INCREMENTAL - treat the count value as
an increment (or decrement) relative to
the current value rather than an
absolute value for the maximum number of
queued messages or threads.
In the thread model, the count must be a positive
increment or else 0, which disables the service. Only a
count of 0 terminates currently queued requests or
in-progress request handling.
0x4500010F -
NotifyVmtpClient(client,cntrl,recSeq,transact,delivery,code)->()
Update the state associated with the transaction
specified by client and transact, an entity identifier
and transaction identifier, respectively. This
operation is normally used only by another VMTP
management module. (Note that it is a datagram
operation.) The other parameters are as follows:
ctrl A 32-bit value corresponding to 4th
32-bit word of the VMTP header of a
Response packet that would be sent in
response to the Request that this is
responding to. That is, the control
flags, ForwardCount, RetransmitCount and
Priority fields match those of the
Request. (The NRS flag is set if the
receiveSeqNumber field is used.) The
PGCount subfield indicates the number of
previous Request packet groups being
acknowledged by this Notify operation.
(The bit fields that are reserved in
Cheriton [page 96]
RFC1045 VMTP February 1988
this word in the header are also
reserved here and must be zero.)
recSeq Sequence number of reception at the
Server if the NRS flag is set in the
ctrl parameter, otherwise reserved and
zero. (This is used for sender-based
logging of message activity for replay
in case of failure - an optional
facility.)
delivery Indicates the segment blocks of the
packet group have been received at the
Server.
code indicates the action the client should
take, as described below.
The VMTP management module should take action on this
operation according to the code, as specified below.
OK Do nothing at this time, continue
waiting for the response with a reset
timer.
RETRY Retransmit the request packet group
immediately with at least the segment
blocks that the Server failed to
receive, the complement of those
indicated by the delivery parameter.
RETRY_ALL Retransmit the request packet group
immediately with at least the segment
blocks that the Server failed to
receive, as indicated by the delivery
field plus all subsequently transmitted
packets that are part of this packet
run. (The latter is applicable only for
streamed message transactions.)
BUSY The server was unable to accept the
Request at this time. Retry later if
desired to continue with the message
transaction.
NONEXISTENT_ENTITY
Specified Server entity does not exist.
Cheriton [page 97]
RFC1045 VMTP February 1988
ENTITY_MIGRATED The server entity has migrated and is no
longer at the host to which the request
was sent. The Server should attempt to
determine the new host address of the
Client using the VMTP management
ProbeEntity operation (described
earlier).
NO_PERMISSION Server has not authorized reception of
messages from this client.
NOT_AWAITING_MSG
The conditional message delivery bit was
set for the Request packet group and the
Server was not waiting for it so the
Request packet group was discarded.
VMTP_ERROR The Request packet group was in error
relative to the VMTP protocol
specification.
BAD_TRANSACTION_ID
Transaction identifier is old relative
to the transaction identifier held for
the Client by the Server.
STREAMING_NOT_SUPPORTED
Server does not support multiple
outstanding message transactions from
the same Client, i.e. streamed message
transactions.
SECURITY_NOT_SUPPORTED
The Request was secure and this Server
does not support security.
SECURITY_REQUIRED
The Server is refusing the Request
because it was not encrypted.
NO_RUN_RECORD Server has no record of previous packets
in this run of packet groups. This can
occur if the first packet group is lost
or if the current packet group is sent
significantly later than the last one
and the Server has discarded its client
state record.
Cheriton [page 98]
RFC1045 VMTP February 1988
0x45000110 - NotifyVmtpServer(server,client,transact,delivery,code)->()
Update the server state associated with the transaction
specified by client and transact, an entity identifier
and transaction identifier, respectively. This
operation is normally used only by another VMTP
management module. (Note that it is a datagram
operation.) The other parameters are as follows:
delivery Indicates the segment blocks of the
Response packet group that have been
received at the Client.
code indicates the action the Server should
take, as listed below.
The VMTP management module should take action on this
operation according to the code, as specified below.
OK Client is satisfied with Response data.
The Server can discard the response
data, if any.
RETRY Retransmit the Response packet group
immediately with at least the segment
blocks that the Client failed to
receive, as indicated by the delivery
parameter. (The delivery parameter
indicates those segment blocks received
by the Client).
RETRY_ALL Retransmit the Response packet group
immediately with at least the segment
blocks that the Client failed to
receive, as indicated by the (complement
of) the delivery parameter. Also,
retransmit all Response packet groups
send subsequent to the specified packet
group.
NONEXISTENT_ENTITY
Specified Client entity does not exist.
ENTITY_MIGRATED The Client entity has migrated and is no
longer at the host to which the response
was sent.
RESPONSE_DISCARDED
Cheriton [page 99]
RFC1045 VMTP February 1988
The Response was discarded and no longer
of interest to the Client. This may
occur if the conditional message
delivery bit was set for the Response
packet group and the Client was not
waiting for it so the Response packet
group was discarded.
VMTP_ERROR The Response packet group was in error
relative to the VMTP protocol
specification.
0x41000111 -
NotifyRemoteVmtpClient(client,ctrl,recSeq,transact,delivery,code->()
The same as NotifyVmtpClient except the co-resident
addressing is not used. This operation is used to
update client state that is remote when a Request is
forwarded.
Note the use of the CRE bit in the RequestCodes to route the request to
the correct VMTP management module(s) to handle the request.
III.1. Entity Group Management
An entity in a group has a set of permissions associated with its
membership, controling whether it can add or remove others, whether it
can remove itself, and whether others can remove it from the group. The
permissions for entity groups are as follows:
VMTP_GRP_MANAGER 0x00000001 { Manager of group. }
VMTP_REM_BY_SELF 0x00000002 { Can be removed self. }
VMTP_REM_BY_PRIN 0x00000004 { Can be rem'ed by same principal}
VMTP_REM_BY_OTHE 0x00000008 { Can be removed any others. }
VMTP_ADD_PRIN 0x00000010 { Can add by same principal. }
VMTP_ADD_OTHE 0x00000020 { Can add any others. }
VMTP_REM_PRIN 0x00000040 { Can remove same principal. }
VMTP_REM_OTHE 0x00000080 { Can remove any others. }
To remove an entity from a restricted group, the invoker must have
permission to remove that entity and the entity must have permissions