Netstrings<br>D. J. Bernstein, djb@pobox.com<br>19970201

1. Introduction

A netstring is a self-delimiting encoding of a string. Netstrings are<br>very easy to generate and to parse. Any string may be encoded as a<br>netstring; there are no restrictions on length or on allowed bytes.<br>Another virtue of a netstring is that it declares the string size up<br>front. Thus an application can check in advance whether it has enough<br>space to store the entire string.

Netstrings may be used as a basic building block for reliable network<br>protocols. Most high-level protocols, in effect, transmit a sequence<br>of strings; those strings may be encoded as netstrings and then<br>concatenated into a sequence of characters, which in turn may be<br>transmitted over a reliable stream protocol such as TCP.

Note that netstrings can be used recursively. The result of encoding<br>a sequence of strings is a single string. A series of those encoded<br>strings may in turn be encoded into a single string. And so on.

In this document, a string of 8-bit bytes may be written in two<br>different forms: as a series of hexadecimal numbers between angle<br>brackets, or as a sequence of ASCII characters between double quotes.<br>For example, is a string of<br>length 12; it is the same as the string "hello world!".

Although this document restricts attention to strings of 8-bit bytes,<br>netstrings could be used with any 6-bit-or-larger character set.

2. Definition

Any string of 8-bit bytes may be encoded as [len]":"[string]",".<br>Here [string] is the string and [len] is a nonempty sequence of ASCII<br>digits giving the length of [string] in decimal. The ASCII digits are<br>for 0, for 1, and so on up through for 9. Extra zeros<br>at the front of [len] are prohibited: [len] begins with exactly<br>when [string] is empty.

For example, the string "hello world!" is encoded as , i.e., "12:hello world!,". The<br>empty string is encoded as "0:,".

[len]":"[string]"," is called a netstring. [string] is called the<br>interpretation of the netstring.

3. Sample code

The following C code starts with a buffer buf of length len and<br>prints it as a netstring.

if (printf("%lu:",len) 999999999 bytes is bad */<br>if (getchar() != ':') barf();<br>buf = malloc(len + 1); /* malloc(0) is not portable */<br>if (!buf) barf();<br>if (fread(buf,1,len,stdin) < len) barf();<br>if (getchar() != ',') barf();

Both of these code fragments assume that the local character set is<br>ASCII, and that the relevant stdio streams are in binary mode.

4. Security considerations

The famous Finger security hole may be blamed on Finger's use of the<br>CRLF encoding. In that encoding, each string is simply terminated by<br>CRLF. This encoding has several problems. Most importantly, it does<br>not declare the string size in advance. This means that a correct<br>CRLF parser must be prepared to ask for more and more memory as it is<br>reading the string. In the case of Finger, a lazy implementor found<br>this to be too much trouble; instead he simply declared a fixed-size<br>buffer and used C's gets() function. The rest is history.

In contrast, as the above sample code shows, it is very easy to<br>handle netstrings without risking buffer overflow. Thus widespread<br>use of netstrings may improve network security.