From 9615b298dc4f8ddbde31ea8e083ec420c67e48a5 Mon Sep 17 00:00:00 2001 From: Tony Arcieri Date: Sat, 19 Apr 2025 08:35:38 -0600 Subject: [PATCH] ssh-encoding: add RFC4251-derived documentation Adds an overview of the data types and their associated wire formats implemented by this crate, adapting the text from RFC4251. --- ssh-encoding/src/lib.rs | 115 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/ssh-encoding/src/lib.rs b/ssh-encoding/src/lib.rs index b8b153db..de4359e3 100644 --- a/ssh-encoding/src/lib.rs +++ b/ssh-encoding/src/lib.rs @@ -21,6 +21,121 @@ unused_qualifications )] +//! ## Conventions used in this crate +//! +//! This crate uses the following type labels which are described in +//! [RFC4251 § 5]: +//! +//! #### `byte`, `byte[n]`, `byte[]` +//! +//! A byte represents an arbitrary 8-bit value (octet). +//! +//! Fixed length data is sometimes represented as an array of bytes, written +//! `byte[n]` where `n` is the number of bytes in the array. +//! +//! `byte[]` is a newer convention from OpenSSH for describing arbitrary +//! length bytestrings (similar to `string`, see below) but identifies data +//! which is inherently binary in nature, as opposed to text. +//! +//! #### `boolean` +//! +//! A boolean value is stored as a single byte. +//! +//! The value 0 represents FALSE, and the value 1 represents TRUE. All non-zero +//! values MUST be interpreted as TRUE; however, applications MUST NOT +//! store values other than 0 and 1. +//! +//! #### `uint32` +//! +//! Represents a 32-bit unsigned integer. +//! +//! Stored as four bytes in the order of decreasing significance (network byte order). +//! +//! For example: the value `699921578` (`0x29b7f4aa`) is stored as +//! `29 b7 f4 aa`. +//! +//! #### `uint64` +//! +//! Represents a 64-bit unsigned integer. +//! +//! Stored as eight bytes in the order of decreasing significance (network byte order). +//! +//! #### `string` +//! +//! Arbitrary length binary string. +//! +//! Strings are allowed to contain arbitrary binary data, including null characters and 8-bit +//! characters. +//! +//! They are stored as a `uint32` containing its length +//! (number of bytes that follow) and zero (= empty string) or more +//! bytes that are the value of the string. Terminating null +//! characters are not used. +//! +//! Strings are also used to store text. In that case, US-ASCII is +//! used for internal names, and ISO-10646 UTF-8 for text that might +//! be displayed to the user. The terminating null character SHOULD +//! NOT normally be stored in the string. For example: the US-ASCII +//! string "testing" is represented as `00 00 00 07 t e s t i n g`. The +//! UTF-8 mapping does not alter the encoding of US-ASCII characters. +//! +//! #### `mpint` +//! +//! Represents multiple precision integers in two's complement format, +//! stored as a string, 8 bits per byte, MSB first. +//! +//! Negative numbers have the value 1 as the most significant bit of the first byte of +//! the data partition. If the most significant bit would be set for +//! a positive number, the number MUST be preceded by a zero byte. +//! Unnecessary leading bytes with the value 0 or 255 MUST NOT be +//! included. The value zero MUST be stored as a string with zero +//! bytes of data. +//! +//! By convention, a number that is used in modular computations in +//! `Z_n` SHOULD be represented in the range `0 <= x < n`. +//! +//! Examples: +//! +//! value (hex) | representation (hex) +//! -------------------|--------------------- +//! `0` | `00 00 00 00` +//! `9a378f9b2e332a7` | `00 00 00 08 09 a3 78 f9 b2 e3 32 a7` +//! `80` | `00 00 00 02 00 80` +//! `-1234` | `00 00 00 02 ed cc` +//! `-deadbeef` | `00 00 00 05 ff 21 52 41 11` +//! +//! #### `name-list` +//! +//! A string containing a comma-separated list of names. +//! +//! A `name-list` is represented as a `uint32` containing its length +//! (number of bytes that follow) followed by a comma-separated list of zero or more +//! names. A name MUST have a non-zero length, and it MUST NOT +//! contain a comma (","). +//! +//! As this is a list of names, all the elements contained are names and MUST be in US-ASCII. +//! +//! Context may impose additional restrictions on the names. For example, +//! the names in a name-list may have to be a list of valid algorithm +//! identifiers (see Section 6 below), or a list of [RFC3066] language +//! tags. The order of the names in a name-list may or may not be +//! significant. Again, this depends on the context in which the list +//! is used. +//! +//! Terminating null characters MUST NOT be used, neither +//! for the individual names, nor for the list as a whole. +//! +//! Examples: +//! +//! value | representation (hex) +//! ---------------------------|--------------------- +//! `()`, the empty name-list | `00 00 00 00` +//! `("zlib")` | `00 00 00 04 7a 6c 69 62` +//! `("zlib,none")` | `00 00 00 09 7a 6c 69 62 2c 6e 6f 6e 65` +//! +//! [RFC3066]: https://datatracker.ietf.org/doc/html/rfc3066 +//! [RFC4251 § 5]: https://datatracker.ietf.org/doc/html/rfc4251#section-5 + #[cfg(feature = "alloc")] #[macro_use] extern crate alloc;