vinegar.tftp.protocol

TFTP protocol definitions and utility functions.

vinegar.tftp.protocol.DEFAULT_BLOCK_SIZE = 512

Default size of a transfer block in bytes. This block size is used if the client does not request a specific block size.

class vinegar.tftp.protocol.ErrorCode(value)

Code identifying the type of of error in a TFTP error packet.

ACCESS_VIOLATION = 2

Access to the requested file has been forbidden.

DISK_FULL = 3

The disk is full (for write requests).

FILE_ALREADY_EXISTS = 6

File does already exist and is not overwritten (for write requests).

FILE_NOT_FOUND = 1

Requested file could not be found.

ILLEGAL_OPERATION = 4

The requested operation is not allowed in this context by the protocol specification.

NOT_DEFINED = 0

Error does not fall into any of the other well-defined categories.

NO_SUCH_USER = 7

The specified user is not known by this server (for write requests using the mail mode).

TRANSFER_ABORTED = 8

Transfer aborted. This can happen as part of option negotiation (RFC 2437).

UNKNOWN_TRANSFER_ID = 5

The packet was received from an unexpected source address or port.

static from_bytes(data: bytes, offset: int = 0) → ErrorCode

Extract the error code from a sequence of bytes. If the sequence contains less than offset plus two bytes or the two bytes do not represent a valid error code, an exception is thrown.

Parameters:

• data – sequence of bytes that contains the error code.

• offset – offset into the sequence of bytes. Default is zero (read from the start of the sequence).

to_bytes() → bytes

Return a byte buffer that contains the two bytes that represent this error code.

vinegar.tftp.protocol.MAX_BLOCK_NUMBER = 65535

Highest possible block number. Beyond this number, the block counter has to wrap back to zero or one.

vinegar.tftp.protocol.MAX_BLOCK_SIZE = 65464

Maximum transfer block size that may be requested by a client.

vinegar.tftp.protocol.MAX_REQUEST_PACKET_SIZE = 512

Maximum size of a request packet in bytes. A TFTP request must never exceed that size.

vinegar.tftp.protocol.MAX_TIMEOUT = 255

Maximum timeout interval that is alloed by RFC 2349.

vinegar.tftp.protocol.MIN_BLOCK_SIZE = 8

Minimum block size that may be requested by a client.

vinegar.tftp.protocol.MIN_TIMEOUT = 1

Minimum timeout interval that is allowed by RFC 2349.

vinegar.tftp.protocol.OPTION_BLOCK_SIZE = 'blksize'

Name of the block-size option.

vinegar.tftp.protocol.OPTION_TIMEOUT = 'timeout'

Name of the timeout-interval option.

vinegar.tftp.protocol.OPTION_TRANSFER_SIZE = 'tsize'

Name of the transfer-size option.

class vinegar.tftp.protocol.Opcode(value)

Code identifying the type of of a TFTP packet.

ACK = 4

Acknowledgement of a received DATA packet.

DATA = 3

Data transfer from the server to the client (read) or from the client to the server (write).

ERROR = 5

Error message.

OPTIONS_ACK = 6

Acknowledgement of supported options (send from the server to the client as the first response to a request specifying supported options).

READ_REQUEST = 1

Client request for reading a file.

WRITE_REQUEST = 2

Client request for writing a file.

static from_bytes(data: bytes, offset: int = 0) → Opcode

Extract the opcode from a sequence of bytes. If the sequence contains less than offset plus two bytes or the two bytes do not represent a valid opcode, an exception is thrown.

Parameters:

• data – sequence of bytes that contains the opcode.

• offset – offset into the sequence of bytes. Default is zero (read from the start of the sequence).

Returns:

Opcode represented by the two bytes at the specified offset.

to_bytes() → bytes

Return a byte buffer that contains the two bytes that represent this opcode.

class vinegar.tftp.protocol.TransferMode(value)

Transfer mode that can be requested by a client.

MAIL = 3

Deprecated mail transfer mode. This mode could be used by clients to write a file that would then be sent to a user by e-mail.

NETASCII = 1

Netascii transfer mode. In this mode, all line breaks are converted to CR LF before sending them over the wire.

OCTET = 2

Binary transfer mode. In this mode, bytes are sent without any conversion.

static from_str(mode: str) → TransferMode

Returns the transfer mode that is equivalent to the specified string. The string is not case sensitive and must be one of the three strings defined in RFC 1350.

If the string does not represent one of the well-defined transfer modes, an exception is raised.

Parameters:

mode – string identifying the transfer mode.

Returns:

TFTP transfer mode represented by the specified string.

to_str() → str

Return a string representing this transfer mode.

vinegar.tftp.protocol.data_packet(block_number: int, data: bytes) → bytes

Create a data packet using the given block number and data.

Parameters:

• block_number – consecutive number of the block being sent.

• data – data to be transferred in this block.

Returns:

byte sequence representing a data packet.

vinegar.tftp.protocol.decode_ack(data: bytes) → int

Decode a packet that represents an ACK. Throws an exception if the packet does not represent a valid ACK.

The return value is the acknowledged block number.

Parameters:

data – data representing the packet.

Returns:

acknowledged block number specified by the packet.

vinegar.tftp.protocol.decode_error(data: bytes) → Tuple[ErrorCode | None, str]

Decode a packet that represents an error message. This function does not raise an exception of the data does not represent a valid error message. Instead, it tries to reconstruct as much of it as possible.

The returned tuple contains the error code and the error message. If the error code cannot be decoded, None is returned instead. If the error message cannot be decoded, an empty string is returned instead.

Parameters:

data – data representing the packet.

Returns:

tuple where the first element is the error code and the second element is the error message sent by the peer.

vinegar.tftp.protocol.decode_read_request(data: bytes) → Tuple[str, TransferMode, Mapping[str, str]]

Decode a packet that represents a read request. Throws an exception if the packet does not represent a valid read request.

The returned tuple contains the requested filename, the requested transfer mode and the specified options.

Parameters:

data – data representing the packet.

Returns:

tuple where the first element is the requested filename, the second element is the requested transfer-mode, and the thir element are additional options that have been specified by the client.

vinegar.tftp.protocol.error_packet(error_code: ErrorCode, error_message: str = '') → bytes

Create an error packet using the given error code and message string.

Parameters:

• error_code – code that indicates the kind of error.

• error_message – optional error message.

Returns:

sequence of bytes representing the error packet.

vinegar.tftp.protocol.options_ack_packet(options: Mapping[str, str]) → bytes

Create a packet acknowledging options.

Parameters:

options – options that shall be acknowledged. Options are mappings from option name strings to value strings. Option names must be non-empty strings and there must be at least one option present.

Returns:

sequence of bytes representing the options acknowledgement packet.