TITLE: Binkp Command Examples DESCRIPTION: Illustrates the frame structure for specific Binkp commands, M_OK and M_NUL, showing the placement of the command ID, data length (SIZE), and command arguments within the frame. LANGUAGE: APIDOC CODE: ``` Example: M_OK "" Frame Structure: +-+-------+--------+--------+ |1| 0 1| 4| +-+-------+--------+--------+ | | +----- command ID (M_OK) | +-------- frame length (SIZE=1 for command ID) +- command frame flag (T bit = 1) Example: M_NUL "TEST" Frame Structure: +-+-------+--------+--------+-------+--------+--------+--------+ |1| 0 5| 0| T E S T | +-+-------+--------+--------+-------+--------+--------+--------+ | | +----- command ID (M_NUL) | +-------- frame length (SIZE=5 for "TEST" + command ID) +- command frame flag (T bit = 1) +-------------------------+----- "Data string" (TEST) ``` ---------------------------------------- TITLE: Binkp Session Frame Exchange Example DESCRIPTION: Illustrates a typical frame exchange during a simple Binkp session setup between two nodes, showing the sequence of commands like M_NUL, M_ADR, M_PWD, and M_OK. LANGUAGE: APIDOC CODE: ``` +----------------------------------------------------------------+ | Originating side | Answering side | |--------------------------------+-------------------------------| | M_NUL "SYS ..." | M_NUL "SYS ..." | | M_NUL "ZYZ ..." | M_NUL "ZYZ ..." | | M_NUL "LOC ..." | M_NUL "LOC ..." | | M_NUL "VER ..." | M_NUL "VER ..." | | M_NUL "OPT ..." | M_NUL "OPT ..." | | M_ADR "1:1/1.1@fidonet" | M_ADR "2:2/2.2@fidonet" | | M_PWD "password" | (waiting for a password from | | | remote) | |--------------------------------+-------------------------------| | (waiting for password | M_OK "secure" | | acknowledgement) | | |--------------------------------+-------------------------------| ``` ---------------------------------------- TITLE: File Transfer Protocol Commands DESCRIPTION: This section details the commands used in a file transfer protocol, covering file metadata, acknowledgments, error reporting, and session management. It includes syntax, parameter descriptions, and usage examples for each command. LANGUAGE: APIDOC CODE: ``` M_OK 1 Description: Reports to the remote about the session status (secure or non-secure). Arguments: - "non-secure": Report normal password unprotected session (e.g., empty password). - "secure": Report normal password protected session. Example: M_OK "secure" M_FILE 3 Description: Specifies parameters for the next file to be transmitted. Synopsis: M_FILE " " Parameters: - filename: The name of the file. - file_size: Size of the file in bytes (decimal integer). - unixtime: Unix timestamp of the file (decimal integer). - file_offset: Transmission offset for the file (decimal integer). Implementation Notes: - Size, unixtime, and offset must be positive numbers or zero. - Mailer MUST check received string to prevent number overflow and skip file if overflow. - Data frames must carry data from this file consecutively until the next M_FILE command. - Transmission typically starts from offset 0, but M_GET command from remote forces transmission from a specified offset. Example: M_FILE "config.sys 125 2476327846 0" M_FILE "config.sys 125 2476327846 100" (answering to M_GET with offset 100) M_EOB 5 Description: End-of-Batch command, transmitted after all files have been sent. Arguments: Arguments MUST be ignored in the basic implementation. Example: M_EOB "" M_GOT 6 Description: File acknowledgment transmitted upon receiving the last data frame for a file. Synopsis: M_GOT " " Parameters: - filename: The name of the successfully received file. - size: Size of the file in bytes (decimal integer). - unixtime: Unix timestamp of the file (decimal integer). Usage: - Argument values must match those sent in the corresponding M_FILE command. - Can be transmitted while receiving a file, potentially interpreted as a destructive file skip. Example: M_GOT "config.sys 125 2476327846" M_ERR 7 Description: Indicates a fatal error; the sending party SHOULD abort the session. Arguments: SHOULD contain an error explanation and may be logged by the remote. Common Errors: - "Bad address": Remote mailer passed a bad (restricted) address. - "Incorrect password": Remote side sent an incorrect password. - ": cannot parse args": Illegal argument string for a command. Implementation Note: - Mailer MUST NOT abort a session without sending M_ERR or M_BSY. - After receiving M_ERR and session drop, mailer should wait before next poll to prevent continuous polling. Example: M_ERR "Incorrect password" M_BSY 8 Description: Transmitted when the system encounters a non-fatal error due to temporary lack of resources (e.g., incoming session limit exceeded). Arguments: SHOULD contain an explanation of the situation and may be logged by the remote. Usage: - Can be sent at any time during the session. - The side sending M_BSY is in a legal position to abort the session. - Mailer MUST be able to accept M_BSY at any time. Example: M_BSY "Incoming session limit exceeded" ``` ---------------------------------------- TITLE: Password Handling Protocol States DESCRIPTION: Defines the state transitions and actions for password authentication. It details how the system responds to different frames (M_PWD, M_ERR, M_NUL) and conditions like password matching or timer expirations, guiding the system through states R3, R4, and R5. LANGUAGE: APIDOC CODE: ``` State: R3 (WaitPwd) - On M_PWD frame received: - If password matches or no password required: Transition to R4. - If password does not match: Transition to exit (Report password error, Send M_ERR frame). - On M_ERR frame received: Transition to exit (Report error). - On M_NUL frame received: Ignore or parse, optionally log. Transition to R1. - On Other known frame received: Report unexpected frame; send M_ERR frame. Transition to exit. - On Unknown frame received: Ignore. Transition to R3. - On Nothing happens: Wait. Transition to R3. - On Timer Expired: Report timeout. Transition to exit. State: R4 (PwdAck) - On Yes, the password matches: - Send M_OK frame. - Report secure session. - Transition to R5. - On No password and got M_PWD "-" frame: - Send M_OK frame. - Report unsecure session. - Transition to R5. - On No, password does not match: - Report password error. - Send M_ERR. - Transition to exit. State: R5 (Opts) - On We have more protocol extensions: - Send frames to negotiate protocol extensions. - Transition to T0. ``` ---------------------------------------- TITLE: Binkp Protocol Extensions Indication DESCRIPTION: Describes how to indicate supported protocol extensions using M_NUL frames. It covers the format for listing extensions and the expected behavior when multiple extension frames are received, emphasizing backward compatibility. LANGUAGE: APIDOC CODE: ``` APIDOC: Protocol Extensions: Indication Method: Sides indicate supported protocol extensions by sending M_NUL frames. Format: M_NUL "OPT list_of_extensions" - list_of_extensions: A space-separated list of supported protocol extensions. Handling Multiple Frames: - Whenever multiple M_NUL "OPT ..." frames are received during the session, they SHOULD augment the current list of extensions rather than replace it, unless specifically stated otherwise for a particular option. Usage: - Mailer SHOULD NOT use any extension unless exactly sure that this extension is supported by the remote. - Mailer SHOULD use M_NUL "OPT ..." to indicate supported options. - Other methods for indicating supported extensions are allowed as long as they provide full backwards compatibility. Recommended Extensions (at time of writing): - None-reliable mode (NR). - Challenge-Response Authentication Mechanism (CRAM). ``` ---------------------------------------- TITLE: Binkp Transmit Routine State Machine DESCRIPTION: Defines the state transitions for the Binkp transmit routine. It details the states, predicates, conditions, actions, next states, and return values for managing file transmission, including opening files, sending data blocks, and handling end-of-batch conditions. LANGUAGE: APIDOC CODE: ``` Table 5: Transmit Routine +-----------------+-----------------+-----------------+-----------------+-------+--------+ | TxState | Predicate(s) | Condition(s) | Actions(s) | Next | Return | |-----------------+-----------------+-----------------+-----------------+-------+--------| | TxGNF | Open next file | File opened OK | Send M_FILE | TxTryR|continue| | | from outgoing | | Report | | | | | queue | | sending file | | | | | |-----------------+-----------------+-------+--------| | | | Failed to open | Report | TxDone|Failure | | | | file | failure | | | | | |-----------------+-----------------+-------+--------| | | | No more files | Send M_EOB | TxWLA |continue| | | | | Report end | | | | | | | of batch | | | |-----------------+-----------------+-----------------+-----------------+-------+--------| | TxTryR | Check TheQueue | TheQueue is | none | TxReadS|continue| | | | empty | | | | | | |-----------------+-----------------+-------+--------| | | | TheQueue is | call ProcessTheQueue|continue| | | | not empty | | | | |-----------------+-----------------+-----------------+-----------------+-------+--------| | TxReadS | Read data block | Read failed | Report Error | TxDone|Failure | | | from file |-----------------+-----------------+-------+--------| | | | Read OK, | Send data | TxGNF |OK | | | | Reached EOF | block frame | | | | | | | Close | | | | | | | current file | | | | | | | Add current | | | | | | | file to | | | | | | | PendingFiles | | | | | |-----------------+-----------------+-------+--------| | | | Read OK, not | Send data | TxTryR|OK | | | | reached EOF | block frame | | | |-----------------+-----------------+-----------------+-----------------+-------+--------| | TxWLA | Check TheQueue | TheQueue is | none | TxDone|OK | | | | empty and | | | | | | | RxState >= | | | | | | | RxEOB | | | | | | |-----------------+-----------------+-------+--------| | | | TheQueue is | none | TxWLA |OK | | | | not empty | | | | +-----------------+-----------------+-----------------+-----------------+-------+--------+ ``` ---------------------------------------- TITLE: FTSC Session Setup - Originating Side DESCRIPTION: Details the state transitions and actions for the originating side during the FTSC session setup phase. It covers connection initiation, authentication, and progression to the file transfer stage. LANGUAGE: APIDOC CODE: ``` FTSC Session Setup - Originating Side (Table 1): State S0 (ConnInit): Predicate(s): None Action(s): Attempt to establish connection. Next State: S1 State S1 (After ConnInit): Predicate(s): Connection established. Action(s): Send M_ADR frame, then send M_PWD frame. Next State: Awaiting Authentication Response State Awaiting Authentication Response: Predicate(s): Reception of M_OK (success) or M_ERR (failure). Action(s) on M_OK: Proceed to file transfer stage. Action(s) on M_ERR: Close connection. Next State: File Transfer Stage or Connection Closed ``` ---------------------------------------- TITLE: Binkp Commands Specification DESCRIPTION: Defines the format and arguments for various Binkp protocol commands, including M_NUL for information exchange, M_ADR for address lists, M_PWD for session passwords, and M_OK for acknowledgments. Covers recommended usage and extensions. LANGUAGE: APIDOC CODE: ``` Binkp Commands: Format: symbolic_command_name command_ID M_NUL 0 Purpose: Used for human-readable information, nodelist info, sysop name, and protocol extensions. Arguments: MAY contain human-readable information. Mailer MAY ignore/log arguments if options not supported. Recommended format for arguments: * M_NUL "OPT protocol options list" (space-separated list of supported options/extensions) * M_NUL "SYS system_name" * M_NUL "ZYZ sysop's_name" * M_NUL "LOC system_location" * M_NUL "NDL system_capabilities" * M_NUL "TIME date_time" (e.g., "Sun, 06 Nov 1994 08:49:37 GMT" [RFC822]) * M_NUL "VER mailer_version protocol_version" (e.g., "binkp/1.0") * M_NUL "TRF netmail_bytes arcmail_bytes" (traffic prognosis in bytes) Other arguments used by some mailers: * M_NUL "PHN string" (phone number, IP address) * M_NUL "OPM string" (message for system operator) * M_NUL "FREQ" (indicate file request) M_ADR 1 Purpose: Lists 5D FTN addresses. Arguments: Space-separated list of 5D FTN addresses (e.g., "2:5047/13.1@fidonet 2:5047/0@fidonet"). Address format: If point part is 0, ".0" may be omitted. Extension: Supports 4D, 3D, and 2D addresses. Mailers MAY append default domain/zone for compatibility. Recommendation: All implementations should send 5D addresses to avoid ambiguities. M_PWD 2 Purpose: Session password for authentication. Usage: Only Originating side MUST send this message. Answering side proceeds after successful authentication. Arguments: Case-sensitive password string (e.g., "pAsSwOrD"). No Password: If no password is available, send M_PWD "-". M_OK 4 Purpose: Acknowledgement for a correct password. ``` ---------------------------------------- TITLE: Binkp Protocol Identification DESCRIPTION: Defines the format for identifying the Binkp protocol version during session setup. It specifies the M_NUL frame content, including mailer identification and the protocol string, and outlines fallback behavior when identification strings are missing or incompatible. LANGUAGE: APIDOC CODE: ``` APIDOC: Protocol Identification String: In session setup stage, both sides send M_NUL frames. Format: M_NUL "VER mailer/version binkp/1.0" - mailer/version: Mailer identification string (free form, ASCII 32-126). - binkp/1.0: Protocol identification string (case-insensitive). Example: M_NUL "VER binkd/0.9.5a/FreeBSD binkp/1.0" Timing: Version identification frame SHOULD be sent and may be received before authentication ends. Fallback Rules: - If no protocol identification string is received, binkp/1.0 MUST be assumed. - Mailers with a protocol higher than binkp/1.0 MUST fallback to binkp/1.0 if they receive a binkp/1.0 version identification string or no identification string at all. ``` ---------------------------------------- TITLE: ftsc File Transfer Protocol Commands DESCRIPTION: Defines the core commands used in the ftsc file transfer protocol for managing file transfers, including requesting files, acknowledging receipt, and skipping files. These commands dictate the flow of data and state management between sender and receiver. LANGUAGE: APIDOC CODE: ``` M_GET command: - Description: Sent by the remote to request a specific file. - Parameters: - requested file: The name of the file being requested. - Requested pos: The offset within the file the remote is interested in. - Behavior: - If requested file is not in KnownFiles list: Report unknown file. - If requested file is in KnownFiles list and Requested pos is FileSize: Close and finalize file. Report remote refused file. Remove file from PendingFiles. Set TxState to TxGNF. - If requested file is in KnownFiles list and Requested pos is less than FileSize: Set file pointer to requested pos. Report remote requested offset. Set TxState to TxGNF. - If requested file is in KnownFiles list and Requested pos is greater than FileSize: Ignore frame. - Related Commands: M_GOT, M_SKIP ``` LANGUAGE: APIDOC CODE: ``` M_GOT command: - Description: Sent by the remote to acknowledge receipt of file data or completion. - Parameters: - file: The file identifier. - Behavior: - If file is currently transmitting: Close and finalize file. Report Remote refused file. Remove file from PendingFiles. Set TxState to TxGNF. - If file is not currently transmitting and File is in PendingFiles list: Finalize file. Report file has been sent. Remove file from PendingFiles. - If file is not currently transmitting and File is not in PendingFiles: Ignore frame. - Related Commands: M_GET, M_SKIP ``` LANGUAGE: APIDOC CODE: ``` M_SKIP command: - Description: Sent by the remote to indicate it will accept a file later or skip it for the current session. - Parameters: - file: The file identifier. - Behavior: - If file is currently transmitting: Close file (do not finalize). Report remote will accept this file later. Remove file from PendingFiles. Set TxState to TxGNF. - If file is not currently transmitting: Report remote will accept this file. - Related Commands: M_GET, M_GOT ``` ---------------------------------------- TITLE: Binkp M_GET Command DESCRIPTION: The M_GET command is a request to resend files, sent only after receiving an M_FILE command. It specifies the file to be resent by its filename, size in bytes, unixtime, and transmission offset. If a previous session was aborted, M_GET is used to continue receiving an incomplete file. LANGUAGE: APIDOC CODE: ``` M_GET ; ; ; Example: M_GET "config.sys 125 2476327846 100" Mailer reacts by discarding transmission in progress, performing seek() to the specified offset, and proceeding with transmission starting with an appropriate M_FILE command. ``` ---------------------------------------- TITLE: Binkp File Naming and Escaping Rules DESCRIPTION: Specifies rules for file naming within the Binkp protocol, emphasizing characters that must be escaped. It defines the structure for plain characters, safe characters, and hexadecimal escaped sequences. LANGUAGE: APIDOC CODE: ``` File Naming Conventions: Characters considered unsafe and MUST be escaped include space and backslash (\). Example: file name "abcd e.0f@" must be transmitted as "abcd\x20e.0f@". Grammar: filename = *pchar pchar = plain | escaped plain = alpha | digit | safe safe = "!" | "\"" | "#" | "$" | "%" | "&" | "'" | "(" | ")" | "*" | "+" | "," | "-" | "." | "/" | ":" | ";" | "<" | "=" | ">" | "?" | "@" | "[" | "]" | "^" | "_" | "`" | "{" | "|" | "}" | "~" alpha = "A" | "B" | ... | "Z" | "a" | "b" | ... | "z" digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" escaped = "\x" HEX HEX HEX = digit | "A" | "B" | "C" | "D" | "E" | "F" | "a" | "b" | "c" | "d" | "e" | "f" Note: The protocol does not impose limitations on file name length beyond the Binkp frame, but practical limits may exist due to OS compatibility. Maximum length can't exceed 32751 bytes. ``` ---------------------------------------- TITLE: Binkp Frame Structure and Notation DESCRIPTION: Defines the general structure of Binkp frames, including the SIZE field for data length, command ID, and the notation used for symbolic command representation. It specifies how commands are encoded within frames. LANGUAGE: APIDOC CODE: ``` Binkp Frame Structure: - Frame consists of a header and a DATA part. - Header includes 15 bits for SIZE (length of DATA part in octets). - Total frame length = SIZE + 2. - SIZE range: 0 to 32767 octets. SIZE 0 is obsolete. - First octet of DATA part is the command ID (0-127). - Other octets in DATA part carry command arguments. Command Notation: - Symbolic names (M_XXX) are used to refer to commands. - Format: M_XXX "Data string" - Encoding: - First octet of DATA: Numeric command ID for M_XXX. - "Data string": Copied into DATA area starting at the second octet. - SIZE field: Set to length of "Data string" + 1 (for command ID octet). - T bit (part of header): Should be set to 1 for command frames. ``` ---------------------------------------- TITLE: FTCS Protocol Session Setup - Answering Side States DESCRIPTION: Defines the states, predicates, actions, and next states for the answering side of the FTCS protocol during session setup. This includes handling incoming connections, address frames, password verification, and error conditions. LANGUAGE: APIDOC CODE: ``` FTCS Protocol Session Setup - Answering Side This section details the state transitions and actions for the answering side of the FTCS protocol during the session establishment phase. **State R0: WaitConn** - **Description**: Waits for an incoming connection. - **Predicates**: Incoming connection established. - **Actions**: - Send M_NUL frames with system info and capabilities (optional). - Send M_ADR frame with system addresses. - Set Timer. - **Next State**: R1 - **Alternate Predicates**: Nothing happens. - **Alternate Actions**: Wait. - **Alternate Next State**: R0 **State R1: WaitAddr** - **Description**: Waits for an M_ADR frame from the remote. - **Predicates**: M_ADR frame received. - **Actions**: - Check if a password exists for each of the remote addresses. - **Next State**: R2 - **Alternate Predicates**: M_ERR frame received. - **Alternate Actions**: Report error, send M_ERR frame. - **Alternate Next State**: exit - **Alternate Predicates**: M_NUL frame received. - **Alternate Actions**: Ignore or parse, optionally log. - **Alternate Next State**: R1 - **Alternate Predicates**: Other known frame received. - **Alternate Actions**: Report unexpected frame; send M_ERR frame. - **Alternate Next State**: exit - **Alternate Predicates**: Unknown frame received. - **Alternate Actions**: Ignore. - **Alternate Next State**: R1 - **Alternate Predicates**: Nothing happens. - **Alternate Actions**: Wait. - **Alternate Next State**: R1 - **Alternate Predicates**: Timer expired. - **Alternate Actions**: Report timeout. - **Alternate Next State**: exit **State R2: IsPasswd** - **Description**: Verifies password match based on received addresses. - **Predicates**: Yes, we have a password. - **Actions**: - Set Timer. - **Next State**: R3 - **Alternate Predicates**: Yes, but we have several different passwords for different addresses of the remote. - **Alternate Actions**: Send M_ERR frame, Report inconsistent password settings. - **Alternate Next State**: exit - **Alternate Predicates**: No, there's no password. - **Alternate Actions**: Set Timer. - **Alternate Next State**: R3 **State R3: (Implicit)** - **Description**: Continues session setup based on password verification outcome. - **Actions**: (Details not fully provided in this snippet for R3 onwards, but implies proceeding to file transfer or disconnection based on password match success/failure). ``` ---------------------------------------- TITLE: Binkp Receive Logic State Transitions DESCRIPTION: Illustrates the logic for handling incoming frames and data during Binkp reception. It maps received frame types and data conditions to specific actions and subsequent states, including error handling and acknowledgment. LANGUAGE: APIDOC CODE: ``` Receive Logic Table +-----------------+-----------------+-----------------+--------+--------+ | | | M_SKIP | Queue | | | | |-----------------+----------+--------| | | | Got M_NUL | Log/parse/| RxEOB |OK | | | | | ignore | | | | | |-----------------+----------+--------| | | | Got other | Report | RxDone |Failure | | | | known frame | unexpected| | | | | | or data frame | frame | | | | | |-----------------+----------+--------| | | | Got unknown | ignore | RxEOB |OK | | | | frame | | | | |-----------------+-----------------+-----------------+----------+--------| | RxDone | none | none | none | RxDone |OK | +-----------------+-----------------+-----------------+----------+--------+ ``` ---------------------------------------- TITLE: Transmit Routine State Machine DESCRIPTION: Details the states, predicates, conditions, actions, and next states for the Transmit Routine during file transfer. It handles transmitting frames, processing queue items, and managing transmission states. LANGUAGE: APIDOC CODE: ``` Transmit Routine State Machine: TxState | Predicate(s) | Condition(s) | Actions(s) | Next | Return --------|--------------|--------------|------------|--------|-------- TxWaitF | Get a frame from TheQueue | TheQueue is empty | none | TxWaitF | OK | | Got M_GET / M_GOT / M_SKIP | Transmit frame | TxWaitF | OK | | Got M_ERR | Report Error | TxDone | Failure | | Got M_EOB | Transmit M_EOB | TxEOB | OK | | Got M_FILE | Transmit M_FILE | TxAccF | continue | | Got other known frame | Report unexpected frame | TxDone | Failure | | Got unknown frame | ignore | TxWaitF | OK TxAccF | Decide how to accept Incoming File | Accept from beginning | Transmit M_GET | TxReceD | OK | | Accept from offset | Transmit M_GET | TxReceD | OK | | Accept later | Transmit M_SKIP | TxWaitF | OK ``` ---------------------------------------- TITLE: Binkp Session Termination Conditions DESCRIPTION: Outlines the conditions under which a Binkp session can be terminated. It details fatal errors, non-fatal errors, and the criteria for a successfully completed session, including the role of acknowledgements and end-of-block signals. LANGUAGE: APIDOC CODE: ``` APIDOC: Session Termination: A session may be terminated in any of the following cases: 1. Fatal Error: - If transmitted or received M_ERR. - Session should be deemed aborted due to a fatal error. 2. Non-Fatal Error: - If transmitted or received M_BSY. - Session should be deemed aborted due to non-fatal error (e.g., temporary lack of resources). 3. Successful Completion: - All files have been sent. - M_EOB has been received from the remote side (no more files for us). - Acknowledgements for all sent files have been received. - All files re-requested by M_GET have been received. - Session should be deemed successfully completed. Termination Mechanism: - Session termination is not a protocol stage. - Mailer may terminate a session at any time by issuing a disconnect (shutdown) command to the underlying transport layer, provided any of the three conditions above are met. - Mailer MUST take proper steps for graceful shutdown of the transport layer, ensuring all data is transmitted and received before disconnection. ``` ---------------------------------------- TITLE: File Transfer Protocol States DESCRIPTION: Describes the state machine for the file transfer stage, managed by Receive Routine (RxState) and Transmit Routine (TxState). It covers initialization, data transfer, and session completion, including states like RxWaitF, RxAccF, RxReceD, RxWriteD, RxEOB, RxDone for receiving and TxGNF, TxTryR, TxReadS, TxWLA, TxDone for transmitting. LANGUAGE: APIDOC CODE: ``` RxState := { RxWaitF | RxAccF | RxReceD | RxWriteD | RxEOB | RxDone } TxState := { TxGNF | TxTryR | TxReadS | TxWLA | TxDone } State: T0 (InitTransfer) - Predicate(s): none - Action(s): - Set Timer - Set RxState to RxWaitF - Set TxState to TxGNF - Next: T1 State: T1 (Switch) - Predicate(s): - RxState is RxDone and TxState is TxDone: - Action(s): Report session complete. - Next: exit - Data Available in Input Buffer: - Action(s): call Receive routine. - Next: T2 - Free space exists in output buffer: - Action(s): call Transmit routine. - Next: T3 - Nothing happens: - Action(s): Wait. - Next: T1 - Timer Expired: - Action(s): Report Timeout. - Next: exit State: T2 (Receive) - Predicate(s): Receive routine - Action(s): - Set Timer - Next: T1 ``` ---------------------------------------- TITLE: Binkp Command Classification by Protocol Stage DESCRIPTION: Categorizes Binkp commands based on the stage of the protocol they are used in, distinguishing between session setup, file transfer, and commands applicable at any stage. LANGUAGE: APIDOC CODE: ``` Command Stages: 1. Session Setup Stage: - M_ADR: MUST be sent by both sides. - M_PWD: MUST NOT be sent by the Answering side. - M_OK: MUST NOT be sent by the Originating side. - These commands MUST NOT be sent during the file transfer stage. 2. File Transfer Stage: - M_FILE, M_GOT, M_GET, M_SKIP, M_EOB. - These commands MUST NOT be sent during the session setup stage. 3. Any Stage: - M_NUL, M_ERR, M_BSY. - These commands MAY be sent any time during the session. ``` ---------------------------------------- TITLE: Receive Routine State Machine DESCRIPTION: Details the states, predicates, conditions, actions, and next states for the Receive Routine during file transfer. It handles incoming frames, processes specific frame types like M_GET, M_GOT, M_SKIP, M_ERR, and M_EOB, and manages file reception states. LANGUAGE: APIDOC CODE: ``` Receive Routine State Machine: RxState | Predicate(s) | Condition(s) | Actions(s) | Next | Return --------|--------------|--------------|------------|--------|-------- RxWaitF | Get a frame from Input Buffer | Haven't got a complete frame yet | none | RxWaitF | OK | | Got Data frame | ignore | RxWaitF | OK | | Got M_ERR | Report Error | RxDone | Failure | | Got M_GET / M_GOT / M_SKIP | Add frame to TheQueue | RxWaitF | OK | | Got M_NUL | Log/parse/ignore | RxWaitF | OK | | Got M_EOB | Report End of Batch | RxEOB | OK | | Got M_FILE | none | RxAccF | continue | | Got other known frame | Report unexpected frame | RxDone | Failure | | Got unknown frame | ignore | RxWaitF | OK RxAccF | Decide how to accept Incoming File | Accept from beginning | Report receiving file | RxReceD | OK | | Accept from offset (we do already have a part of file) | Send M_GET Report receiving file, requested offest | RxReceD | OK | | Accept later (or failed to create file) | Send M_SKIP Report we will accept | RxWaitF | OK ``` ---------------------------------------- TITLE: FTSC Protocol Message Types DESCRIPTION: Defines common message types used within the FTSC protocol for communication between sides during session setup and file transfer. Includes status indicators and file transfer markers. LANGUAGE: APIDOC CODE: ``` FTSC Protocol Messages: - M_OK: Acknowledgment of successful operation or authentication. - M_ERR: Error indicator, signaling a failure in an operation or authentication. - M_FILE "file_info": Indicates a file is being transferred, with associated metadata like filename, size, and checksum. - M_EOB: End of Block marker, signifying the completion of a data block or file segment. - M_GOT "file_info": Confirmation that a file has been received and processed. - M_ADR: Address frame, typically sent by the originating side during session setup. - M_PWD: Password frame, sent by the originating side for authentication. - M_NUL "OPT ...": Null frame used to indicate optional protocol extensions. ``` ---------------------------------------- TITLE: Binkp Frame Format Specification DESCRIPTION: Defines the structure of Binkp frames, including the header format, frame type, and data size. It details the mapping of an octet stream or datagram stream into Binkp frames, specifically for TCP/IP socket connections. LANGUAGE: APIDOC CODE: ``` Binkp Frame Structure: 7 6543210 76543210 +-+-+-------+--------+--- ................ ---+ |T| SIZE | DATA | +-+-+-------+--------+--- ................ ---+ |<- 2 octets ->|<- up to 32767 octets ->| (frame header) (frame data) Frame Header: - T (1 bit): Frame Type - 0: Indicates a data frame. - 1: Indicates a command frame. - SIZE (15 bits): Specifies the size of the DATA field in octets. Maximum value is 32767. Frame Data: - DATA: Contains the actual protocol command or data payload, with a maximum size of 32767 octets. ``` ---------------------------------------- TITLE: FTSC Basic Authentication Scheme DESCRIPTION: Describes the mandatory Basic Authentication Scheme for FTSC, including its requirements, limitations, and the exchange of password information for verification. LANGUAGE: APIDOC CODE: ``` FTSC Basic Authentication Scheme: Purpose: Authenticates the originating side to the answering side. Mechanism: 1. Originating side sends M_PWD frame containing a password. 2. Answering side verifies the password against presented addresses. 3. Answering side responds with M_OK (acknowledgement) or M_ERR (rejection). Limitations: - Password must be the same for all presented addresses if multiple are sent. - Passwords are sent in cleartext over the network. - Verification is performed only by the Answering side; Originating side cannot verify Answering side. Extensions for Improvement: - CRAM extension for secure password transmission. - 'IP address restriction' extension for Answering side verification. ``` ---------------------------------------- TITLE: ftsc ProcessTheQueue Routine Logic DESCRIPTION: Details the decision-making process for the ProcessTheQueue routine, which handles actions based on received messages (predicates) and specific conditions related to file transfer states and remote requests. This logic governs how the system responds to various file transfer scenarios. LANGUAGE: APIDOC CODE: ``` ProcessTheQueue Routine: - Purpose: To manage file transfer states and actions based on incoming messages and conditions. - Predicates and Actions: - Predicate: M_GET received - Condition: requested file is not in the KnownFiles list - Action: Report unknown file - Predicate: M_GET received for a known file - Condition: Requested pos is FileSize - Action: Close and finalize file. Report that remote refused file being transmitted. Remove file from the PendingFiles list. Set TxState to TxGNF. - Condition: Requested pos is less than FileSize - Action: Set file pointer to requested pos. Report that remote requested offset. Set TxState to TxGNF. - Condition: Requested pos is greater than FileSize - Action: Ignore frame. - Predicate: M_GOT file that is currently transmitting - Action: Close and finalize file. Report Remote refused file being transmitted. Remove file from the PendingFiles list. Set TxState to TxGNF. - Predicate: M_GOT file that is not currently transmitting - Condition: File is in PendingFiles list - Action: Finalize file. Report file has been sent. Remove file from the PendingFiles list. - Condition: File is not in PendingFiles - Action: Ignore frame. - Predicate: M_SKIP file that is currently transmitting - Action: Close file (do not finalize, will send later). Report remote will accept this file later. Remove file from the PendingFiles list. Set TxState to TxGNF. - Predicate: M_SKIP file that is not currently transmitting - Action: Report remote will accept this file. - Dependencies: KnownFiles list, PendingFiles list, TxState, FileSize, RxState, RxEOB. ``` ---------------------------------------- TITLE: ftsc Protocol State Machine DESCRIPTION: Defines the state transitions and actions within the ftsc communication protocol. It maps received frame types and internal conditions to specific system responses, including state changes and error handling. This table serves as a comprehensive reference for the protocol's behavior. LANGUAGE: APIDOC CODE: ``` State: RxReceD (Receive Data) Action/Condition: Get a frame from Input Buffer Sub-condition: Didn't got a complete frame yet Outcome: none Next State: RxReceD Status: OK Sub-condition: Got Data frame Outcome: Add frame to The Queue Next State: RxWriteD Status: continue Sub-condition: Got M_ERR Outcome: Report Error Next State: RxDone Status: Failure Sub-condition: Got M_GET / M_GOT / M_SKIP Outcome: Add frame to The Queue Next State: RxReceD Status: OK Sub-condition: Got M_NUL Outcome: Log/parse/ignore Next State: RxReceD Status: OK Sub-condition: Got M_FILE Outcome: Report partially received file Next State: RxAccF Status: Continue Sub-condition: Got other known frame Outcome: Report unexpected frame Next State: RxDone Status: Failure Sub-condition: Got unknown frame Outcome: ignore Next State: RxReceD Status: OK State: RxWriteD (Write Data) Action/Condition: Write data to file Sub-condition: Write Failed Outcome: Report error Next State: RxDone Status: Failure Sub-condition: File Pos > Reported Outcome: Report write beyond EOF Next State: RxDone Status: Failure Sub-condition: File Pos = Reported Outcome: Close File, Send M_GOT Report File Received Next State: RxWaitF Status: OK Sub-condition: File Pos < Reported Outcome: none Next State: RxReceD Status: OK State: RxEOB (End of Buffer) Action/Condition: Get a frame from Input Buffer Sub-condition: PendingFiles list is empty Outcome: none Next State: RxDone Status: OK Sub-condition: Didn't get a complete frame yet or TxState is not TxDone Outcome: none Next State: RxEOB Status: OK Sub-condition: Got M_ERR Outcome: Report Error Next State: RxDone Status: Failure Sub-condition: Got M_GET / M_GOT / M_SKIP Outcome: Add frame to The Queue Next State: RxEOB Status: OK State: Refuse (delete on remote) Action/Condition: Send M_GOT Report we do not accept file Outcome: later, not in current session Next State: RxWaitF Status: OK ``` ---------------------------------------- TITLE: Binkp M_SKIP Command DESCRIPTION: The M_SKIP command is a non-destructive skip that indicates the remote should postpone sending a specific file until the next session. It requires the filename, size, and unixtime of the file to be skipped. LANGUAGE: APIDOC CODE: ``` M_SKIP " " Example: M_SKIP "config.sys 125 2476327846" ```