This is the cl-rfc4251 Reference Manual, version 0.1.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 15 05:19:57 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
cl-rfc4251Common Lisp library for encoding and decoding data in RFC 4251 compliant format
cl-rfc4251
Marin Atanasov Nikolov <dnaeon@gmail.com>
Marin Atanasov Nikolov <dnaeon@gmail.com>
BSD 2-Clause
## cl-rfc4251
‘cl-rfc4251‘ is a Common Lisp system, which provides support for
parsing [RFC 4251][RFC 4251] encoded binary
data, as described in the [Data Type Representations Used in the SSH
Protocols](https://tools.ietf.org/html/rfc4251#section-5) section of
the document.
## Requirements
* [Quicklisp][Quicklisp]
## Installation
Clone the [cl-rfc4251][cl-rfc4251] repo in
your [Quicklisp local-projects
directory][Quicklisp FAQ].
“‘ shell
git clone https://github.com/dnaeon/cl-rfc4251.git
“‘
Load the system.
“‘ shell
CL-USER> (ql:quickload :cl-rfc4251)
“‘
## Supported Data Types
The following table summarizes the supported data types, that can be
decoded or encoded by the respective ‘RFC4251:DECODE‘ and
‘RFC4251:ENCODE‘ generic functions. The ‘RFC 4251‘ and ‘cl-rfc4251
type‘ columns specify the mapping between the RFC-defined data type
name and the keywords used to decode or encode a given value in Common
Lisp.
| RFC 4251 | cl-rfc4251 type | Description |
|————-|—————–|————————————————–|
| ‘byte‘ | ‘:byte‘ | An arbitrary 8-bit value (octet) |
| ‘byte[n]‘ | ‘:raw-bytes‘ | A sequence of raw bytes up to a given length |
| ‘boolean‘ | ‘:boolean‘ | A boolean value |
| ‘uint32‘ | ‘:uint32‘ | Unsigned 32-bit integer in big-endian byte order |
| ‘uint64‘ | ‘:uint64‘ | Unsigned 64-bit integer in big-endian byte order |
| ‘string‘ | ‘:string‘ | Arbitrary length string |
| ‘mpint‘ | ‘:mpint‘ | Multiple precision integer |
| ‘name-list‘ | ‘:name-list‘ | A string of comma-separated names |
In addition to the above data types the ‘cl-rfc4251‘ system supports
encoding and decoding of these types as well. Note, that these are not
mentioned in RFC 4251.
| cl-rfc4251 type | Description |
|—————–|——————————————————-|
| ‘:uint16-be‘ | Unsigned 16-bit integer in big-endian byte order |
| ‘:uint16-le‘ | Unsigned 16-bit integer in little-endian byte order |
| ‘:uint32-le‘ | Unsigned 32-bit integer in little-endian byte order |
| ‘:uint64-le‘ | Unsigned 64-bit integer in little-endian byte order |
| ‘:c-string‘ | NULL-terminated C string |
| ‘:buffer‘ | A buffer similar to ‘:string‘, but contains raw bytes |
## Usage
The following section provides various examples showing how to encode
and decode values using the ‘cl-rfc4251‘ system.
For additional examples, make sure to check the [test
suite](./t/test-suite.lisp).
### Decoding
The ‘cl-rfc4251‘ system exports the generic functions ‘DECODE‘ and
‘ENCODE‘ via the ‘CL-RFC4251‘ (also available via its nickname
‘RFC4251‘) package.
The ‘RFC4251:DECODE‘ function takes a *type* and a *binary stream*
from which to decode. Some types also take additional keyword
parameters (e.g. ‘:raw-bytes‘), which allow to specify the number of
bytes to be decoded.
In all of the examples that follow below ‘s‘ represents a binary
stream. You can also use the ‘RFC4251:MAKE-BINARY-INPUT-STREAM‘
function to create a binary stream, which uses a vector for the
underlying data.
‘RFC4251:DECODE‘ returns multiple values – the actual decoded value,
and the number of bytes that were read from the binary stream in order
to produce the value.
Decode raw bytes with a given length from the binary stream ‘s‘.
“‘ common-lisp
CL-USER> (rfc4251:decode :raw-bytes s :length 4)
#(0 0 0 8)
4
“‘
The second value in above example indicates the actual bytes that were
read from the binary stream.
This example decodes a 16-bit unsigned integer represented in
big-endian byte order from a given binary stream ‘s‘.
“‘ common-lisp
CL-USER> (let ((s (rfc4251:make-binary-input-stream #(0 #x80))))
(rfc4251:decode :uint16 s))
128
2
“‘
The following example decodes a multiple precision integer represented
in two’s complement format from the binary stream ‘s‘.
“‘ common-lisp
CL-USER> (let ((s (rfc4251:make-binary-input-stream #(#x00 #x00 #x00 #x05 #xFF #x21 #x52 #x41 #x11))))
(rfc4251:decode :mpint s))
-3735928559
9
“‘
The second value in the example above, which specifies the number of
bytes being read is ‘9‘, because we had to read one ‘uint32‘ value
(the header) and additional ‘5‘ bytes (the value partition).
A bytes buffer is similar to a ‘:string‘, except that the bytes are
not explicitely converted to a string value, but instead the result
contains the raw bytes.
“‘ common-lisp
CL-USER> (let ((s (rfc4251:make-binary-input-stream #(#x00 #x00 #x00 #x04 #x0A #x0B #x0C #x0D))))
(rfc4251:decode :buffer s))
#(10 11 12 13)
8
“‘
### Encoding
The ‘RFC4251:ENCODE‘ generic function is used to encode data. The
function returns the total number of bytes written to the binary
stream.
You can also use the ‘RFC4251:MAKE-BINARY-OUTPUT-STREAM‘ function to
create a binary stream, if needed.
The following example encodes an unsigned 16-bit integer value.
“‘ common-lisp
CL-USER> (defparameter *s* (rfc4251:make-binary-output-stream))
*S*
CL-USER> (rfc4251:encode :uint16 42 *s*)
2
CL-USER> (rfc4251:get-binary-stream-bytes *s*)
#(0 42)
“‘
Note in the second expression the number of bytes that were written.
Above example, can be written this way as well, if you only care about
the actual encoded bytes.
“‘ common-lisp
CL-USER> (let ((s (rfc4251:make-binary-output-stream)))
(rfc4251:encode :uint16 42 s) ;; <- Encode the value into the stream
(rfc4251:get-binary-stream-bytes s)) ;; <- Return the contents of the stream
#(0 42)
“‘
The following example encodes a string value.
“‘ common-lisp
CL-USER> (defparameter *s* (rfc4251:make-binary-output-stream))
*S*
CL-USER> (rfc4251:encode :string "Hello, World!" *s*)
17
CL-USER> (rfc4251:get-binary-stream-bytes *s*)
#(0 0 0 13 72 101 108 108 111 44 32 87 111 114 108 100 33)
“‘
The result from the second expression here is ‘17‘, which includes the
‘4‘ (uint32) bytes required for the header (representing the bytes that follow),
plus the additional ‘13‘ bytes representing the actual string data.
The following examples show how to encode ‘mpint‘ values according to
[RFC 4251][RFC 4251].
“‘ common-lisp
CL-USER> (let ((s (rfc4251:make-binary-output-stream)))
(rfc4251:encode :mpint #x00 s) ;; <- Encode the zero value
(rfc4251:get-binary-stream-bytes s)) ;; <- Get the encoded data
#(0 0 0 0)
“‘
Here are a few more examples taken directly from the examples described in
[RFC 4251][RFC 4251].
“‘ common-lisp
CL-USER> (let ((s (rfc4251:make-binary-output-stream)))
(rfc4251:encode :mpint #x-DEADBEEF s)
(rfc4251:get-binary-stream-bytes s))
#(0 0 0 5 255 33 82 65 17)
CL-USER> (let ((s (rfc4251:make-binary-output-stream)))
(rfc4251:encode :mpint #x80 s)
(rfc4251:get-binary-stream-bytes s))
#(0 0 0 2 0 128)
CL-USER> (let ((s (rfc4251:make-binary-output-stream)))
(rfc4251:encode :mpint #x9A378F9B2E332A7 s)
(rfc4251:get-binary-stream-bytes s))
#(0 0 0 8 9 163 120 249 178 227 50 167)
CL-USER> (let ((s (rfc4251:make-binary-output-stream)))
(rfc4251:encode :mpint #x-1234 s)
(rfc4251:get-binary-stream-bytes s))
#(0 0 0 2 237 204)
“‘
Encoding a bytes buffer. A bytes buffer is preceeded by its length,
similar to the way ‘:string‘ values are being encoded.
“‘ common-lisp
CL-USER> (let ((s (rfc4251:make-binary-output-stream)))
(rfc4251:encode :buffer #(#x0A #x0B #x0C #x0D) s)
(rfc4251:get-binary-stream-bytes s))
#(0 0 0 4 10 11 12 13)
“‘
## Tests
Tests are provided as part of the ‘cl-rfc4251.test‘ system.
In order to run the tests you can evaluate the following expressions.
“‘ common-lisp
CL-USER> (ql:quickload :cl-rfc4251.test)
CL-USER> (asdf:test-system :cl-rfc4251.test)
“‘
Or you can run the tests in a Docker container instead.
First, build the Docker image.
“‘ shell
docker build -t cl-rfc4251 .
“‘
Run the tests.
“‘ shell
docker run –rm cl-rfc4251
“‘
## Contributing
‘cl-rfc4251‘ is hosted on
[Github](https://github.com/dnaeon/cl-rfc4251). Please contribute by
reporting issues, suggesting features or by sending patches using pull
requests.
## Authors
* Marin Atanasov Nikolov (dnaeon@gmail.com)
## License
This project is Open Source and licensed under the [BSD
License](http://opensource.org/licenses/BSD-2-Clause).
[RFC 4251]: https://tools.ietf.org/html/rfc4251
[Quicklisp]: https://www.quicklisp.org/beta/
[Quicklisp FAQ]: https://www.quicklisp.org/beta/faq.html
[cl-rfc4251]: https://github.com/dnaeon/cl-rfc4251
0.1.0
trivial-gray-streams (system).
uiop (system).
util (module).
core (module).
client-package (module).
Modules are listed depth-first from the system components tree.
cl-rfc4251/coreutil (module).
cl-rfc4251 (system).
decoder.lisp (file).
encoder.lisp (file).
stream.lisp (file).
cl-rfc4251/client-packagecore (module).
cl-rfc4251 (system).
package.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
cl-rfc4251/cl-rfc4251.asdcl-rfc4251/util/util.lispcl-rfc4251/core/decoder.lispcl-rfc4251/core/encoder.lispcl-rfc4251/core/stream.lispcl-rfc4251/client-package/package.lispcl-rfc4251/util/util.lisputil (module).
decode-int-be (function).
decode-int-le (function).
encode-int-be (function).
encode-int-le (function).
twos-complement (function).
cl-rfc4251/core/decoder.lispcl-rfc4251/core/encoder.lispcl-rfc4251/core/stream.lispcore (module).
binary-input-stream (class).
binary-input-stream-data (reader method).
binary-input-stream-end (reader method).
binary-input-stream-index (reader method).
binary-output-stream (class).
binary-output-stream-data (reader method).
(setf binary-output-stream-data) (writer method).
get-binary-stream-bytes (generic function).
make-binary-input-stream (function).
make-binary-output-stream (function).
print-object (method).
print-object (method).
stream-element-type (method).
stream-element-type (method).
stream-read-byte (method).
stream-write-byte (method).
with-binary-input-stream (macro).
with-binary-output-stream (macro).
cl-rfc4251/client-package/package.lispclient-package (module).
Packages are listed by definition order.
cl-rfc4251-systemcl-rfc4251.encodercl-rfc4251cl-rfc4251.streamcl-rfc4251.utilcl-rfc4251.decodercl-rfc4251.encoderrfc4251.encoder
common-lisp.
encode (generic function).
cl-rfc4251.streamrfc4251.stream
common-lisp.
binary-input-stream (class).
binary-input-stream-data (generic reader).
binary-input-stream-end (generic reader).
binary-input-stream-index (generic reader).
binary-output-stream (class).
binary-output-stream-data (generic reader).
(setf binary-output-stream-data) (generic writer).
get-binary-stream-bytes (generic function).
make-binary-input-stream (function).
make-binary-output-stream (function).
with-binary-input-stream (macro).
with-binary-output-stream (macro).
cl-rfc4251.utilrfc4251.util
common-lisp.
decode-int-be (function).
decode-int-le (function).
encode-int-be (function).
encode-int-le (function).
twos-complement (function).
cl-rfc4251.decoderrfc4251.decoder
common-lisp.
decode (generic function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Decode a vector of bytes into an integer, using big-endian byte order
Decode a vector of bytes into integer, using litte-endian byte order
Encode the given value as bytes in big-endian byte order
Convert an integer value to a vector of bytes in little-endian byte order
Creates a new instance of BINARY-INPUT-STREAM class
Creates a new instance of BINARY-OUTPUT-STREAM
Returns the two’s complement of the given number
binary-input-stream)) ¶A vector providing the underlying data
data.
binary-input-stream)) ¶End marker up to which bytes are to be read
end.
binary-input-stream)) ¶Current index position in the data
binary-output-stream)) ¶binary-output-stream)) ¶The underlying vector to which data is written
data.
Decode a value with the given type from the binary
stream. Returns multiple values – the decoded value and the number of
bytes that were actually read to produce the value.
(eql :buffer)) stream &key) ¶Decode a bytes buffer from the given stream
(eql :c-string)) stream &key) ¶Decode a NULL-terminated C string from the given stream
(eql :name-list)) stream &key) ¶Decode a comma-separated list of names from the given binary stream
(eql :mpint)) stream &key) ¶Decode a multiple precision integer in two’s complement format
(eql :string)) stream &key) ¶Decode a string value from the given binary stream
(eql :uint64)) stream &key) ¶Synonym for :uint64-be
(eql :uint64-le)) stream &key) ¶Decode 64-bit unsigned integer using little-endian byte order
(eql :uint64-be)) stream &key) ¶Decode 64-bit unsigned integer using big-endian byte order
(eql :uint32)) stream &key) ¶Synonym for :uint32-be
(eql :uint32-le)) stream &key) ¶Decode 32-bit unsigned integer using little-endian byte order
(eql :uint32-be)) stream &key) ¶Decode 32-bit unsigned integer using big-endian byte order
(eql :uint16)) stream &key) ¶Synonym for :uint16-be
(eql :uint16-le)) stream &key) ¶Decode 16-bit unsigned integer using little-endian byte order
(eql :uint16-be)) stream &key) ¶Decode 16-bit unsigned integer using big-endian byte order
(eql :boolean)) stream &key) ¶Decode a boolean value from the given binary stream
(eql :byte)) stream &key) ¶Decode a single byte (octet) from the given binary stream
(eql :raw-bytes)) stream &key length) ¶Read up to the given length of raw bytes from the stream
Encodes the value of the given type into the binary stream. Returns the number of bytes that were written to the stream.
(eql :buffer)) value stream &key) ¶Encode a bytes buffer into the given stream
(eql :c-string)) value stream &key) ¶Encode a NULL-terminated C string into the binary stream
(eql :name-list)) value stream &key) ¶Encode a list of strings into the binary stream
(eql :mpint)) value stream &key) ¶Encode the given multiple precision integer value into the binary stream
(eql :string)) value stream &key) ¶Encode a string value into the given binary stream
(eql :uint64)) value stream &key) ¶Synonym for :uint64-be
(eql :uint64-le)) value stream &key) ¶Encode an unsigned 64-bit integer in little-endian byte order
(eql :uint64-be)) value stream &key) ¶Encode an unsigned 64-bit integer in big-endian byte order
(eql :uint32)) value stream &key) ¶Synonym for :uint32-be
(eql :uint32-le)) value stream &key) ¶Encode an unsigned 32-bit integer in little-endian byte order
(eql :uint32-be)) value stream &key) ¶Encode an unsigned 32-bit integer in big-endian byte order
(eql :uint16)) value stream &key) ¶Synonym for :uint16-be
(eql :uint16-le)) value stream &key) ¶Encode an unsigned 16-bit integer in little-endian byte order
(eql :uint16-be)) value stream &key) ¶Encode an unsigned 16-bit integer in big-endian byte order
(eql :boolean)) value stream &key) ¶(eql :raw-bytes)) bytes-vector stream &key length) ¶(eql :byte)) value stream &key) ¶Encodes a raw byte into the given binary stream
Returns the underlying bytes for a binary stream
binary-output-stream)) ¶binary-input-stream)) ¶binary-input-stream) stream) ¶binary-output-stream) stream) ¶binary-input-stream)) ¶binary-output-stream)) ¶binary-input-stream)) ¶Reads a byte from the binary stream
sb-gray.
binary-output-stream) value) ¶Writes a byte to the given binary stream
sb-gray.
Binary input stream class using a vector as the underlying data
fundamental-binary-input-stream.
A vector providing the underlying data
(error "must provide vector data")
:data
This slot is read-only.
Current index position in the data
0
:index
This slot is read-only.
End marker up to which bytes are to be read
:end
This slot is read-only.
Binary output stream class using a vector for the underlying data
fundamental-binary-output-stream.
The underlying vector to which data is written
(make-array 0 :element-type (quote (unsigned-byte 8)) :adjustable t :fill-pointer 0)
:data
| Jump to: | (
B D E F G M P S T W |
|---|
| Jump to: | (
B D E F G M P S T W |
|---|
| Jump to: | D E I S |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| D | |||
data: | Public classes | ||
data: | Public classes | ||
| | |||
| E | |||
end: | Public classes | ||
| | |||
| I | |||
index: | Public classes | ||
| | |||
| S | |||
Slot, data: | Public classes | ||
Slot, data: | Public classes | ||
Slot, end: | Public classes | ||
Slot, index: | Public classes | ||
| | |||
| Jump to: | D E I S |
|---|
| Jump to: | B C D E F M P S U |
|---|
| Jump to: | B C D E F M P S U |
|---|