Multi-part Messages in KMIP John Leiseboer, QuintessenceLabs

Response Message Response Header Protocol Version Time Stamp Batch Count Batch Item Operation Unique Batch Item ID Result Status Response Payload Message Extension Vendor ID = QLABS_MULTI_RESPONSE_ID Criticality Indicator = TRUE Vendor Extension = Packet Number = n Final Indicator = TRUE | FALSE [Length] [Length] … [Length] We have appended a message extension that indicates that the response consists of multiple parts, the packet (or sequence) number of the part contained in this message, and a final indicator (TRUE => last part; FALSE => not the last part). The criticality indicator is set to TRUE, meaning that if the receiver does not understand the extension, it should throw away the message. No other part of the message is changed. Each response message of the multi-part response is formatted as shown; i.e. each message part is a complete response message. It is only the contents of the response payload that get split across packets

What the receiving party needs to do The party receiving this form of message must identify and parse the message extension. If the receiver does not understand the extension, it throws away the message. If it does understand the message extension, then it processes the response payload. How it processes the payload is operation and implementation dependent. One way of processing, is to parse the (partial) response, and if it makes sense, do stuff with it, like return it to the caller. If the partial response cannot be fully parsed, perhaps because the part ends part way through a structure or other item, then the receiver needs to buffer the partial response until enough of the rest of the response (which come in one or more following messages) can be reassembled to create useful results. When the receiver sees that the final indicator is set to TRUE, it knows that the multi-part response has finished, and the receiver should do whatever it has to do when it sees the end of a response.

Why is there a packet number? Although KMIP currently specifies TLS (over TCP), which guarantees packet order, no lost packets, and no duplicated packets, this is not the case for all protocols. And in many systems, connections can be lost for a variety of reasons. The packet number allows sessions to restart from where they were interrupted (very useful for very large messages which is a likely scenario for multi-part messages), and to assist the receiver in message reassembly if a protocol that can lose, duplicate or reorder packets is used.

What are the item lengths specified in the response payload? The length of each item in the response payload is just that - the length of the item, but ONLY IF IT IS CONTAINED ENTIRELY WITHIN the current part. There is an implicit requirement here that the sender know and correctly populate the length of the items that fit entirely within the current part. Where items spill over a part boundary, that item's length is indicated in the message extension for the part containing the end of the item. The diagram on the next page shows an example.

Structure (L1=?) { Structure (L2=?) { Structure (L3=?) { Structure (L4=?) { Item (L5) {}. Item (L6=?){ PACKET #1, FINAL = FALSE. } Structure (L7=?) { PACKET #2, FINAL = FALSE, L6, L4. } PACKET #3, FINAL = FALSE, L7, L3. Item (L8) {} Item (L9) {} } PACKET #4, FINAL = TRUE, L2, L1 Response Payload Message Extension

The structures with length L1, L2, L3 and L4, as well as the item of length L6 all start in packet #1, and spill over the packet boundary. Their lengths are unknown at the time of transmission of packet #1 (indicated by Li=?), so a special "unknown/indefinite" length value is written in the length field for these items (FF..FF could be used). The item with length L6 and the structure with length L4 end in packet #2. The sender can now indicate the length of these items in the message extension for packet #2. The receiver uses this information to identify the end of these items. In packet #3, the structures with length L7 and L3 end. The sender indicates the length of these structures in the message extension. And finally, the structures with length L2 and L1 end in the final packet, #4. Again the sender indicates these lengths in the message extension. Note the order of the length indications in the message extension. Order is LIFO (last in first out - like a stack). To put this in really simple terms: a) if the sender knows the length when it sends an item, then it fills in the length of the item at the start of the item (as in current specification); b) if the sender does not know the length of the item when it sends the item, it fills in a special "unknown" length value at the start of the item, calculates the item's length across all parts as it streams the item, and indicates the length in the message extension for the packet containing the end of the item.

Request Message Request Header Protocol Version … Batch Count Batch Item Operation Unique Batch Item ID Request Payload Message Extension Vendor ID = QLABS_MULTI_REQUEST_ID Criticality Indicator = TRUE Vendor Extension = Packet Number = n Final Indicator = TRUE | FALSE [Length] [Length] … [Length] The same mechanism looks like it might also work for streaming Request Messages from the Client to the Server. This opens up the possibility of full-duplex streaming between client and server. The server could begin to send a response before receiving the complete set of request parts.

ClientServer Request packet #1 Request packet #2 Request packet #u Request packet #n, FINAL Response packet #1 Response packet #2 Response packet #3 Response packet #i Response packet #j Response packet #k Response packet #m, FINAL Client sends multi-part request message. Concurrently, server sends multi- part response message when it has sufficient request message parts to begin streaming out response parts. Request and response packet numbers generally have no relationship to each other; e.g. Request #1 triggers no response. Request #1 combined with Request #2 triggers Responses #1, #2, and #3, and possibly even Responses #i, #j, …. If the server detects an unrecoverable error early in the request stream, it could initiate an error response that gives the client an opportunity to abort its request stream; i.e. server FINAL could be returned before client FINAL is sent.