The SNBS Protocol

This document describes the SNBS protocol.

Overview

The protocol described here is a client-server protocol. The protocol is initiated by the backup server, which establishes a TCP connection to the backup source.

The protocol is designed to transport backup streams from the backup source to the backup server. The backup server queries the backup source for a list of all available backup streams, and selects some of them for transmission. Incremental and differential backups are supported.

The protocol is unaware of the format actually used for the backup streams, but it is expected that this data is encrypted in integrity-protected.

Message Types

The first byte of each message describes the message type. By convention, messages containing data about the actual backup uses type codes which are lower-case ASCII letters. Other messages use upper-case letters.

A message with a Pascal string has the folllowing structure:

A message with a wide Pascal string has the folllowing structure:

Times are stored in unsigned 32-bit integers, transmitted in network byte order. The integer counts the number of seconds since Januar 1, 1970, 00:00:00 UTC.

Type Code "b"

"b" messages are 4097 bytes long. After the type code, 4096 bytes of backup data follow.

Type Code "C"

"C" messages are 17 bytes long. After the type code, a 16 byte challenge follows.

Type Code "D"

"D" messages are messages with a Pascal string.

Type Code "e"

"e" messages are between 3 and 4098 bytes long. They are messages with a wide Pascal string. The length of the payload is between 0 and 4095 bytes (inclusive).

Type Code "E"

"E" messages are between 4 and 1027 bytes long. They are messages with a wide Pascal string. The payload shall contain a human-readable error message.

Type Code "l"

"l" messages are messages with a Pascal string.

Type Code "L"

"L" messages are one byte long. They do not have any payload.

Type Code "m"

"m" messages are 17 bytes long. A 16-byte MD5 hash of backup data follows the type code.

Type Code "Q"

"Q" messages are one byte long. They do not have any payload.

Type Code "R"

"m" messages are 17 bytes long. A 16-byte MD5 hash follows the type code.

Type Code "S"

"S" messages are 12 bytes long. After the type code "S", the three ASCII characters "NBS" follow, followed by 8 bytes of version identification. The version identification contains of two parts, 4 bytes protocol version and 4 bytes client version. The version identification consists of printable ASCII characters. Its current value is "00010001".

Type Code "T"

"T" messages are 5 bytes long. A four byte time value follows the type code.

The Protocol

The protocol consists of the exchange of the messages described in the previous section.

Backup server and source share a common secret which is used during the challenge-response authentication. The main purpose of this cryptographic handshake is to prevent denial-of-service attacks by starting bogus backups, and to prevent accidental backup of a client by the wrong server. It is expected that the backups itself are encrypted.

At each point during the protocol, a party may send an "E" message with an error message, and close the connection.

Phase 1: Handshake

  1. The backup server establishes a TCP connection to the backup source, on port 17685.

  2. The backup source responds with an "S" message, followed by a "C" message with an embedded challenge.

  3. The backup server uses the version identification in the "S" message to detect the capabilities of the client. It extracts the challenge from the "C" message. To the challenge, it appends the shared secret and the six byte string "SNBS 0" (the four bytes "SNBS", followed by an ASCII space character, followed by the ASCII decimal digit zero). The entire string is hashed using MD5. The backup server sends back an "R" message containing the MD5 digest.

  4. The backup source verifies the "R" response received.

Phase 2: Listing backup streams

  1. The server sends an "L" message.

  2. For each available backup stream, the backup source responds with an "l" message, containing the name of the backup stream. The list ist terminated with an "l" message with an empty payload.

  3. The server receives the "l" messages and stores them for later reference.

Phase 3: Transfer of backup streams

The following steps are executed for each backup stream the backup server wishes to receive from the backup source.

  1. The backup server sends a "D" message to the backup source, containing the name of a backup stream and a time. The time indicates that the source may skip data which has been changed before the specified time.

  2. The backup source responds with a "T" message. The time states that when the backup terminates successfully (that is, the "m" message is received as below), the backup stream includes all changes between the time specified by the server and the time in the "T" message.

  3. After that, the backup source sends zero or more "b" messages, containing the backup stream. This sequence is terminated by a single "e" message. The final "e" message can have empty payload.

    The backup server stores the payload of the "b" and "e" messages (without the type codes and the length header).

  4. The backup source sends a "m" message with the MD5 sum over the shared secret, followed by the six byte string "SNBS 1", followed by the backup stream (without the type codes and the length header).

  5. The server verifies that the MD5 sum is correct (preferably by re-reading the backup stream from stable storage).

Phase 4: Termination

  1. The backup server sends a "Q" message to the backup source and closes the connection.

  2. The backup source closes the connection.

Revisions


Florian Weimer
Home Blog (DE) Blog (EN) Impressum RSS Feeds