Kermit file-transfer packet reference

Frank da Cruz
The Kermit Project, Bronx NY.
7 September 2022
Last update: Mon Jan 29 12:35:41 2024

This is a supplement to the information found in the Kermit Protocol Manual (1986) and the book Kermit, a File Transfer Protocol (1987). Both of those documents were written in the pre-WWW days in a markup language called Scribe that no longer exists and therefore those sources can't be easily updated. This page does not explain the Kermit protocol, only what is in the packets.

Fundamental rules Block checks Negotiations Capabilities mask S-Packet examples Empty directories Transfer encodings References

Over the decades many backwards-compatible improvements have been made to the Kermit file transfer protocol, and these resulted in a variety of new packet formats, types, and contents. Until now this information was never collected into a single reference.

Kermit file transfers occur when two Kermit programs — the file sender and the file receiver — exchange a well-defined sequence of packets. The file sender initiates the transfer by sending a packet to the file receiver. The receiver sends a short acknowledgement packet back (or in case the packet was damaged in transit, a negative acknowledgement). The process repeats until the the task is done. There can also be a client/server relationship, in which the client sends not only files to the server, but also commands (for example, to "get" a file or other information from the server or perform file-management tasks in the server side.

Fundamental rules

The use of longer packets, sliding windows (right), streaming, compression, transmission of bare control or 8-bit characters, and all the other performance improvements made since the original protocol — which was designed to interoperate among IBM mainframes, the DECSYSTEM-20 mainframe, and 8-bit CP/M microcomputers — can be used only if both Kermit programs implement them and agree to use them in the feature-negotiation phase at the beginning of the file transfer.

tochar(x)

Converts an integer x (0-94) to a printable ASCII character (space through tilde) by adding 32, so 0 (zero) becomes space, 1 (one) becomes exclamation mark, (etc...), and 95 becomes circumflex/caret (^).

unchar(x)

Converts a tochar()-encoded integer x back to its numeric value.

ctl(x)

Converts a C1 (7-bit) control character x (ASCII 0-31) to a printable character or vice-versa by toggling its bit number six (i.e. 7th bit from the "right").

All numbers used in this document are decimal (base 10). All characters used in Kermit packets to implement the protocol are 7-bit ASCII printable characters (strictly speaking, the Mark and End control characters are outside the packet). Of course any kind of data — binary, 8-bit, text in any language (e.g. Japanese) — can be included in the packet Data field but it is almost always encoded to some degree for transparency and/or efficiency using methods described in this document such as single and locking shifts.

Kermit packet types

Here's an example:

🇦+!Ftest.txtC🇲

• Len (the length) is '+' (plus sign, ASCII 43 - 32 = 11);
• Seq (the sequence number) is '!' (exclamation mark, ASCII 33 - 32 = 1, i.e. the second packet);
• Type (the packet type) is 'F', meaning File header;
• the Data field contains 'test.txt', the name of the file being sent;
• Check (the block-check field) is 'C'

The maximum length for a basic Kermit packet (not counting Mark and End, which are outside the packet) is 96, so the maximum length of the Data field is 92 to 94, depending on the type of block check. This is the basic and required packet format for all implementations of the Kermit protocol. In the Data field, "sensitive" items such control characters are encoded printably, for example #M#J is Control-M followed by Control-J, i.e. carriage return and linefeed.

For increased efficiency and reliability an optional format allows packets up to about 9K long. A long packet has a blank Len field (blank = space = ASCII 32 - 32 = 0). This tells the receiver to take the length from the two bytes after the Type field.

Like the basic packet format except Len is blank (Space, ASCII character 32), an impossible value for a basic-format packet, which denotes this as a "long packet" with its length appearing after the Type and before Data field:

References

• MaxLx1 = tochar(length / 95)
• MaxLx2 = tochar(length MOD 95)
• Hcheck = tochar(header checksum)

Block checks

For all packets, the Packet checksum is based on the sum, s, of the ASCII numeric code values of all the bytes in the packet starting with the Len field up to the last byte of the Data field. The Header checksum (used only in long packets) is based on the arithmetic sum, s, of the code values of Len, Seq, Type, MaxLx1, and MaxLx2. In both cases the single-byte 6-bit block check is calculated by this formula:

checksum = tochar((s + ((s & 192)/64)) & 63;

The 2-byte block check is the low-order 12 bits of the sum of all the characters divided into two bytes, each made printable by tochar(). It is 64 times stronger than type 1.

The two-byte "blank-free" 12-bit block check, for use on communication paths (such as IBM 370 protocol converters) that discard trailing blanks, is the same, but if a result byte is blank (ASCII 32), it is converted to '!' (ASCII 33).

The 3-byte block check is the international standard CRC-16-CCITT cyclic redundancy check (as used in X.25) encoded as three printable characters. It detects all single- and double-bit errors, all messages with an odd number of bits in error, all error bursts shorter than 16 bits, and over 99.99% of longer error bursts.

The original protocol had only one kind of block check so its location and length were always known. When higher-order block checks were introduced some years later a minor weakness was that you could no longer tell by looking at a packet where the block check started or how long it was. Kermit programs that support the newer block checks have to rely on the state established by the negotiations at the beginning of the transfer: the length of the Data field is indicated in the packet, so the block check is the final 1, 2, or 3 characters depending on the block-check type previously negotiated. If the block check were clearly marked in the packet itself, then every packet would be "self-parsing" and could have any kind of block check. In 40 years of practice, however, no ill effects have been noted with over 300 different versions of Kermit created in nearly 40 different programming languages (see list).

Reference: Kermit, A File Transfer Protocol: Block check options.

Feature negotiation

The parameters are encoded in various ways, some of which are not comprehensible by the human reader. In retrospect, a better design might have conveyed parameters in tag=value format but in the early 1980s bandwidth was extremely limited (imagine transferring even a modest-size a file over a noisy 300 bit-per-second dialup modem connection, which was the norm 1n 1981, the year Kermit was born).

The Data field of the S-packet, I-packet, and their ACKs can contain the following fields (where "I" am the file sender and "you" are the receiver):

Clearly, the initialization string must be at least 12 characters long in order for long packets to be used; long packets are documented in the Kermit Protocol Manual and in Chapter 12 of the Kermit book. SYSIDs are listed starting on page 275 (scroll down to "(ASCII 46)"), reproduced in part here with slightly updated terminology:

The SYSID can be used by the file sender to choose a transfer character-set for text files that is appropriate for the file receiver. Conceivably a SYSID could be longer than 2 characters, but the great proliferation of computer system types in the 1980s has dwindled down to just Windows, macOS, Unix, and (Open)VMS in the 21st Century.

The capabilities mask

    bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0
   +----+----+----+----+----+----+----+----+
   |  X |  X |  1 |  2 |  3 |  4 |  5 |  Z |
   +----+----+----+----+----+----+----+----+

   X   = Must always be 0
   1-5 = Bits indicating specific capabilities
   Z = Capability Mask Extension Bit (1 = end; 0 = more to follow)

    lpcapb = 2,                         /* Long Packet capability */
    swcapb = 4,                         /* Sliding Window capability */
    atcapb = 8,                         /* Attribute-packet capability */
    rscapb = 16,                        /* RESEND capability */
    lscapb = 32,                        /* Locking Shift capability */

S-Packet examples

🇦9 S~/ @-#Y3~^>J)0___J"U1@C🇲

🇦9 S~/ @-#Y3~^>J)0___J"U1@C🇲
     1234567890123456789012

Here's an ACK to C-Kermit's S-packet from a bare-bones Kermit implementation:

🇦^A, Y~* @-#N1~]🇲

Since fields 10-21 are not present, the capabilities and features they represent are not used. This allows the newest and most advanced Kermit implementation to interoperate with oldest and least capable one, provided it follows the rules.

File header packet

There is no provision for very long or non-ASCII filenames. In retrospect, it would have been better to allow multiple F packets for a file whose name is longer than the negotiated maximum length; these would work just like Data packets, but there would also need to be some kind of "end of filename" signal.

Another issue with F-packets is that the receiver has no way of knowing the filename's character-set because A packets come after the F packet. For example, the filename might be German "Grüße" in UTF-8 or ISO-8859-1, or even some proprietary character set the receiver never heard of. Until such time (if ever) as the protocol is improved to handle these issues, the best policy is to keep filenames shorter than about 80 characters, spell them with ASCII letters and digits and a few other characters like "-" (hyphen), "_" (underscore), and of course "." (period); almost anything else can cause confusion or conflict. And avoid including spaces in filenames even if it's legal on your computer, because it isn't on others. And for that matter don't assume that capital and small letters are equivalent in filenames; they are in most operating systems but not others.

Attribute packets

Each attribute consists of a 1-byte length field, which is a small integer (up to 95) encoded by encoded by tochar(). Then the attribute code as a 7-bit ASCII character, then the value of the attribute. Here is a typical A packet:

🇦U"A."UN"#AMJ*'CI6/100#120181209 09:44:49!!31$2763@ '.]🇲
  000000000011111111112222222222333333333344444444445555
  123456789012345678901234567890123456789012345678901234

U (at position 06) is the packet length (85 - 32 = 53), " is the packet sequence number (2), and A is the packet type (Attribute). The attributes start at 04. The first attribute is . (period), meaning system ID; it is " (doublequote) bytes long (meaning 2), and the ID is UN. The next attribute starts at 08, type " = File type, Length # = 3, value AMJ meaning text with CRLF line terminator. Next comes attribute * at 13, the transfer encoding, length 7, value I6/100, which denotes ISO 8859-1 Latin Alphabet 1. Next at 22: Creation date, length 1 = 49 - 32 = 17, "20181209 09:44:49". Next, !!3 says the file is about 3k bytes long. Finally, 2763 says the exact file length is 2763 bytes in the sender's file system. The @-sign at 40 means "end of attributes", i.e, no more attribute packets follow this one and the next packet will be file data. The A-packet ends with a 3-byte block check.

Here's the same packet with each field separated by spaces for easier reading:

🇦U"A ."UN "#AMJ *'CI6/100 #120181209 09:44:49 !!3 1$2763 @ '.]🇲
  000 0000 00011 111111112 2222222223333333333 444 444444 4 555
  123 4567 89012 345678901 2345678901234567890 123 456789 0 123
  hdr sid  ftype charset   creation date-time  kb  bytes  @ chk

Empty directories

Generic server commands

Transfer encodings

(~/) C-Kermit>set file character-set ? One of the following:
 ascii               cp866-cyrillic      german              latin9-iso
 british             cp869-greek         greek-iso           macintosh-latin
 bulgaria-pc         cyrillic-iso        hebrew-7            mazovia-pc
 canadian-french     danish              hebrew-iso          next-multinational
 cp1250              dec-kanji           hp-roman8           norwegian
 cp1251-cyrillic     dec-multinational   hungarian           portuguese
 cp1252              dg-international    jis7-kanji          shift-jis-kanji
 cp437               dutch               koi7                short-koi
 cp850               elot927-greek       koi8                spanish
 cp852               elot928-greek       koi8r               swedish
 cp855-cyrillic      euc-jp              koi8u               swiss
 cp858               finnish             latin1-iso          ucs2
 cp862-hebrew        french              latin2-iso          utf8
(~/) C-Kermit>

(~/) C-Kermit>set transfer character-set ? One of the following:
 ascii         greek-iso     latin2-iso    ucs2
 cyrillic-iso  hebrew-iso    latin9-iso    utf8
 euc-jp        latin1-iso    transparent
(~/) C-Kermit>