Publication: FSP-1040 draft 3 Revision: 1 Title: Packet Type 2 Compatible Formats Author: Stephen Hurd 1:103/1 Date: 2016-02-11 ----------------------------------------------------------------------
Status of this document -----------------------
This document is a Fidonet Standard Proposal (FSP), issued by Stephen Hurd for the benefit of the Fidonet community.
This document specifies an optional Fidonet standard protocol for the Fidonet community, and requests discussion and suggestions for improvements.
This document is released to the public domain, and may be used, copied or modified for any purpose whatever.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in FTA-1006.
Contents -------- 1. Fidonet Packets 2. Original Type 2 Packet 3. Type 2+ Packet 4. Type 2.2 Packet 5. Packed Message 6. Comparison of Headers 7. Bibliography
In Fidonet terms, a "packet" is a file which contains zero or more separate messages to be transfered together to a system. The "original" Type 2 packet format only supported 3D node addressing (zone, net and node numbers) so different new types of packets were developed. None of them have previously been ratified as a standard despite being in common use on Fidonet.
These Type 2 "compatible" formats all use a similar fixed-length header and the same packed message format. Values in these headers are in "Little-endian" or "Intel" format with the "least-significant" or "low order" byte first followed by the next most significant up to the length of the field. All integer values SHOULD be treated as unsigned, though some notations MAY treat them as signed values (ie: Policy 4 mentions address "-1/-1") if a signed value is used, it MUST be in twos-compliment little-endian format.
After the last packed message, there are two NUL characters to indicate the end of the packet.
A Type 2 packet parser which ignores invalid values in some fields is able to process all three types (with some loss of information).
The Type 2+ packet supports 4D addressing, includes product version information, and supports a "capability word" method of advertising support for new packet types. It is highly compatible with Type 2 packets (any Type 2 processor should work with a Type 2+ packet).
The Type 2.2 packet supports 5D addressing, but is not as compatible with Type 2 format as it redefines some rarely-used fields, (specifically, date/time and baud) and does not protect the origin address when the originating system is a point.
It is therefore RECOMMENDED that without prior arrangement between the systems on both sides of the link, that Type 2+ packets be used rather than 2.2 packets for Fidonet.
1.1 Field types used in this document -------------------------------------
Each field in this document has an associated type which defines the format of the field contents. Type values that are used are:
Int8, Int16, Int32: As described above, these are integer values expressed with the number of bits following the "Int" part of the type name. These SHOULD be unsigned integers, but MAY be twos-compliment signed values.
pStr: NUL-padded, fixed length string. Always defined with a count of bytes. NULs are added at the end to fill the field. Since the maximum length of the string is the same as the count of bytes, this is not a NUL-terminated string as the last byte may be part of the string.
nStr: NUL-terminated string. A sequence of zero or more non-NUL characters followed by a single NUL character. If a length is specified, does NOT include the terminating NUL. If an nStr with a length of 19 is stored, it will take 20 bytes of storage because of the terminating NUL.
Undef: Undefined sequence of bytes. SHOULD be set to NULs.
2. Original Type 2 Packet -------------------------
Originally defined in FSC0001, supports 3D addressing only. This can cause problems when transferring them to/from points, and across domain gateways.
This header has eighteen fields specified below:
,------------------------------------------------------------------. | Name | Offset | Bytes | Type | Description | +----------+--------+-------+-------+------------------------------+ | origNode | 0 | 2 | Int16 | Node number packet is from | | destNode | 2 | 2 | Int16 | Node number packet is to | | year | 4 | 2 | Int16 | Year packet was created | | month | 6 | 2 | Int16 | Month " " " | | day | 8 | 2 | Int16 | Day " " " | | hour | 10 | 2 | Int16 | Hour " " " | | minute | 12 | 2 | Int16 | Minute " " " | | second | 14 | 2 | Int16 | Second " " " | | baud | 16 | 2 | Int16 | See Notes | | pktType | 18 | 2 | Int16 | MUST have a value of 2 | | origNet | 20 | 2 | Int16 | Network number packet is from| | destNet | 22 | 2 | Int16 | Network number packet is to | | prodCode | 24 | 1 | Int8 | Assigned by the FTSC | | serialNo | 25 | 1 | Int8 | See Notes | | password | 26 | 8 | pStr | Packet password, NUL padded | | origZone | 34 | 2 | Int16 | Zone number packet is from | | destZone | 36 | 2 | Int16 | Zone number packet is to | | fill | 38 | 20 | Undef | SHOULD be NULs | `----------+--------+-------+-------+------------------------------'
Notes: origZone/destZone Older software MAY not populate these fields. If origZone is specified and the packed messages do not have a zone specified in them, software MAY assume that origZone defines the "default zone" for packed messages.
origNet/origNode These define the origin of the packet, not the messages in the packet.
origNet/origNode These define the destination of the packet, not the messages in the packet.
year/month/day/hour/minute/second SHOULD reflect the UTC time when the packet is created. However, software MUST be able to handle this being in local time. Further, since some packet types (such as 2.2) redefine these bytes, programs SHOULD function normally if these are invalid or unexpected values.
baud Not widely used. SHOULD be set to zero unless the maximum common baud rate between the two systems is known at the time of packet creation. If this field is two, the packet is a Type 2.2 packet as specified in part 4.
prodCode As defined in the latest FTA-1005, the product code assigned by the FTSC to the software which creates the packet. A value of 254 indicates the software has not been assigned a product code. If this value is 255, indicates this is part of a two-byte product code (see note for serialNo).
serialNo The contents of this field are not well defined, and this field SHOULD NOT be used for anything exception informational purposes (such as logging). When the software generating the packet has been issued a two-byte product code, it MAY place the most-significant byte in this field.
password NUL-padded password up to eight characters long. Software SHOULD NOT allow NULs in passwords, and when reading this field, any bytes after the first NUL SHOULD be treated as though they are also NUL. Keep in mind that an eight character password will not have a NUL in this field at all, so this is not a NUL terminated string.
fill This SHOULD be filled with NUL characters when written and ignored when read.
3. Type 2+ Packet -----------------
Originally specified in FSC-0039, then updated by FSC-0048, this introduced a mechanism to detect packet type support which, due to multiple incompatible "Type 3" packet formats, never really caught on. This "Capability Word" feature is not specified in this document.
The Type 2+ packet added point information and zone information before FTS-0001 was updated to include zones. As a result, the zone numbers are in different places in the Type 2 and Type 2+ packet definitions. Type 2+ was extended to include zone information in the same location, so the Type 2+ packet has the zone information twice. Software creating or modifying packets MUST set these two sets of zone fields to the same values.
In the following table, fields on lines beginning with an "H" reflect changes from the Type 2 packet above.
,------------------------------------------------------------------. | Name | Offset | Bytes | Type | Description | +----------+--------+-------+-------+------------------------------+ | origNode | 0 | 2 | Int16 | Node number packet is from | | destNode | 2 | 2 | Int16 | Node number packet is to | | year | 4 | 2 | Int16 | Year packet was created | | month | 6 | 2 | Int16 | Month " " " | | day | 8 | 2 | Int16 | Day " " " | | hour | 10 | 2 | Int16 | Hour " " " | | minute | 12 | 2 | Int16 | Minute " " " | | second | 14 | 2 | Int16 | Second " " " | | baud | 16 | 2 | Int16 | See Notes | | pktType | 18 | 2 | Int16 | MUST have a value of 2 | | origNet | 20 | 2 | Int16 | Network number packet is from| | destNet | 22 | 2 | Int16 | Network number packet is to | | prodCode | 24 | 1 | Int8 | Assigned by the FTSC | | | | | | (Low byte only) | H prodVerM | 25 | 1 | Int8 | Major Version Number | | password | 26 | 8 | pStr | Packet password, NUL padded | | origZone | 34 | 2 | Int16 | Zone number packet is from | | destZone | 36 | 2 | Int16 | Zone number packet is to | H auxNet | 38 | 2 | Int16 | origNet when orig is a point | H capValid | 40 | 2 | Int16 | See Notes | H prodCodH | 42 | 1 | Int8 | Assigned by the FTSC | H | | | | (High byte only) | H prodVerN | 43 | 1 | Int8 | Minor Version Number | H capWord | 44 | 2 | Int16 | See Notes | H origZ+ | 46 | 2 | Int16 | See Notes | H destZ+ | 48 | 2 | Int16 | See Notes | H origPnt | 50 | 2 | Int16 | Point number packet is from | H destPnt | 52 | 2 | Int16 | Point number packet is to | H prodData | 54 | 4 | Int32 | Product-specific data | `----------+--------+-------+-------+------------------------------'
Notes: auxNet If origNet is 65535 (0xffff), indicates that the originator is a point, and the originating network can be found in this field. Some old software may not follow this convention, so the network number may be found in either of the two fields. When parsing a Type 2+ packet, if origNet is 65535, the software MUST use the value from the auxNet field. When creating a packet, if the originating system is a point, it SHOULD set origNet to 65535 and put the net number in this field. In the case where the originating net is 65535 (As recommended by Policy 4), it SHOULD be placed in both origNet and auxNet.
capValid Byte-swapped copy of the least-significant 15 bits of capWord. That is to say that the most significant bit of capWord is masked off, and the resulting two bytes are swapped. In C: capValid = ((capWord & 0x7f00) >> 8) | ((capWord & 0xff) << 8));
If the capValid and capWord fields do not match, the packet SHOULD NOT be processed as a Type 2+ packet.
prodVerM Major version number of product generating the packet. This replaces the serialNo field of packet Type 2.
prodCodH High (most-significant) byte of FTSC-assigned product code.
prodVerN Minor version number of product generating the packet.
capWord Capability Word. Not specified in this document, SHOULD have a value of 1. MUST at least have the least significant bit set (ie: be an odd number) or the packet is not a valid Type 2+ packet.
origZ+ A copy of origZone. If origZone and origZ+ are different, the non-zero one SHOULD be used. If neither is zero, origZ+ SHOULD be used. A compliant program MUST set these two fields to the same value.
destZ+ A copy of destZone. As with origZ+, this is the "preferred" copy for software to use.
origPnt Point number of the originating system.
destPnt Point number of the destination system.
prodData Value defined by the holder of the FTSC product code specified.
4. Type 2.2 Packet ------------------
Originally specified in FSC-0045, this packet format supports full 5D addressing.
The Type 2.2 packet format adds both point and domain information, but replaces some rarely used fields, so is not as compatible with Type 2 as Type 2+ is.
In the following table, fields on lines beginning with an "H" reflect changes from the Type 2 packet in section 2.
,------------------------------------------------------------------. | Name | Offset | Bytes | Type | Description | +----------+--------+-------+-------+------------------------------+ | origNode | 0 | 2 | Int16 | Node number packet is from | | destNode | 2 | 2 | Int16 | Node number packet is to | H origPnt | 4 | 2 | Int16 | Point number packet is from | H destPnt | 6 | 2 | Int16 | Point number packet is to | H fill | 8 | 8 | Undef | MUST be NULs | H subType | 16 | 2 | Int16 | MUST have a value of 2 | | pktType | 18 | 2 | Int16 | MUST have a value of 2 | | origNet | 20 | 2 | Int16 | Network number packet is from| | destNet | 22 | 2 | Int16 | Network number packet is to | | prodCode | 24 | 1 | Int8 | Assigned by the FTSC | H prodRev | 25 | 1 | Int8 | See Notes | | password | 26 | 8 | pStr | Packet password, NUL padded | | origZone | 34 | 2 | Int16 | Zone number packet is from | | destZone | 36 | 2 | Int16 | Zone number packet is to | H origDom | 38 | 8 | pStr | Domain packet is from, | H | | | | NUL padded | H destDom | 46 | 8 | pStr | Domain packet is to, | H | | | | NUL padded | H prodData | 54 | 4 | Int32 | Product-specific data | `----------+--------+-------+-------+------------------------------'
origPnt Point number of the originating system. Replaces the year in Type 2 packets.
destPnt Point number of the destination system. Replaces the month in Type 2 packets.
subType Always set to 2. Replaces the baud from Type 2 packets, indicates this is a Type 2.2 packet.
prodRev "Product revision level" software assigned a 2-byte FTSC product code SHOULD put the most significant byte in this field, but some software MAY put a product version number or other data in this field.
origDom NUL padded domain this packet is from.
destDom NUL padded domain this packet is to.
5. Packed Message -----------------
All Type 2 compatible formats share the same packed message format. It consists of a fixed-length header followed by variable-length header followed by the message text.
The fixed-length header is as follows:
,------------------------------------------------------------------. | Name | Offset | Bytes | Type | Description | +-----------+--------+-------+-------+-----------------------------+ | msgType | 0 | 2 | Int16 | MUST have a value of 2 | | origNode | 2 | 2 | Int16 | Node number packet is from | | destNode | 4 | 2 | Int16 | Node number packet is to | | origNet | 6 | 2 | Int16 | Network numb. packet is from| | destNet | 8 | 2 | Int16 | Network number packet is to | | attribute | 10 | 2 | Int16 | See Notes | | cost | 12 | 2 | Int16 | See Notes | `-----------+--------+-------+-------+-----------------------------'
Notes:
origNode/origNet Net and node the message originated from (not the node the packet was created on).
destNode/destNet Net and node the message is directed to (not the node the packet is directed to).
attribute The attribute word of the message. The following bits are defined, any undefined bits MUST be zeroed before the message is packed. When processing these packets, undefined attributes MUST be ignored.
Bit 10 SHOULD be retained unchanged when packing messages despite it being unused. All other bits SHOULD be cleared when packing. The attributes can be ANDed with 29715 (0x7413) to clear the appropriate bits.
cost Expressed in the lowest unit of originators currency. Usually set to zero.
After the fixed-length portion is a variable-length series of NUL terminated strings.
The variable-length header is as follows:
,-------------------------------------------------------------. | Name | Type | Length | Description | +--------------+------+------------+--------------------------+ | dateTime | nStr | Exactly 19 | Date and time of message | | toUserName | nStr | 0-36 | User the message is to | | fromUserName | nStr | 0-36 | User the message is from | | subject | nStr | 0-36 | Message subject | | text | nStr | 0-Infinity | Message body | `--------------+------+------------+--------------------------'
The lengths above do NOT include the NUL terminator.
dateTime MUST occupy twenty bytes including the NUL terminator. The following is the ABNF notation of the format that messages SHOULD use:
dateTime = dayOfMonth " " month " " year " " hour ":" minute ":" second %x00
January 1st, 2016 at 11:15:55pm would therefore be "01 Jan 16 23:15:55" with a NUL at the end. Notice the two spaces between the year and the hour.
This format ensures the broadest compatibility however, other formats are known to be in use. SEAdog has been known to use the format "Mon 1 Jan 86 02:34" with a single NUL terminator. The day of month is right-justified with spaces. ie: "Mon 15 Jan 86 02:34".
After the message text is either the next message or the two-NUL packet terminator.
Note that some old systems MAY terminate the message text with an EOF (0x1A) or the literal end of the file. Some even older systems MAY terminate the message text with an empty line (0x0D 0x0A 0x0D 0x0A). To detect this, software MAY use the NUL in the second byte of the Type field to attempt to resynchronize. It is up to the developer if this needs to be supported.
Since the packed message header only contains 2D addresses, the text SHOULD have addressing control paragraphs as specified in FTS-4001 added when messages are packed.
6. Comparison of Headers ------------------------
The following chart compares the different header fields between the three packet header types. A '*' before the field name indicates it is may be incompatible with the Type 2 column value.
