Zero-Knowledge Command Protocol

Freedom Services 2.0 Archive Validated

$Id: protocol.html,v 1.5 2001/07/10 20:36:49 sam Exp $
Revision Comments
1.1 Author(s): Roger McFarlane (roger@zks.net), Philippe Boucher (philippe@zks.net); 

Initial draft. 

1.2 Incorporated suggestions based on feedback from Adam Shostack (adam@zks.net).

Contents

  1. Introduction
    1. Motivation
    2. Requirements
    3. Non-requirements
  2. Data Types
  3. Packet Format
    1. Header
    2. Parameter
    3. MAC
  4. Security
  5. Examples
  6. References

1 - Introduction

Goto : [top]
This document describes the Zero-Knowledge Command Protocol (ZKCP).

See Also:

Your feedback is welcome. Please direct your comments, criticism, and suggestions to the author of this document and/or the Core Development Team (core-team@zks.net"). 

1.1 - Motivation

ZKCP is designed to be a general purpose communication format. Currently, almost all inter-entity stream communication performed by software which has been developed at Zero-Knowledge Systems (ZKS) uses the aging Zero-Knowledge Interactive Protocol (ZKIP). ZKCP is positioned to replacs ZKIP as the lingua franca of the core servers.

The application which initially motivated the development of ZKCP was the Zero-Knowledge Database Server. The verbosity and overhead associated with ZKIP was perceived to be detrimental to the performance of the server, which is a perfomance critical component. At the same time, schedule and legacy constraints prevented the logical progression to SQL. Rather than inventing a context specific interim (read throw-away) solution, the Core Development Team elected to create a successor to ZKIP for use with the database server.

ZKCP is an attempt to fix many of the problems inherent in ZKIP. Its first application will be that of the database server; however, it is intended to phase out ZKIP as the Freedom software matures. ZKCP is suitable for server-to-server communication, client-server communication, client-to-client communications, and for serialization to persistant storage.

1.2 - Requirements

1.3 - Non-requirements

2 - Datatypes

Goto : [top]
The following are the basic data types used by the various parts of the protocol.
 
Datatype Format Description
uint32 4 bytes in NBO Unsigned 32 bit value
uint16 2 bytes in NBO Unsigned 16 bit value
uint8 1 byte Unsigned 8 bit value
TimeStamp 8 bytes in NBO An unsigned 64 bit integral value which counts the number of seconds since 1 January 1970 00:00:00 (in UTC)

3 - Format

Goto : [top]
A command packet is composed of the following pieces:
+----------+--------------+--------------+-------+--------------+---------+
|  Header  |  Parameter1  |  Parameter2  |  ...  |  ParameterN  |   MAC   |
+----------+--------------+--------------+-------+--------------+---------+
                  |                                     |
                  +-------->  Optional Params  <--------+
  1. Header Format
  2. Parameter Format
  3. MAC Format

3.1 - Header Format

Goto : [top] [format]
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
|  0  |  1  |  2  |  3  |  4  |  5  |  6  |  7  |  8  |  9  | 10  | 11  | 12  | 13  | 14  | 15  | 16  | 17  |
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
   |     |     |     |     |                 |     |                                         |    |     |
   +--+--+     |     |     +--------+--------+     +--------------------+------------------- +    |     |
      |        |     |              |                                   |                         |     |
      |        |     |              |                                   |                         |     +--> Reserved
      |        |     |              |                                   |                         |
      |        |     |              |                                   |                         +--> Command ID
      |        |     |              |                                   |
      |        |     |              |                                   +--> Time Stamp
      |        |     |              |
      |        |     |              +--> Sequence Number
      |        |     |         
      |        |     +--> Flags
      |        |
      |        +--> Version
      |
      +--> Prefix
Bytes Field Datatype Description
0 - 1 Buffer Prefix uint16 A constant value (i.e., magic number) which identifies the data buffer as being a command protocol packet.
2 Version uint8 Packet version (current value is 1)
3 Flags uint8 Bit field. 
Bit 0 (low order bit) 
Link Authenitication Key Value (LAKV). This single bit value is used to denote which authentication key was used to compute the MAC. This allows for link key rotation over the lifetime of a communication session. 
Bit 1 - 7 
Reserved. Must be zero (0) 
4 - 7 Sequence uint32 Sequence number
8 - 15 Time TimeStamp Time at which the packet was generated
16 Command ID uint8 The numeric identifier of the command which this packet represents
17 reserved uint8 Reserved. Must be zero (0).

3.2 - Parameter Format

Goto : [top] [format]
A command packet may have zero (0) or more parameters.
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-------
|  0  |  1  |  2  |  3  |  4  |  5  |  6  |  7  |  8  |  ...
+-----+-----+-----+-----+-----+-----+-----+-----+-----+-------
   |     |     |                 |     |     
   |     |     +--------+--------+     +--------+------ ...
   |     |              |                       |
   |     |              |                       +--> Value Data
   |     |              |         
   |     |              +--> Size
   |     |
   |     +--> Type ID
   |
   +--> Param ID
Bytes Field Datatype Description
0 Param ID uint8 Identification code for the parameter. The Param ID zero (0) is reserved for as the MAC identifier (see MAC Format)
1 Type ID uint8 Identifies the type of the parameter's value. This would denote, for instance, that a parameter was a binary blob or an integer. The Type ID zero (0) is reserved for as the MAC type identifier (see MAC Format).
2 - 5 Size uint32 Size of the value data (in octets). 

{ In most cases, a 16-bit field would suffice; however, there are applications in which a 16-bit field would be insufficient (e-mail, for instance). - roger }

6 - ? Data raw bytes Format depends on the particular data type (i.e., the Type ID value). Usually an NBO integer like format or a byte array.

3.4 - MAC Format

Goto : [top] [format]
The Message Authentication Code is a special case parameter that is included with every command packet.
+-----+-----+-----+-----+-----+-----+-----+-----+-----+----------------+
|  0  |  1  |  2  |  3  |  4  |  5  |  6  |  7  |  8  |    9 ... 20    |
+-----+-----+-----+-----+-----+-----+-----+-----+-----+----------------+
   |     |     |                 |     |                            |
   |     |     +--------+--------+     +--------+----------- ... ---+
   |     |              |                       |
   |     |              |                       +--> MAC Data
   |     |              |         
   |     |              +--> Size = 14
   |     |
   |     +--> Type ID = 0
   |
   +--> Param ID = 0
Bytes Field Datatype Description
0 Param ID uint8 Reserved Parameter ID for MAC. This is always zero (0).
1 Type ID uint8 Reserved Type ID for MAC. This is always zero (0).
2 - 5 Size uint32 Size of MAC buffer. This must be 14 (semi-arbitrary)
6 - 20 MAC HMAC-SHA1 Message Authentication Code. 

To authenticate we will use the lower 14 bytes of an HMAC as defined in [RFC 2104] with the SHA-1 cryptographic hash function described in [SHA]

4 - Security

Goto : [top]
This section discusses the various parts of the protocol and formats that are security related

Sequence Numbers

Goto : [top] [security]
As command packets are sent between the communicating parties, the protocol implementation will maintain a counter. Each packet will be stamped with the numeric value of the counter. This serves to order the packets which will allow the implementation to prevent (or at least detect) replay attacks.

Time Stamps

Goto : [top] [security]
Each command packet will be stamped with the time at which it was put on the wire. This serves to order the packets which will allow the implementation to prevent (or at least detect) replay attacks.

Message Authentication Code (MAC)

Goto : [top] [security]
The protocol uses Message Authentication Codes (MACs) to validate the integrity and authenticity of the information being transmitted. This serves to make packet alteration difficult. The MAC is computed over the everything in the packet except the MAC data itself. This includes: The description of the particular MAC scheme can be found in [RFC2104].

Confidentiality

The protocol does not make any promises regarding the confidentiality of the data flowing through it. If confidentiality is required, one could layer the protocol over an encrypted link (over SSL for instance) or one could use encrypted values.

Access Control Lists

While not directly related to the protocol, there will likely be need for users of the protocol to ensure that servers only accept connections from a select set of clients. To do so, the server could maintain an access control list (ACL) of the IP addresses of the clients with which it is allowed to communicate. This functionality is independent of this protocol, it is not discussed further within this document.

Key Exchange

The scheme used to authenticate each command packet (i.e., the MAC) assumes that the communicating parties share knowledge of a secret key. Ideally, the servers and clients would use Diffie-Helman to exchange keys for the MACs.

5 - Examples

Goto : [top]
Coming soon.

6 - References

Goto : [top]
[RFC2104] HMAC: Keyed-Hashihg for Message Authentication
H. Krawczyk, M. Bellare, and R. Canetti
February 1997
[SHA] NIST, FIPS PUB 180-1: Secure Hash Standard, April 1995.

Copyright © 2000 Zero-Knowledge Systems Inc.
All rights reserved.