The Industria Libraries Manual

This procedures accepts either a filename or a binary input port. Returns #t if the file or port starts with what looks like an ELF image. If it is not an ELF image #f is returned. The port is returned to its previous position.

ELF-MAGIC

This constant contains the “magic” integer used at the start of ELF images.

This procedure accepts a filename or an binary input port. The ELF header at the start of the file is parsed and returned as an elf-image object.

The returned object contains the input port that was used to read the header, so that the rest of the procedures in this library do not need to take an extra port argument. All other fields contain integers.

          (import (weinholt binfmt elf))
          (open-elf-image "/bin/ls")
          ⇒ #[elf-image #<input-port (binary) "/bin/ls">
               2 1 0 0 262 1 4203856 64 106216 0 64 56 8 64 28 27]

Contructs a new elf-image object. This procedure is normally not useful when reading ELF images. No checks are performed on the arguments.

Returns #t if obj is an ELF image object.

If image was created by open-elf-image, then this returns the port that the ELF header was read from.

Returns an integer that represents the word size of image. The order and size of fields in the ELF format vary depending on the word size, but that is all hidden by this library.

ELFCLASS32

The image is a 32-bit ELF image.

ELFCLASS64

The image is a 64-bit ELF images.

Returns an integer that represents the endianness of image. The byte order used in ELF images is the same that is used by the machine that the image is intended to run on.

ELFDATA2LSB

The image is in little endian format.

ELFDATA2MSB

The image is in big endian format.

The Operating System ABI indicates which operating system image was created for. The returned value might be one of the ELFOSABI-* constants.

ELFOSABI-SYSV

System V. An earlier version of ELF did not include the OS ABI field at all and this value is the default.

ELFOSABI-HPUX

ELFOSABI-NETBSD

ELFOSABI-LINUX

Linux. (This does not actually seem to be used by Linux.)

ELFOSABI-SOLARIS

ELFOSABI-AIX

ELFOSABI-IRIX

ELFOSABI-FREEBSD

ELFOSABI-TRU64

ELFOSABI-MODESTO

ELFOSABI-OPENBSD

ELFOSABI-OPENVMS

ELFOSABI-NSK

ELFOSABI-AROS

The version number of the Operating System ABI.

The type of the image. This might be one of the ET-* constants.

ET-NONE

No type was specified.

ET-REL

Relocatable object file.

ET-EXEC

Executable object file.

ET-DYN

Shared object file.

ET-CORE

Core dump.

ET-LOOS

Start of the environment-specific range.

ET-HIOS

End of the environment-specific range.

ET-LOPROC

Start of the processor-specific range.

ET-HIPROC

End of the processor-specific range.

Most ELF images contain executable code. This field specifies which machine type (CPU architecture) is needed to run the code.

EM-NONE

No machine type was given.

EM-M32

EM-SPARC

EM-386

The Intel 80386 and all its extensions. The 64-bit extensions use EM-X86-64 instead.

EM-68K

EM-88K

EM-860

EM-MIPS

EM-MIPS-RS3-LE

EM-PARISC

EM-SPARC32PLUS

EM-PPC

EM-PPC64

EM-S390

EM-ARM

EM-SPARCV9

EM-IA-64

EM-68HC12

EM-X86-64

The AMD x86-64 architecture.

EM-68HC11

The ELF format version used. There is only one valid value for this field, EV-CURRENT.

EV-CURRENT

The current ELF version.

The program entry point. When an operating system has loaded an ELF image (by mapping the segments into virtual memory) it needs to know which address contains the first instruction of the program.

The port position at which the first segment can be found. The name is short for “program header offset”.

The port position at which the first section header can be found.

This field can contain processor-specific flags.

The size of the ELF header in bytes.

The size of a segment header in bytes.

The number of segment headers contained in the ELF image.

The size of a section header in bytes.

The number of section headers contained in the ELF image.

This is an index into the section headers table. It indicates which of the section headers contains the names of all the section headers.

SHN-UNDEF

This is used when there is no reference to any section.

This is an alist that contains human-readable names for all the exported EM-* constants.

Constructs a new elf-section object. These objects represent section headers and are used to refer to the contents of the file. This procedure is normally not useful when reading ELF images. No checks are performed on the arguments.

Returns #t if obj is an ELF section object.

Gives the name of section as an index into the section name table, which contains #\nul terminated strings. The section name table is located by using elf-image-shstrndx.

An integer representing the type of section.

SHT-NULL

The section header is unused.

SHT-PROGBITS

The section contains executable code.

SHT-SYMTAB

The section contains a symbol table.

SHT-STRTAB

The section contains a string table.

SHT-RELA

SHT-HASH

SHT-DYNAMIC

SHT-NOTE

SHT-NOBITS

SHT-REL

SHT-SHLIB

SHT-DYNSYM

The section contains a symbol table with only the symbols needed for dynamic linking.

SHT-LOOS

Start of the environment-specific range.

SHT-HIOS

End of the environment-specific range.

SHT-LOPROC

Start of the processor-specific range.

SHT-HIPROC

End of the processor-specific range.

An integer representing a bitmask of flags for section.

SHF-WRITE

The section data will be writable when the program is running.

SHF-ALLOC

The section data will be mapped into memory when the program is running.

SHF-EXECINSTR

The section data contains executable instructions.

SHF-MASKOS

The bitmask for environment-specific flags.

SHF-MASKPROC

The bitmask for processor-specific flags.

If section is mapped into memory when the program is running this field contains the address at which it will be mapped.

The port position at which the data of section can be found.

The length of the data of section. If the section type is not SHT-NULL then this indicates the size of the segment in the image file.

This may contain a reference to another section.

This may contain extra information, depending on the type of section.

This specifies the alignment requirements of the data in section.

If section contains fixed-size entries then this is used to specify the size of those entries.

Constructs a new elf-segment object. These objects represent program headers and are used to refer to the contents of the file. This procedure is normally not useful when reading ELF images. No checks are performed on the arguments.

Returns #t if obj is an ELF segment object.

An integer representing the type of the segment.

PT-NULL

This segment is unused.

PT-LOAD

This segment should be mapped into memory when loading the executable.

PT-DYNAMIC

PT-INTERP

This segment contains the name of a program that should be invoked to interpret the binary. This is most commonly the system's dynamic linker/loader.

PT-NOTE

PT-PHDR

PT-LOPROC

Start of the processor-specific range.

PT-HIPROC

End of the processor-specific range.

An integer representing a bitmask of flags for segment.

PF-X

This segment should be mapped as executable.

PF-W

This segment should be mapped as writable.

PF-R

This segment should be mapped as readable.

PF-MASKOS

The bitmask for environment-specific flags.

PF-MASKPROC

The bitmask for processor-specific flags.

The port position for the start of segment.

The virtual address at which segment will be mapped.

The physical address at which segment will be mapped, if it is relevant to the operating system loading the executable. Normally this is just the same as the virtual address.

The size of segment in the file.

The size of segment in the program memory. This can be larger than filesz when the program uses uninitialized data (bss).

The alignment requirements of segment.

Contructs a new elf-symbol object. This procedure is normally not useful when reading ELF images. No checks are performed on the arguments.

Returns #t if obj is an ELF symbol object.

The name of symbol. This is given as an index into a string table. The string table is located in one of the sections of the image. Use elf-section-link on the elf-section object for the symbol table for find it. Normally you will not need to read the name yourself, if you use elf-image-symbols to read the symbol table.

This field is reserved and should be zero.

The index of the section that is associated with symbol. This can also be one of the special section index constants, SHN-*.

SHN-ABS

The symbol references an absolute address.

SHN-COMMON

The symbol references an address in the uninitialized data segment (bss).

A value or address associated with symbol. For a symbol that refers to a function, this is the address of the function.

The size of the data symbol refers to.

An integer representing the symbol binding semantics of symbol.

STB-LOCAL

The symbol is local to the object file it is located in.

STB-GLOBAL

The symbol can be seen by all object files.

STB-WEAK

The symbol can be seen by all object files, but may be overridden.

STB-LOOS

Start of the environment-specific range.

STB-HIOS

End of the environment-specific range.

STB-LOPROC

Start of the processor-specific range.

STB-HIPROC

End of the processor-specific range.

An integer representing the type of object symbol refers to.

STT-NOTYPE

No particular type.

STT-OBJECT

A variable, array or some other data object.

STT-FUNC

A function or some other executable code.

STT-SECTION

A section (like the .text section).

STT-FILE

A source code file name associated with the image.

STT-LOOS

Start of the environment-specific range.

STT-HIOS

End of the environment-specific range.

STT-LOPROC

Start of the processor-specific range.

STT-HIPROC

End of the processor-specific range.

This is a combination of the binding and type fields of symbol. It is used in the binary encoding of symbols, but is otherwise not interesting on its own.

Searches image for the section header named name. Returns the matching elf-section object, or #f if there is no such section.

          (import (weinholt binfmt elf))
          (let ((elf (open-elf-image "/bin/ls")))
            (elf-image-section-by-name elf ".text"))
          ⇒ #[elf-section 132 1 6 4203856 9552 65240 0 0 16 0]

Returns all the section headers of image as an alist mapping names to elf-section objects.

          (let ((elf (open-elf-image "/bin/ls")))
            (map car (elf-image-sections elf)))
          ⇒
          ("" ".interp" ".note.ABI-tag" ".note.gnu.build-id" ".hash"
           ".gnu.hash" ".dynsym" ".dynstr" ".gnu.version"
           ".gnu.version_r" ".rela.dyn" ".rela.plt" ".init" ".plt"
           ".text" ".fini" ".rodata" ".eh_frame_hdr" ".eh_frame"
           ".ctors" ".dtors" ".jcr" ".dynamic" ".got" ".got.plt"
           ".data" ".bss" ".shstrtab")

Locates and parses the symbol table of image. The symbol table contains information about the locations of functions, data structures and other things. The return value is a vector of all the symbols, represented as pairs where the car is the name of the symbol and the cdr is an elf-symbol object.

Returns #f if image has no symbol table. Most executables are “stripped” of their symbol table to save space and to make debugging more difficult.

          (let ((elf (open-elf-image "/usr/lib/debug/lib/libc-2.11.2.so")))
            (assoc "memcpy" (vector->list (elf-image-symbols elf))))
          ⇒ ("memcpy" . #[elf-symbol 78278 18 0 12 522064 1125])

Takes a filename or a binary input port and returns true if the file looks like a GZIP file. The port should have set-port-position! and port-position.

Returns a new port that can be used to read decompressed GZIP data from the binary-input-port. The id is the name of the returned port.

If close-underlying-port? is true then at the end of the GZIP stream the binary-input-port will be closed.

Opens the file specified by filename and returns a binary input port that decompresses the file on-the-fly.

Reads compressed data from binary-input-port and writes the decompressed data to binary-output-port. Returns a list of gzip headers, one for each gzip member of the file (gzip files can be concatenated).

Reads a GZIP header from binary-input-port and performs sanity checks.

True if the uncompressed data associated with hdr is believed to be text.

The file's modification time as an SRFI-19 date or #f is none is available.

An “extra field” which some systems use to encode additional file attributes. This is an unparsed bytevector.

The file's original filename as a string or #f if none is available.

A file comment as a string or #f if none is available.

The symbol slowest, fastest or an integer (probably denoting a different compression setting).

The id number of the operating system that created the file. It is e.g. 0 for DOS, 1 for Amiga, 2 for VMS, 3 for Unix.

Inflates a complete DEFLATE data stream. It reads compressed data from binary-input-port and writes decompressed data to binary-output-port.

The arguments crc-init, crc-update and crc-finish should have the same semantics that (weinholt crypto crc) uses, see crypto crc and compression adler-32.

Three values are returned: the final CRC of the decompressed data, its length, and a bytevector with read but unused bytes from the input.

Returns a procedure that, when called, decompresses a DEFLATE block from binary-input-port. The returned procedure should be called with zero arguments and returns either the symbol done, to signify the end of the DEFLATE stream, or more to indicate more blocks are (or will be) available.

For a description of the sink argument, see compression sliding-buffer.

The window-size is the size of the sliding window buffer. The most common value is 32*1024 bytes, but each DEFLATE stream has a correct value that was used when creating the stream. For zlib streams this value is specified in the header.

The dictionary is a bytevector that is prepended to the output buffer, but it is not actually copied to the output. See compression zlib.

The inflate algorithm needs some lookahead and therefore it can read a byte or two that does not belong to the inflate stream itself. Apply the symbol get-buffer to the returned procedure to recover those extra bytes as a bytevector.

Returns a new sliding buffer with the given sink and size. The size determines how far back in the output stream sliding-buffer-dup! can look.

True if obj is a sliding buffer.

Copy initial data into the buffer so that it can be used with sliding-buffer-dup!. The sink does not receive this data.

Sends the buffered data to to the buffer's sink.

Reads len bytes from binary-input-port into the buffer.

Copies the byte u8 into the buffer.

Duplicates len bytes from inside the output stream of buffer at distance bytes from the current end of the buffer.

Takes a filename or a binary input port and returns true if the file looks like a XZ file. The port should have set-port-position! and port-position.

Returns a new port that can be used to read decompressed XZ data from the binary-input-port. The id is the name of the returned port.

To verify that the file was decompressed correctly it is necessary to close the port. On close the port will read all remaining data and compare its checksum to the checksum at the end of the file.

If close-underlying-port? is true then when the XZ input port is closed the binary-input-port will also be closed.

Opens the file specified by filename and returns a binary input port that decompresses the file on-the-fly.

Returns the central directory of the ZIP archive in binary-input-port. This is a list of central directory records and the end of central directory record.

Uses the data in the central directory record cdir to read the associated file record from zip-input-port. The returned value is also referred to as a local file header.

Extracts the file associated with the local and central records. The zip-port is the same port the records were read from.

The extracted file will be created relative to the current working directory (or default filespec) and will retain as many attributes as possible from those recorded in the ZIP archive.

Extracts the file associated with the local and central records to the given binary output port dest-port. The zip-port is the same port the records were read from.

It is possible to preserve the file's attributes (at least if the extracted file is a regular byte stream) by using the accessors for local and central similarly to how the “extra” library uses that data.

Appends the file given by filename to zip-port, which is a binary output port. Returns a central directory record.

Similar to append-file, except no file is used. Instead the data for the file is read from the binary input port data-port. Because there is no file, all the file attributes need to be provided explicitly. A central directory record is returned.

For a description of the attributes, see the accessors for file and central directory records.

Writes a list of central directory records to the zip-port and then appends the special end of central directory record. After this no more data should be written to the ZIP archive. The list of central directory records centrals should be those returned by append-file and append-port.

Builds a complete ZIP archive that includes all the files specified by the list filenames and writes it to port, which should be a binary output port.

True if n represents a supported compression method. Currently only stored and deflated are supported. See file-record-compression-method.

If an attempt was made to access an unsupported file record or to extract a file using an unsupported compression method then a condition will be raised that satisfies this predicate.

True if obj is a file record.

This is the minimum supported version of the ZIP standard required to extract the file. Currently vresion 2.0 is supported (which is encoded as the exact integer 20).

Various flags that can indiciate which compression option was used, etc. You can probably ignore these.

Returns an integer that represents the compression method that was used when storing the file associated with frec. Most ZIP files use only Deflate and store.

• compression-stored means the file was stored without any compression.
• compression-shrunk is the obsolete Shrunk method.
• compression-reduced1 is the obsolete Reduced method with factor 1.
• compression-reduced2 same as above, factor 2.
• compression-reduced3 same as above, factor 3.
• compression-reduced4 same as above, factor 4.
• compression-imploded is the obsolete Implode method.
• compression-deflated is the Deflate compression algorithm.
• compression-deflate64 is a slightly modified Deflate.
• compression-pkimplode is something else.
• compression-bzip2 is BZIP2.

The file's modification time as an SRFI-19 date.

The file's CRC-32 checksum. See crypto crc.

The number of bytes the file uses inside the ZIP archive.

The number of bytes the file will use when it has been decompressed.

The filename of the file. This might be different in the associated central directory record (e.g. due to mischief). This can also be the string "-" if the file came from the standard input port.

An list of id and data pairs. This is used to encode file attributes, etc. See the file format specification for more information.

True if obj is a central-directory record.

This is the version of the ZIP standard supported by the implementation that created the archive.

The ID number of the operating system on which the ZIP archive was created. See the file format specification for a full list (DOS is 0, Unix is 3).

This is the minimum supported version of the ZIP standard required to extract the file. Currently version 2.0 is supported (which is encoded as the exact integer 20).

See file-record-flags.

See file-record-compression-method.

The file's modification time as an SRFI-19 date.

The file's CRC-32 checksum. See crypto crc.

The number of bytes the file uses inside the ZIP archive.

The number of bytes the file will use when it has been decompressed.

The number of the split archive that the file starts on. Note that there is no explicit support for split archives, so this is untested.

Bit 0 of this integer is set if the file is believed to be text. This might be useful for end of line conversion, but it is probably unreliable.

The file attributes of the file. The format depends on the os-made-by field.

See file-record-filename.

See file-record-extra. Note that some of the fields have the same ID here and in the file records, but slightly different encodings.

A textual comment associated with the file.

True of obj is an end-of-central-directory record.

The number of the split archive where edir is located.

The number of the split archive where the central directory begins.

The number of records in the central directory in this split archive.

The number of records in the central directory for the whole archive.

A textual comment associated with the whole archive.

Returns a binary input port that decompresses and reads a ZLIB stream from the binary input port binary-input-port. The id is the name of the returned custom binary input port.

If max-buffer-size is false then the internal buffer can grow without bounds (might be a bad idea). Protocols using ZLIB will normally specify a "flush" behavior. If your protocol uses flushing and specifies a maximum record size, then use that size as max-buffer-size.

If close-underlying-port? is true then at the end of the zlib stream the binary-input-port will be closed.

An application can define dictionaries which can improve compression by containing byte sequences commonly found at the start of files. The dictionaries argument is an alist that maps Adler-32 checksums to bytevectors. See compression adler-32.

Expands the key into an AES key schedule suitable for aes-encrypt!. The key must be a bytevector of length 16, 24 or 32 bytes. The type of the return value is unspecified.

Takes the 16 bytes at source+source-start, encrypts them in Electronic Code Book (ECB) mode using the given key-schedule, and then writes the result at target+target-start. The source and the target can be the same.

          (import (weinholt crypto aes))
          (let ((buf (string->utf8 "A Scheme at work"))
                (sched (expand-aes-key (string->utf8 "super-secret-key"))))
            (aes-encrypt! buf 0 buf 0 sched)
            buf)
          ⇒ #vu8(116 7 242 187 114 235 130 138 166 39 24 204 117 224 5 8)

It is generally not a good idea to use ECB mode alone.

Reverses the key-schedule to make it suitable for aes-decrypt!.

Performs the inverse of aes-encrypt!. The key-schedule should first be reversed with reverse-aes-schedule.

          (import (weinholt crypto aes))
          (let ((buf (bytevector-copy #vu8(116 7 242 187 114 235 130 138
                                           166 39 24 204 117 224 5 8)))
                (sched (reverse-aes-schedule
                        (expand-aes-key
                         (string->utf8 "super-secret-key")))))
            (aes-decrypt! buf 0 buf 0 sched)
            (utf8->string buf))
          ⇒ "A Scheme at work"

Clears the AES key schedule so that it no longer contains cryptographic material. Please note that there is no guarantee that the key material will actually be gone from memory. It might remain in temporary numbers or other values.

Encrypts or decrypts the len bytes at source+source-start using Counter (CTR) mode and writes the result to target+target-start. The len does not need to be a block multiple. The ctr argument is a non-negative integer.

This procedure is its own inverse and the key-schedule should not be reversed for decryption.

Never encrypt more than once using the same key-schedule and ctr value. If you're not sure why that is a bad idea, you should read up on CTR mode.

Encrypts k bytes in the bytevector source starting at source-start with AES in CBC mode and writes the result to target at target-start.

The argument k must be an integer multiple of 16, which is the block length.

The iv bytevector is an Initial Vector. It should be 16 bytes long, initialized to random bytes. This procedure updates the iv after processing a block.

The inverse of aes-cbc-encrypt!.

Expands the bytevector key into an ARCFOUR keystream value. The return value has an unspecified type and is suitable for use with the other procedures exported by this library.

Never use the same key to encrypt two different plaintexts.

Reads k bytes from source starting at source-start, XORs them with bytes from the keystream, and writes them to target starting at target-start. If source and target are the same object then it is required that target-start be less then or equal to source-start.

          (import (weinholt crypto arcfour))
          (let ((buf #vu8(90 60 247 233 181 200 38 52 121 82 133
                          98 244 159 12 97 90 157 43 183 249 170
                          73 244 126))
                (keystream (expand-arcfour-key
                            (string->utf8 "hardly a secret"))))
            (arcfour-discard! keystream 3000)
            (arcfour! buf 0 buf 0 (bytevector-length buf) keystream)
            (clear-arcfour-keystream! keystream)
            (utf8->string buf))
          ⇒ "I AM POKEY THE PENGUIN!!!"

Discards n bytes from the keystream keystream. It is recommended that the beginning of the keystream is discarded. Some protocols, e.g. RFC 4345, require it.

Removes all key material from the keystream.

Expands a Blowfish key, which is a bytevector of length between 1 and 56 bytes (the longer the better). The returned key schedule can be used with blowfish-encrypt! or reverse-blowfish-schedule.

Encrypts the eight bytes at source+source-start using Electronic Code Book (ECB) mode. The result is written to target+target-start.

Reverses a Blowfish key schedule so that it can be used with blowfish-decrypt!.

The inverse of blowfish-encrypt!.

Clears the Blowfish key schedule so that it no longer contains cryptographic material. Please note that there is no guarantee that the key material will actually be gone from memory. It might remain in temporary numbers or other values.

Encrypts k bytes in the bytevector source starting at source-start with Blowfish in CBC mode and writes the result to target at target-start.

The argument k must be an integer multiple of 8, which is the block length.

The iv bytevector is an Initial Vector. It should be 8 bytes long, initialized to random bytes. This procedure updates the iv after processing a block.

The inverse of blowfish-cbc-encrypt!.

This is the simple interface that requires merely the name of the CRC algorithm. The pre-defined CRCs that can be used this way are currently: crc-32, crc-16, crc-16/ccitt, crc-32c, crc-24, crc-64 (CRC-64-ISO), and crc-64/ecma-182.

          (import (weinholt crypto crc))
          (define-crc crc-32)

For details on how the arguments work, and the theory behind them, see Ross N. Williams's paper A painless guide to CRC error detection algorithms, which is available at http://www.ross.net/crc/crcpaper.html. A brief description of the arguments follows.

The width is the bitwise length of the polynomial. You might be led to believe that it should sometimes be 33, but if so you've been counting the highest bit, which doesn't count.

The polynomial for CRC-16 is sometimes given as x^16 + x^15 + x^2 + 1. This translates to #b1000000000000101 (#x8005). Notice that x^16 is absent. Don't use the reversed polynomial if you have one of those, instead set ref-in and ref-out properly.

After a CRC has been calculated it is sometimes xor'd with a final value, this is xor-out.

check is either #f or the CRC of the string "123456789".

This is a slightly easier version of the advanced interface where you can simply specify the powers of the coefficients. CRC-16 in this syntax becomes:

          (import (weinholt crypto crc))
          (define-crc crc-16 (16 15 2 0) #x0000 #t #t #x0000 #xBB3D)
          ==>
          (begin
            (define (crc-16 bv)
              (crc-16-finish (crc-16-update (crc-16-init) bv)))
            (define (crc-16-init) #x0000)
            (define (crc-16-finish r) (bitwise-xor r #x0000))
            (define (crc-16-self-test)
              (if #xBB3D
                  (if (= (crc-16 (string->utf8 "123456789")) #xBB3D)
                      'success 'failure)
                  'no-self-test))
            ...)

Another example: the polynomial x^8 + x^2 + x + 1 in this syntax is (8 2 1 0).

Calculates the final CRC of the entire bytevector and returns it as an integer.

          (import (weinholt crypto crc))
          (define-crc crc-32)
          (crc-32 (string->utf8 "A fiendish scheme"))
          ⇒ 1384349758

Returns an initial CRC state.

Uses the state and returns a new state that includes the CRC of the given bytes.

          (import (weinholt crypto crc))
          (define-crc crc-32)
          (crc-32-finish
           (crc-32-update (crc-32-init)
                          (string->utf8 "A fiendish scheme")))
          ⇒ 1384349758

Finalizes the CRC state.

Returns the bit-width of the CRC, e.g. 32 for CRC-32.

Performs a sanity check and returns either success, failure or no-self-test.

Returns #f if the DES key has good parity, or the index of the first bad byte. Each byte of the key has one parity bit, so even though it is a bytevector of length eight (64 bits), only 56 bits are used for encryption and decryption. Parity is usually ignored.

The fundamental DES procedure, which performs both encryption and decryption in Electronic Code Book (ECB) mode. The eight bytes starting at offset in the bytevector bv are modified in-place.

The offset can be omitted, in which case 0 is used.

The E argument will normally be omitted. It is only used by the des-crypt procedure.

          (import (weinholt crypto des))
          (let ((buf (string->utf8 "security"))
                (sched (permute-key (string->utf8 "terrible"))))
            (des! buf sched)
            buf)
          ⇒ #vu8(106 72 113 111 248 178 225 208)

          (import (weinholt crypto des))
          (let ((buf (bytevector-copy #vu8(106 72 113 111 248 178 225 208)))
                (sched (reverse (permute-key (string->utf8 "terrible")))))
            (des! buf sched)
            (utf8->string buf))
          ⇒ "security"

Permutes the DES key into a key schedule. The key schedule is then used as an argument to des!. To decrypt, simply reverse the key schedule. The return value is a list.

Permutes a 3DES key into a key schedule. If only one argument is given then it must be a bytevector of length 24. If three arguments are given they must all be bytevectors of length eight.

The return value's type is unspecified.

Encrypts the eight bytes at offset of bv using the given 3DES key schedule.

The inverse of tdea-encipher!.

Encrypts the count bytes at offset of bv using Cipher Block Chaining (CBC) mode.

The iv argument is the Initial Vector, which is XOR'd with the data before encryption. It is a bytevector of length eight and it is modified for each block.

Both offset and count must be a multiples of eight.

The inverse of tdea-cbc-encipher!.

This is a password hashing algorithm that used to be very popular on Unix systems, but is today too fast (which means brute forcing passwords from hashes is fast). The password string is at most eight characters.

The algorithm is based on 25 rounds of a slightly modified DES.

The salt must be a string of two characters from the alphabet #\A–#\Z, #\a–#\z, #\0–#\9, #\. and #\/.

          (import (weinholt crypto des))
          (des-crypt "password" "4t")
          ⇒ "4tQSEW3lEnOio"

A more general interface is also available, see crypto password.

Generates a Diffie-Hellman secret key pair. Returns two values: the secret key (of bitwise length bit-length) part and the public key part.

Computes (mod (expt base exponent) modulus). This is modular exponentiation, so all the parameters must be integers.

The exponent can also be negative (set it to -1 to calculate the multiplicative inverse of base).

          (import (weinholt crypto dh))
          (let ((g modp-group15-g) (p modp-group15-p))
            (let-values (((y Y) (make-dh-secret g p 320))
                         ((x X) (make-dh-secret g p 320)))
              ;; The numbers being compared are the shared secret
              (= (expt-mod X y modp-group15-p)
                 (expt-mod Y x modp-group15-p))))
          ⇒ #t

Returns a DSA public key value. See the FIPS standard for a description of the parameters.

To access the fields use dsa-public-key-p, dsa-public-key-q, dsa-public-key-g and dsa-public-key-y.

True if obj is a DSA public key value.

Returns the number of bits in the p value of key. This is often considered to be the length of the key. The bitwise-length of q is also important, it corresponds with the length of the hashes used for signatures.

Returns a DSA private key value. See the FIPS standard for a description of the parameters.

To access the fields use dsa-private-key-p, dsa-private-key-q, dsa-private-key-g, dsa-private-key-y and dsa-private-key-x.

Returns #t if obj is a DSA private key.

Converts a private DSA key into a public DSA key by removing the private fields.

Parses bv as an ASN.1 DER encoded private DSA key.

Opens the file and reads a private DSA key. The file should be in Privacy Enhanced Mail (PEM) format and contain an ASN.1 DER encoded private DSA key.

Encrypted keys are currently not supported.

Parses the bytevector bv as an ASN.1 DER encoded DSA signature. The return value is a list with the r and s values that make up a DSA signature.

The hash is the message digest (as a bytevector) of the data you want to sign. The hash and the private-key are used to create a signature which is returned as two values: r and s.

The hash can e.g. be an SHA-1 message digest. Such a digest is 160 bits and the q parameter should then be 160 bits.

The hash is the message digest (as a bytevector) of the data which the signature is signing.

Returns #t if the signature matches, otherwise #f.

Constructs a new elliptic-curve object given the domain parameters of a curve:

y^2 \equiv x^3 + ax + b (mod p).

Normally one will be working with pre-defined curves, so this constructor can be safely ignored. The curve definition will include all these parameters.

Returns #t if obj is an elliptic prime curve.

This is one of the parameters that defines the curve: an element in the field.

This is one of the parameters that defines the curve: another element in the field.

This is one of the parameters that defines the curve: the base point, i.e. an actual point on the curve.

This is one of the parameters that defines the curve: a prime that is the order of G (the base point).

This is one of the parameters that defines the curve: the cofactor.

This is one of the parameters that defines the curve: the integer that defines the prime finite field.

Returns #t if the elliptic curve objects are equal (in the sense that all domain parameters are equal).

This adds the points P and Q, which must be points on elliptic-curve.

This subtracts Q from P, both of which must be points on elliptic-curve. If Q is omitted it returns the complement of P.

This multiplies P by multiplier. P must be a point on elliptic-curve and multiplier must be a non-negative integer.

This operation is the elliptic curve equivalence of expt-mod.

Converts bytevector to a point on elliptic-curve. When points are sent over the network or stored in files they are first converted to bytevectors.

Performs the same conversion as bytevector->elliptic-point, but first converts integer to a bytevector.

A generic procedure that accepts as input an x that is either already a point, a bytevector representing a point, or an integer representing a point.

Converts point to its bytevector representation. This representation is sometimes hashed, e.g. in SSH public keys, so the canonical representation is used for compatibility with other software.

Constructs an ECDSA public key object. Q is a point on elliptic-curve. Q is only checked to be on the curve if it is in bytevector format.

Returns #t if obj is an ECDSA public key object.

Returns the curve that ecdsa-public-key uses.

The point on the curve that defines ecdsa-public-key.

The bitwise length of the ECDSA public key ecdsa-public-key.

Constructs an ECDSA private key object. d is a secret multiplier, which gives a public point Q on elliptic-curve.

If Q is omitted it is recomputed based on d and the curve. If d is omitted a random multiplier is chosen. Please note the warning about entropy at the start of this section. See crypto.

Returns #t if obj is an ECDSA private key object.

The secret multiplier of ecdsa-private-key.

The public point of ecdsa-private-key.

Strips ecdsa-private-key of the secret multiplier and returns an ECDSA public key object.

Parses bytevector as an ECDSA private key encoded in RFC 5915 format. A curve identifier is encoded along with the key. Currently only the curves secp256r1, secp384r1 and secp521r1 are supported.

Returns #t if the signature (r,s) was made by the private key corresponding to ecdsa-public-key. The bytevector hash is the message digest that was signed.

Creates a signature of the bytevector hash using ecdsa-private-key. Returns the values r and s.

Performs the same function as make-ecdsa-public-key, but the returned key is marked to be used with SHA-2.

Returns #t if obj is an ECDSA public key marked to be used with SHA-2.

Performs the same function as make-ecdsa-private-key, but the returned key is marked to be used with SHA-2.

Returns #t if obj is an ECDSA private key marked to be used with SHA-2.

The bytevector message is hashed with the appropriate message digest algorithm (see RFC 5656) and the signature (r,s) is then verified. Returns #t if the signature was made with the private key corresponding to ecdsa-sha2-public-key.

The bytevector message is hashed with the appropriate message digest algorithm (see RFC 5656) and a signature is created using ecdsa-sha2-private-key. Returns the values r and s.

Performs the same function as ecdsa-private-key-from-bytevector, except the returned value is marked to be used with SHA-2.

Writes k random bytes to the bytevector target starting at index target-start.

Returns a bytevector of length k with random content.

          (import (weinholt crypto entropy))
          (make-random-bytevector 8)
          ⇒ #vu8(68 229 38 253 58 70 198 161)

The complete all-in-one procedure to calculate the MD5 message digest of all the given bytevectors in order. Returns an md5 state, which should be used with md5->bytevector or md5->string.

          (md5->string (md5 (string->utf8 "A Scheme in my pocket")))
          ⇒ "65A2B2D8EE076250EA0A105A8D5EF1BB"

The length of md5 message digests in bytes.

Returns a new MD5 state for use with the procedures below. The type of the return value is unspecified.

Updates the md5state to include the specified range of data from bv.

Finalizes the md5state. This must be used after the last call to md5-update!.

Clear the md5state so that it does not contain any part of the input data or the message digest.

Make a copy of the md5state.

Performs md5-finish! on a copy of md5state and then returns the new state.

Copies the message digest (a.k.a. hash) in the finalized md5state into bv at the given offset.

Like md5-copy-hash!, but only copies the leftmost 96 bits.

Returns a new bytevector which contains a binary representation of the finalized md5state.

Returns a new string which contains a textual representation of the finalized md5state. The conventional hexadecimal representation is used.

Compares the finalized md5state with the leading bytes of bv. The comparison is designed to take the same amount of time regardless of where any differences may be. This may be important for networked programs that would otherwise be vulnerable to timing attacks.

Like md5-hash=? except it only compares the leftmost 96 bits.

An HMAC is a Hash-based Message Authentication Code. This procedure uses MD5 to generate such a code. The return value is an MD5 state.

Returns false if the data at the beginning of port doesn't look like a valid binary OpenPGP packet. The port must be a binary input port. The port position is not changed.

Reads an OpenPGP packet from port, which must be a binary input port. An error is raised if the packet type is unimplemented.

Reads a keyring from the binary input port p. Returns a hashtable where all primary keys and subkeys are indexed by their key ID (an integer). The values in the hashtable are lists that contain all OpenPGP packets associated with each key. No effort at all is made to verify that keys have valid signatures.

Warning: this can take a while if the keyring is very big.

Searches the binary input port p for the public key with the given keyid. Returns a hashtable similar to get-openpgp-keyring, except it will only contain the primary and subkeys associated with the keyid.

The keyid can be either a 64 or 32 bit exact integer.

Warning: this is faster than get-openpgp-keyring, but is still rather slow with big keyrings. The speed depends on the SHA-1 implementation.

Reads a detached OpenPGP signature from the textual input port p. Returns either an OpenPGP signature object or the end of file object.

These signatures can be created with e.g. gpg -a --detach-sign filename.

Verifies the signature data in sig. The keyring hashtable is used to find the public key of the signature issuer. The signed data is read from the binary input port p.

This procedure returns two values. These are the possible combinations:

• good-signature key-data – The signature matches the data. The key-data contains the public key list that was used to verify the signature.
• bad-signature key-data – The signature does not match the data. The key-data is the same as above.
• missing-key key-id – The issuer public key for the signature was not found in the keyring. The key-id is the 64-bit key ID of the issuer.

True if obj is an OpenPGP signature object. Such objects are read with get-openpgp-detached-signature/ascii and are also contained in keyring entries.

The 64-bit key ID of the OpenPGP public key that issued the signature sig.

Returns the name of the public key algorithm used to create the signature sig. This is currently the symbol dsa or rsa.

The name of the message digest algorithm used to create the signature sig. This is currently one of md5, sha-1, ripe-md160 (unsupported), sha-224, sha-256, sha-384 or sha-512.

An SRFI-19 date object representing the time at which the signature sig was created.

An SRFI-19 date object representing the time at which the signature sig expires. Returns #f if there's no expiration time.

True if obj is an OpenPGP user id.

The string value of the user-id. This is often the name of the person who owns the key.

True if obj is an OpenPGP user attribute. Attributes are used to encode JPEG images. There's currently no way to access the image.

True if obj is an OpenPGP primary key or subkey.

True if obj is a subkey.

The DSA or RSA public key contained in the OpenPGP public key. The value returned has the same type as the (crypto weinholt dsa) or (crypto weinholt rsa).

The fingerprint of the OpenPGP public key as a bytevector. This is an SHA-1 digest based on the public key values.

Formats the bytevector bv, which was presumably created by openpgp-public-key-fingerprint, as a string in the format preferred for PGP public key fingerprints.

The 64-bit key ID of the OpenPGP public key.

Scrambles a password using the given salt. The salt can also be a hash. The returned hash will be prefixed by the salt.

A fresh random salt should be used when hashing a new password. The purpose of the salt is to make it infeasible to reverse the hash using lookup tables.

To verify that a password matches a hash, you can do something like (string=? hash (crypt password hash)).

          (import (weinholt crypto password))
          (crypt "test" "..")
          ⇒ "..9sjyf8zL76k"

          (crypt "test" "$1$RQ3YWMJd$")
          ⇒ "$1$RQ3YWMJd$oIomUD5DCxenAs2icezcn."

          (string=? "$1$ggKHY.Dz$fNBcmNFTa1BFGXoLsRDkS."
                    (crypt "test" "$1$ggKHY.Dz$fNBcmNFTa1BFGXoLsRDkS."))
          ⇒ #t

Returns an RSA public key object containing the modulus n and the public exponent e.

True if obj is a public RSA key.

Returns the modulus of key.

Returns the public exponent of key.

Parses bytevector as an ASN.1 DER encoded public RSA key. The return value can be used with the other procedures in this library.

Returns the number of bits in the modulus of key. This is also the maximum length of data that can be encrypted or decrypted with the key.

Returns the number of 8-bit bytes required to store the modulus of key.

Returns an RSA private key object with the given modulus n, public exponent e, and private exponent d.

The other parameters are used to improve the efficiency of rsa-encrypt. They are optional and will be computed if they are omitted.

True if obj is a private RSA key.

Returns the modulus of key.

Returns the public exponent of key. This exponent is used for encryption and signature verification.

Returns the private exponent of key. This exponent is used for decryption and signature creation.

These two procedures return the first and second prime factors (p,q) of the modulus (n=pq).

This should be equivalent to (mod d (- p 1)). It is used to speed up rsa-decrypt.

This should be equivalent to (mod d (- q 1)). It is used to speed up rsa-decrypt.

This should be equivalent to (expt-mod q -1 p). It is used to speed up rsa-decrypt.

Uses the modulus and public exponent of key to construct a public RSA key object.

Parses bytevector as an ASN.1 DER encoded private RSA key. The return value can be used with the other procedures in this library.

Opens the file and reads a private RSA key. The file should be in Privacy Enhanced Mail (PEM) format and contain an ASN.1 DER encoded private RSA key.

Encrypted keys are currently not supported.

Encrypts the plaintext integer using the key, which is either a public or private RSA key.

plaintext must be an exact integer that is less than the modulus of key.

Decrypts the ciphertext integer using the key, which must be a private RSA key.

ciphertext must be an exact integer that is less than the modulus of key.

          (import (weinholt crypto rsa))
          (let ((key (make-rsa-private-key 3233 17 2753)))
            (rsa-decrypt (rsa-encrypt 42 key) key))
          ⇒ 42

This performs the same function as rsa-decrypt, but it uses RSA blinding. It has been shown that the private key can be recovered by measuring the time it takes to run the RSA decryption function. Use RSA blinding to protect against these timing attacks.

For more technical information on the subject, see Paul C. Kocher's article Timing Attacks on Implementations of Diffie-Hellman, RSA, DSS, and Other Systems.

Pads and encrypts the plaintext bytevector using public-key, a public RSA key. The return value is an integer.

The plaintext can't be longer than the length of the key modulus, in bytes, minus 11.

The inverse of rsa-pkcs1-encrypt. Decrypts the ciphertext integer using private-key, a private RSA key. The padding is then checked for correctness and removed.

          (import (weinholt crypto rsa))
          (let ((key (make-rsa-private-key
                      288412728347463293650191476303670753583
                      65537
                      190905048380501971055612558936725496993)))
            (utf8->string
             (rsa-pkcs1-decrypt
              (rsa-pkcs1-encrypt (string->utf8 "Hello")
                                 (rsa-private->public key))
              key)))
          ⇒ "Hello"

Decrypts the signature (a bytevector) contained in the signature integer by using the public-key. The signature initially contains PKCS #1 padding, but this is removed.

This performs the same operation as rsa-pkcs1-decrypt-signature, except it then treats the decrypted signature as a DER encoded DigestInfo. The return value is a list containing a digest algorithm specifier and a digest.

Reads a public RSA/DSA/ECDSA key encoded in the SSH public key format from the binary input port p.

Converts the public RSA/DSA/ECDSA key to the SSH public key format.

Returns the SSH algorithm identifier of key. For RSA keys this is "ssh-rsa", for DSA keys it is "ssh-dss", and for ECDSA keys it is "ecdsa-sha2-[identifier]" where [identifier] identifies the curve.

The MD5 based fingerprint of the RSA/DSA/ECDSA key in the same format used by common SSH software and specified by RFC 4716.

The random art of the RSA/DSA/ECDSA key. This is a visual representation of the key can is easier for humans to distinguish than fingerprints. This is the same art that OpenSSH's VisualHostKey feature displays.

True if obj is an X.509 certificate.

Reads an X.509 certificate from the bytevector bv. The certificate is in the ASN.1 DER format customarily used for X.509 certificates. For certificates in PEM format, first read them with get-delimited-base64. See text base64.

Returns the public key contained in the certificate. The return value's type is either an RSA or a DSA public key. See crypto dsa. See crypto rsa.

Returns ok if the certificates in the path list form a valid certificate path. A valid certificate path begins with a trusted CA certificate and ends with an end entity's certificate. Each certificate in the chain signs the next certificate. This is intended to form a chain of trust from a certificate you already trust (the CA certificate) to a new certificate, the end entity's certificate.

Optionally a common-name string can be given. This is normally a good idea. If you've tried to connect to a service at the domain name example.com, you might like to know that the certificate it presents actually belongs to example.com. Both the common name and subjectAltName fields of the certificate are checked. Currently only tested with domain names.

An SRFI-19 time can also optionally be given, in which case it is used instead of the system's current time.

If the optional CA-cert argument is given it is a trusted certificate that will be used to validate the start of the path. If this argument is given then no other trusted certificates will be tried.

These SRFI-39 parameters can be used to provide the validate-certificate-path procedure with trusted Certificate Authority (CA) certificates, also known as root certificates. It is beyond the scope of this library collection to provide you with trusted certificates. Many operating systems have such collections, e.g. Debian's ca-certificates package. Technically, a CA certificate is a self-issued certificate with correctly set “basic constraints” and “key usage” attributes. The CA-path parameter should be the name (ending in the path separator character, if any) of a directory containing files named by OpenSSL's c_rehash program. The files contain PEM encoded CA certificates. The filenames are partially a hash which also can be retrieved from the name-hash value in the issuer/subject alists. Default: "/etc/ssl/certs/".

The CA-file parameter is not yet implemented. In the future this will be the name of a file which contains trusted certificates. Default: "/etc/ssl/certs/ca-certificates.crt".

The CA-procedure parameter is a procedure which takes a single argument: an issuer alist. If you have the requested certificate, return it. Otherwise return #f. For forward compatibility the procedure should accept any number of arguments. Default: (lambda (issuer . _) #f)

Returns the keyUsage extension data from certificate. If the extension is absent then the return value is #f. Otherwise it is a list in which the possible entries are: digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly, and decipherOnly. See RFC 5280 for an explanation of their meaning. If you are implementing a protocol where keyUsage is important, the specification will probably mention it.

Returns the To Be Signed (TBS) part of certificate as a DER encoded bytevector. Except for the certificate's signature, the whole certificate is contained in the TBS data.

Uses the public key of issuer-cert to decipher the signature on subject-cert.

When an invalid opcode is encountered an exception with the &invalid-opcode condition is raised. Use invalid-opcode? to guard against it.

Reads one instruction from the binary-input-port and returns it in symbolic form. For a description of the collector, see disassembler.

          (import (weinholt disassembler i8080))
          (get-instruction (open-bytevector-input-port
                            #vu8(#x22 #x01 #x01))
                           #f)
          ⇒ (shld (mem16+ 257))

Reads one instruction from the binary-input-port and returns it in symbolic form. For a description of the collector, see disassembler.

          (import (weinholt disassembler m68hc12))
          (get-instruction (open-bytevector-input-port
                            #vu8(#x18 #x01 #xAE #x00 #x00))
                           #f)
          ⇒ (movw (0) (pre- 2 sp))

Disassembles one instruction from the binary-input-port and returns it in symbolic form. The endianness specifies if instructions are read in big or little endianness. For a description of the collector, see disassembler.

          (import (weinholt disassembler mips))
          (get-instruction (open-bytevector-input-port
                            #vu8(#x10 #x40 #x00 #x02))
                           (endianness big)
                           #f)
          ⇒ (beq $v0 $zero ($pc 8))

Reads a single instruction from the given binary-input-port. The mode is one of 16, 32 or 64 (which roughly correspond to real, protected and long mode).

The collector is either #f or a procedure that takes a symbolic tag and a variable number of bytes. The tag is one of the symbols modr/m, sib, disp, immediate, /is4, prefix and opcode. The x86 instruction set uses variable length instructions (of up to 15 bytes) and the collector procedure can be used to find out the type of data each byte of an instruction contains.

The returned instructions have the same operand order as Intel's documentation uses, i.e. the left operand is the destination.

          (import (weinholt disassembler x86))
          (get-instruction (open-bytevector-input-port
                            #vu8(#x69 #x6c #x6c #x65 #x01 #x00 #x00 #x00))
                           64 #f)
          ⇒ (imul ebp (mem32+ rsp 101 (* rbp 2)) 1)

          (get-instruction (open-bytevector-input-port
                            #vu8(196 227 113 72 194 49))
                           64 (lambda x (display x) (newline)))
          -| (prefix 196 227 113)
          -| (opcode 72)
          -| (modr/m 194)
          -| (/is4 49)
          ⇒ (vpermiltd2ps xmm0 xmm1 xmm2 xmm3)

          (get-instruction (open-bytevector-input-port #vu8(#xEB #x20))
                           64 #f)
          ⇒ (jmp (+ rip 32))

This procedure splits an IRC message into three parts: prefix, command and a list of arguments. The command is either a symbol or a number. If the message does not have a prefix the remote-server argument will be used instead, because it is implied by the protocol.

          (import (weinholt net irc))
          (parse-message
           ":irc.example.net PONG irc.example.net :irc.example.net")
          ⇒ "irc.example.net"
          ⇒ PONG
          ⇒ ("irc.example.net" "irc.example.net")

          (parse-message
           ":user!ident@example.com PRIVMSG #test :this is a test")
          ⇒ "user!ident@example.com"
          ⇒ PRIVMSG
          ⇒ ("#test" "this is a test")

          (parse-message "PING irc.example.net" "irc.example.net")
          ⇒ "irc.example.net"
          ⇒ PING
          ⇒ ("irc.example.net")

          (parse-message "PING irc.example.net")
          ⇒ #f
          ⇒ PING
          ⇒ ("irc.example.net")

This procedure does the same thing parse-message does, except it works on bytevectors. This is useful because the IRC protocol does not have a standard character encoding. Different channels on IRC often use different encodings.

Formats and outputs an IRC message to the given port, which must be in binary mode.

The codec is a codec, meaning the value returned by e.g. utf-8-codec or latin-1-codec. The codec is used to transcode the parameters.

The prefix is the name of the server or client that originated the message. IRC clients should use #f as prefix when sending to a server.

The cmd is a symbol or string representing an IRC command, but it can also be an integer (which must be be between 000 and 999). Only servers send numerical commands.

The rest of the arguments are the parameters for the given command, which can be either numbers, strings or bytevectors. Only the last of the parameters may contain whitespace. The maximum number of parameters allowed by the protocol is 15. Each IRC protocol command takes a pre-defined number of parameters, so e.g. if cmd is PRIVMSG then you must only pass two parameters.

          (import (weinholt net irc))
          (utf8->string
           (call-with-bytevector-output-port
             (lambda (port)
               (format-message-raw port (utf-8-codec)
                                   "irc.example.net" 1 "luser"
                                   "Welcome to the IRC"))))
          ⇒ ":irc.example.net 001 luser :Welcome to the IRC\r\n"

          (utf8->string
           (call-with-bytevector-output-port
             (lambda (port)
               (format-message-raw port (utf-8-codec)
                                   #f 'NOTICE "#example"
                                   "Greetings!"))))
          ⇒ "NOTICE #example Greetings!\r\n"

This procedure works just like format-message-raw, except before writing the message it parses the formatted message and compares it with the input to make sure it is the same. This prevents some attacks against IRC bots.

          (import (weinholt net irc))
          (utf8->string
           (call-with-bytevector-output-port
             (lambda (port)
               (format-message-and-verify
                port (utf-8-codec) #f 'NOTICE
                "#scheme" "announcing the 2^32th irc library!"))))
          ⇒ "NOTICE #scheme :announcing the 2^32th irc library!\r\n"

This example shows what happens when a parameter contains a newline, which is a common attack against bots. The command after the newline would be sent to the server, and the bot would exit all channels. Instead an exception is raised:

          (utf8->string
           (call-with-bytevector-output-port
             (lambda (port)
               (format-message-and-verify
                port (utf-8-codec) #f 'NOTICE
                "#example" "Querent: the answer is \r\nJOIN 0"))))
          error--> &irc-format

This provides an alternative to format-message-and-verify which is useful if you're not concerned about data integrity, so to speak. It replaces all bad characters with space before transmitting.

          (utf8->string
           (call-with-bytevector-output-port
             (lambda (port)
               (format-message-with-whitewash
                port (utf-8-codec) #f 'NOTICE
                "#example" "Querent: the answer is \r\nJOIN 0"))))
          ⇒ "NOTICE #example :Querent: the answer is   JOIN 0\r\n"

Returns #t is obj is an &irc-parse condition. The message parsing procedures use this condition when they detect a malformed message.

Returns #t is obj is an &irc-format condition. The message formatting procedures use this condition when they are unable to format a message.

The prefix in an IRC message can either be a server name or an extended prefix which identifies a client. Extended prefixes look like nickname!user@host.

Splits an extended prefix into its parts and returns three values: nickname, user and host.

Returns the nickname part of an extended prefix.

Parses an ISUPPORT list. The return value is an alist.

See http://www.irc.org/tech_docs/005.html for more on ISUPPORT.

Returns an alist of default ISUPPORT values.

Compares str1 and str2 for equality. The comparison is case-insensitive and uses the specified mapping to compare characters. This procedure is useful for comparing nicknames.

The mapping should be one of rfc1459, ascii or strict-rfc1459. Servers indicate in the CASEMAPPING ISUPPORT parameter which mapping they use.

The first IRC servers used Swedish ASCII for nicknames, so the nicknames sm|rg}s and SM\RG]S are equivalent on some servers.

Upcases str using the given case mapping.

Downcases str using the given case mapping.

Returns #t if the str represents a CTCP message. This is currently the extent of this library's CTCP support. CTCP is used for sending files, opening direct connections between clients, checking client versions, asking for the time, pinging clients, doing “action” style messages, and some other stuff.

Returns #t if the pattern, which can contain wildcards, matches the input. Otherwise returns #f. Strings containing wildcards are called masks, and they are used in e.g. channel ban lists.

The pattern follows the syntax specified in section 2.5 of RFC2812. A #\* matches zero or more characters and #\? matches any single character. The comparison is case-insensitive. Wildcard characters can be escaped with #\\.

          (import (weinholt net irc))
          (irc-match? "a?c" "abc")
          ⇒ #t
          (irc-match? "a*c" "ac")
          ⇒ #t
          (irc-match? "a*c" "acb")
          ⇒ #f

Uses the ISUPPORT data in prefix and chanmodes to parse a MODE command for a channel. The target is not included in the mode-list. To keep track of changes to who is op'd and voice'd (and half-op'd) you can use this procedure together with the server's ISUPPORT PREFIX data.

          (parse-channel-mode (cdr (assq 'PREFIX (isupport-defaults)))
                              (cdr (assq 'CHANMODES (isupport-defaults)))
                              '("+o-o+e-e+l-l+km+-be"
                                "op" "deop" "ex" "unex"
                                "50" "key" "unban"))
          ⇒
          ((+ #\o "op")
           (- #\o "deop")
           (+ #\e "ex")
           (- #\e "unex")
           (+ #\l "50")
           (- #\l #f)
           (+ #\k "key")
           (+ #\m channel)
           (- #\b "unban")
           (? #\e channel))

Returns #f is the string is not a FiSH message.

Decrypts a FiSH message. The msg is the line that the remote client sent to you.

Encrypts the string msg with FiSH encryption. Returns a string containing the plaintext. There is no verification that the key was correct and the returned string might be garbage.

Returns #f is str is not a FiSH key-exchange initialization request.

Finishes the DH1080 key-exchange request contained in init-msg. Returns two values: the newly generated key and a response for the remote client. There is no protection against middleman attacks.

The str is expanded and can then be used with fish-decrypt-message and fish-encrypt-message.

Returns #t if str, which is a message from a remote party, contains an OTR message. If it is an OTR message you should look up the OTR state that corresponds to the remote party (possibly make a new state) and call otr-update!.

Creates an OTR state value given the private DSA key dsa-key and a maximum segment size mss. The state is used to keep track of session keys and incoming message fragments.

The dsa-key must have a 160-bit q-parameter because of details in the protocol and limitations of other implementations. A 1024-bit DSA key will work. See crypto dsa.

The maximum segment size mss is used to split long OTR messages into smaller parts when OTR is used over a protocol with a maximum message size, e.g. IRC.

If an instance-tag is specified it must be a 32-bit integer not less than #x100. If it is omitted or #f an instance tag will be randomly generated. OTR version 3 uses the instance tags to identify which OTR state messages belongs to. Be sure to read the documentation for otr-state-our-instance-tag. New for Industria 1.5.

If versions is not omitted it must be a list of acceptable OTR protocol versions. The default is (2 3). New for Industria 1.5.

Processes the str message, which came from the remote party, and updates the state. Use otr-empty-queue! to retrieve scheduled events.

This is used to send a message to the remote party. It encrypts and enqueues the msg bytevector and updates the state. Use otr-empty-queue! to retrieve the encrypted and formatted messages that should be sent to the remote party.

The msg must not contain a NUL (0) byte.

Initiate or respond to an authentication request. After calling this procedure you should use otr-empty-queue!, just like with otr-send-encrypted!.

The authentication protocol can be used to verify that both partyies know the secret bytevector. The secret is never revealed over the network and is not even transmitted in an encrypted form. The protocol used is the Socialist Millionaires' Protocol (SMP), which is based on a series of zero-knowledge proofs.

Returns and clears the event queue. The queue is a list of pairs where the symbol in the car of the pair determines its meaning. These are the possible types:

• (outgoing . line) – The cdr is a string that should be sent to the remote party.
• (encrypted . msg) – The cdr is a string that contains a decrypted message that was sent by the remote party.
• (unencrypted . msg) – The cdr is a string that was sent unencrypted by the remote party. This happens when a whitespace-tagged message is received.
• (session-established . whence) – A session has been established with the remote party. It is now safe to call otr-state-their-dsa-key, otr-state-secure-session-id, otr-send-encrypted! and otr-authenticate!. The cdr is the symbol from-there if the session was initiated by the remote party. Otherwise it is from-here.
• (session-finished . whom) – The session is now finished and no new messages can be sent over it. The cdr is either the symbol by-them or by-us. Note: there is currently no way to finish the session from the local side, so by-us is not used yet.
• (authentication . expecting-secret) – The remote party has started the authentication protocol and now expects you to call otr-authenticate!.
• (authentication . #t) – The authentication protocol has succeeded and both parties had the same secret.
• (authentication . #f) – The authentication protocol has failed. The secrets were not identical.
• (authentication . aborted-by-them) – The remote party has aborted the authentication protocol.
• (authentication . aborted-by-us) – The local party has encountered an error and therefore aborted the authentication protocol.
• (they-revealed . k) – The remote party revealed an old signing key. This is a normal part of the protocol and the key is sent unencrypted to ensure the deniability property. You might like to reveal the key somehow yourself in case you're tunneling OTR over an encrypted protocol.
• (we-revealed . k) – The local party has revealed an old signing key. Note: currently not used.
• (undecipherable-message . #f) – An encrypted message was received, but it was not possible to decrypt it. This might mean e.g. that the remote and local parties have different sessions or that a message was sent out of order.
• (remote-error . msg) – The remote party encountered a protocol error and sent a plaintext error message (probably in English).
• (local-error . con) – There was an exception raised during processing of a message. The cdr is the condition object.
• (symmetric-key-request . (protocol . data)) – The remote party has requested that the extra symmetric key be used to communicate in some out-of-band protocol. See otr-send-symmetric-key-request!. New for Industria 1.5.

For forward-compatibility you should ignore any pair with an unknown car. Most messages are quite safe to ignore if you don't want to handle them.

Returns the remote party's public DSA key. This should be used to verify the remote party's identity. If the SMP authentication protocol succeeds you can remember the hash of the key for the next session. The user could also verify the key's hash by cell phone telephone or something.

Returns the local party's private DSA key. This is useful when the user is on the phone with the remote party. First convert it to a public key with dsa-private->public and then hash it with otr-hash-public-key.

Hashes a public DSA key and formats it so that it can be shown to the OTR user.

Returns the secure session ID associated with the OTR state.

Formats a secure session ID in the format that is recommended when the ID should be shown to the OTR user.

The first part of the ID should be shown in bold if the session was initiated by the local party. Otherwise the second part should be bold.

The OTR protocol version used by the state. This is either the integer 2 or the integer 3. New for Industria 1.5.

Returns the current maximum segment size of the OTR state.

Sets int as the maximum segment size of the OTR state.

This sends a message to the remote party that requests that it uses the extra symmetric key for some out-of-band protocol.

The remote party may ignore this request if the OTR protocol version (as returned by otr-state-version) is not at least 3.

The protocol parameter is an unsigned 32-bit integer that indicates what the key should be used for. At the time this manual is written there are no defined uses. One might expect a list of uses to appear in the protocol documentation at http://www.cypherpunks.ca/otr/.

The data parameter is a bytevector containing protocol-dependent data.

This returns the extra symmetric key in the form of a 256-bit bytevector.

Constructs a string that may be sent to a remote party as a request to start an OTR session. New for Industria 1.5.

If whitespace? is true then a whitespace tag will be made. This tag may be appended to a normal message sent by the user. If the recipient's client supports OTR it may start a session, but if it does not support OTR then hopefully it will not show the whitespaces.

The versions argument specifies which OTR protocol versions should be present in the tag. This can either be a list of version numbers or the symbol all.

This returns the local instance tag. It is new for Industria 1.5.

It is intended for instance tags to be persistent across client restarts. If the local party crashes then the remote party may still have an OTR session established. If the local client were then to change its instance tag on restart it would not receive any messages from the remote party and would not send error messages. To the remote party it would look like they were being ignored.

This SRFI-39 parameter controls debug output. It is a bit field with three bits currently defined. Bit 0 enables general trace messages, bit 1 enables packet traces and bit 2 enables packet hexdumps.

Default: #b000

This SRFI-39 parameter controls where debug output is written to. It defaults to the error port that was current when the library top-level was run.

This SRFI-39 parameter is used when constructing the local identification string. It specifies which SSH protocol version number is supported.

Default: "2.0"

This SRFI-39 parameter is used when constructing the local identification string. It specifies the name and version of the client or server.

Default: "Industria_1"

This SRFI-39 parameter is used when constructing the local identification string. It is #f or optionally a string of comments. This field is sometimes used to identify a vendor.

Default: #f

This is a list of key exchange algorithm names in the order they are preferred.

Default: ("diffie-hellman-group-exchange-sha256" "diffie-hellman-group-exchange-sha1" "diffie-hellman-group14-sha1" "diffie-hellman-group1-sha1")

This is a list of host key algorithm names in the order they are preferred. The server may have more than one host key and this is used to decide between them.

Default: ("ecdsa-sha2-nistp256" "ecdsa-sha2-nistp384" "ecdsa-sha2-nistp521" "ssh-rsa" "ssh-dss")

This is a list of encryption algorithm names in the order they are preferred for communication from the client to the server.

Default: ("aes128-ctr" "aes192-ctr" "aes256-ctr" "aes128-cbc" "aes192-cbc" "aes256-cbc" "blowfish-cbc" "arcfour256" "arcfour128" "3des-cbc")

This is a list of encryption algorithm names in the order they are preferred for communication from the server to the client.

Default: ("aes128-ctr" "aes192-ctr" "aes256-ctr" "aes128-cbc" "aes192-cbc" "aes256-cbc" "blowfish-cbc" "arcfour256" "arcfour128" "3des-cbc")

This is a list of message authentication code algorithms in the order they are preferred for communication from the client to the server.

Default: ("hmac-md5" "hmac-sha1" "hmac-sha1-96" "hmac-md5-96")

This is a list of message authentication code algorithms in the order they are preferred for communication from the server to the client.

Default: ("hmac-md5" "hmac-sha1" "hmac-sha1-96" "hmac-md5-96")

This is a list of compression algorithms for packets transmitted from the client to the server.

Default: ("none")

This is a list of compression algorithms for packets transmitted from the server to the client.

Default: ("none")

This is currently not used.

Default: ()

This is currently not used.

Default: ()

Starts an SSH client connection over the two given ports, which should be connected to a server via TCP (or some other similar means).

If everything goes right an ssh-conn object is returned. The peer identification and kexinit fields are valid.

Starts an SSH server connection over the two given ports, which should be connected to a client via TCP (or some other similar means).

keys is a list of host keys. The currently supported key types are dsa-private-key and ecdsa-sha-2-private-key.

If everything goes right an ssh-conn object is returned. The peer identification and kexinit fields are valid.

This runs the negotiated key exchange algorithm on ssh-conn. After this is done the client will have received one of the server's public keys. The negotiated encryption and MAC algorithms will have been activated.

The identification string the peer sent. This is a string that contains the peer's protocol version, software version and optionally some comments.

This is the peer's key exchange initialization (kexinit) packet. It lists the peer's supported algorithms. See net ssh transport.

The server's public key. This has unspecified contents before the ssh-key-exchange procedure returns.

The session ID of ssh-conn. This has unspecified contents before the ssh-key-exchange procedure returns.

Returns a procedure that can be used to register parsers and formatters for SSH packet types. The returned procedure should be given as an argument to register-connection and register-userauth.

Sends a disconnect packet to the peer. The packet contains the message and the code. The connection is then closed and an error is raised.

The error code constants are defined elsewhere. See net ssh transport.

Sends the SSH packet pkt to the peer of ssh-conn.

Reads an SSH packet object from the peer of ssh-conn. The end-of-file object will be returned if the peer has closed the connection. The procedure blocks until a message has been received. Any messages of the type ignore are ignored.

Packet types must be registered before they can be received. Initially only the transport layer types are registered. If an unregistered type is received this procedure returns a list of two items: the symbol unimplemented and the unparsed contents of the packet. A packet of type unimplemented is sent to the peer.

Flushes the output port of ssh-conn, and then closes both the input and output ports.

Flushes any pending output on ssh-conn.

Constructs and returns a key exchange packet for use by the local side.

Returns #t if pkt should be given to process-key-exchange-packet for handling by the key exchange logic.

Initiates key re-exchange on ssh-conn. This requires the peer's key exchange packet peer-kex, and the local key exchange packet local-kex. The procedure returns before the key re-exchange is finished. Both sides of the algorithm will need to communicate to complete the exchange.

Updates the key exchange logic on ssh-conn with the contents of pkt. If the packet is a kexinit packet and ssh-conn is a server, then this will automatically initiate the key re-exchange algorithm.

The procedure may return the symbol finished to indicate that the key exchange algorithm has finished and the new algorithms are used for packets sent to the peer.

Note: This interface is currently balanced in favor of servers. More experience in using the library is needed to determine how to make the key re-exchange interface better for clients. Suggestions are welcome.

Registers the packet types for the connection protocol so that they may be received and sent. A registrar may be obtained from an ssh-conn object using ssh-conn-registrar.

Constructs a global request: a connection request not related to any channel. Some global requests contain additional fields. These requests are represented by the global-request/* packets.

Returns true if obj is a global-request? packet.

This field contains a string identifying the type of the request, e.g. "no-more-sessions@openssh.com".

This field is true if the sender expects a request-success or request-failure record in response.

Constructs a request that instructs the server to bind a TCP server port and forward connections to the client.

Returns true if obj is a global-request/tcpip-forward packet.

This field is a string that represents the address to which the server should bind the TCP server port. Some addresses are given special meaning:

""

The server should listen to all its addresses on all supported protocols (IPv4, IPV6, etc).

"0.0.0.0"

The server should listen to all its IPv4 addresses.

"::"

The server should listen to all its IPv6 addresses.

"localhost"

The server should listen to its loopback addresses on all supported protocols.

"127.0.0.1"

The server should listen to its IPv4 loopback address.

"::1"

The server should listen to its IPv6 loopback address.

This field is an integer representing the port number to which the server should bind the TCP server port. If the number is 0 and want-reply? is true, the server will pick a port number and send it to the client in a request-success packet (the port number can be recovered with (unpack "!L" (request-success-data response))).

Constructs a message that undoes the effect of a global-request/tcpip-forward request.

Returns true if obj is a global-request/cancel-tcpip-forward packet.

See global-request/tcpip-forward-address.

See global-request/tcpip-forward-port.

Constructs a packet which indicates that the previous global-request was successful.

Returns true if obj is a request-success packet.

This field contains a request-specific bytevector which is mostly empty.

Returns an object which indicates that a global request failed.

Returns true if obj is a request-failure packet.

Returns true if obj is a channel-open packet.

A string representing the type of the channel-open request, e.g. "session".

This is the ID for the sender side of the channel.

This is the window size of the channel. The window size is used for flow-control and it decreases when data is sent over the channel and increases when a channel-window-adjust packet is sent. Each side of a channel has a window size.

This is the maximum allowed packet size for data sent to a channel. It basically limits the size of channel-data and channel-extended-data packets.

Constructs a request to open a new channel which is then connected to a TCP port.

Returns true if obj is a channel-open/direct-tcpip packet.

This is the hostname or network address that the TCP connection should be connected to.

This is the port number that the TCP connection should be connected to.

This is the network address of the machine that made the request.

This is the port number on which the request was made. This is useful when a client implements forwarding of client-local TCP ports.

This request is used by the server to tell the client that a TCP connection has been requested to a port for which the client sent a global-request/tcpip-forward request.

Returns true if obj is a channel-open/forwarded-tcpip packet.

The address to which the TCP connection was made.

The port to which the TCP connection was made.

The remote address of the TCP connection.

The remote port of the TCP connection.

Construct a request to open a session channel. This type of channel is used for interactive logins, remote command execution, etc. After the channel has been established the client will send e.g. a channel-request/shell or a channel-request/exec request.

Returns true if obj is a channel-open/session packet.

Constructs a message that opens an X11 channel. This message can be sent after X11 forwarding has been requested.

Returns true if obj is a channel-open/x11 packet.

The network address that originated the X11 connection.

The network port that originated the X11 connection.

Returns true if obj is a channel-packet packet.

This field is an integer that identifies the ID of the channel that should receive the request.

Constructs a packet that represents a failure to open a channel. It is sent in response to a channel-open/* request.

Returns true if obj is a channel-open-failure packet.

SSH-OPEN-ADMINISTRATIVELY-PROHIBITED

SSH-OPEN-CONNECT-FAILED

SSH-OPEN-UNKNOWN-CHANNEL-TYPE

SSH-OPEN-RESOURCE-SHORTAGE

This field is a human-readable reason for why the channel could not be opened.

This field is most commonly unused and set to "".

Constructs a message that indicates a channel was successfully opened (identified by recipient). The party that sends this message will include its own channel ID (sender).

Returns true if obj is a channel-open-confirmation packet.

This field contains the sender's ID for this channel.

This is the sender's initial window size. Analogous to the initial window size in a channel-open/* request.

This is the sender's maximum packet size. Analogous to the maximum packet size in a channel-open/* request.

This constructs a packet that is used to increment the window size of channel recipient by amount octets. It tells the remote part that the channel may receive additional data. If the client has assigned to a channel a receive buffer of 4096 bytes and the server sends 4096 bytes, the server will not be able to successfully send more data until the client has processed some of the buffer. When there is more room in the buffer the client can send a message of this type.

Returns true if obj is a channel-window-adjust packet.

This field contains the number of bytes that will be added to the window size.

This constructs a request that sends data over a channel.

Returns true if obj is a channel-data packet.

This field contains a bytevector with data being sent over the channel.

This constructs a message that works just like channel-data, except it contains an additional type field (explained below).

Returns true if obj is a channel-extended-data packet.

Data sent by a channel-data packet will normally be sent to a port connected with standard output. A channel-extended-data field is used when the data destination is a different port.

SSH-EXTENDED-DATA-STDERR

This constant specifies that the destination is the standard error port.

This field contains a bytevector with the data sent over the channel, e.g. an error message printed on the standard error port.

This constructs a packet that signals the end-of-file condition on the channel identified by the recipient ID.

Returns true if obj is a channel-eof packet.

This constructs a message that is used when a channel is closed.

Returns true if obj is a channel-close packet.

This constructs a packet that indicates that the previous request was successful. These packets are sent in response to requests where want-reply? is true.

Returns true if obj is a channel-success packet.

This constructs a packet that indicates that the previous request was not successful. These packets are sent in response to requests where want-reply? is true.

Returns true if obj is a channel-failure packet.

Returns true if obj is a channel-request packet.

This field is a string that identifies the type of the request, e.g. "break" or "shell".

When this field is true the peer will respond with channel-success or channel-failure. This field is not valid for all requests. Where it is not valid the constructor will not include it as an argument.

This constructs a request that relays a “BREAK” signal on the channel. A “BREAK” is a signalling mechanism used with serial consoles. This request is standardized by RFC 4335.

Returns true if obj is a channel-request/break packet.

The length of the signal in milliseconds.

Constructs a request that can be used before a shell or command has been started. It is used to set an environment variable (of the same kind that SRFI-98 accesses).

Returns true if obj is a channel-request/env packet.

This is a string that identifies the name of the environment variable.

This is a bytevector that contains the value of the environment variable.

Constructs a request that instructs the server to execute a command. The channel identified by recipient will be connected to the standard input and output ports of the program started by the server.

Returns true if obj is a channel-request/exec packet.

This field is a bytevector that contains the command that the server should try to execute.

This constructs a packet which indicates that the program connected to the channel identified by recipient has exited due to an operating system signal.

Returns true if obj is a channel-request/exit-signal packet.

This is a string that identifies the signal by name. For posix systems it is one of the following: "ABRT", "ALRM", "FPE", "HUP", "ILL", "INT", "KILL", "PIPE", "QUIT", "SEGV", "TERM", "USR1", "USR2". Other signal names may be used by following the guidelines in section 6.10 of RFC 4254.

This field is true when the operating system saved a process image (“core dump”) when it sent the signal.

This may be a string that explains the signal.

This string may identify the language used in channel-request/exit-signal-message.

This constructs a packet which indicates that the program connected to the channel identified by recipient has exited voluntarily.

Returns true if obj is a channel-request/exit-status packet.

This is an integer that identifies the exit status of the program. It is the same kind of number used by the the Scheme procedure exit.

Constructs a request that instructs the server to allocate a pseudo-terminal (PTY) for the channel identified by recipient. A PTY is needed for interactive programs, such as shells and Emacs.

Returns true if obj is a channel-request/pty-req packet.

This is a string that identifies the type of terminal that this PTY will be connected to. If the terminal is compatible with the DEC VT100 the value would be "vt100". This value is also the environment variable TERM. The set of supported terminal types depends on the server. Typically the software running on an SSH server uses the “terminfo” database.

This field contains the number of columns the terminal supports, e.g. 80. The channel-request/window-change request can be used to update this value if the terminal supports resizing.

This field contains the number of rows the terminal supports, e.g. 24.

This field specifies the width of the terminal in pixels.

This field specifies the height of the terminal in pixels.

This is a bytevector that encodes POSIX terminal modes. Unlike the size of the terminal, it is not possible to change the modes after the PTY has been created. The client should emulate a terminal set to “raw” mode and send a correct list of terminal modes. The server will then cooperate to handle the rest. This means that, unlike with telnet, the client will generally not do local “canonical” terminal processing.

Decodes the modes from a channel-request/pty-req. The return value is an association list.

The inverse of bytevector->terminal-modes. All modes specified by RFC 4254 can be encoded.

          (import (weinholt net ssh connection))
          (terminal-modes->bytevector '((VINTR . 3) (VERASE . 127)))
          ⇒ #vu8(1 0 0 0 3 3 0 0 0 127 0)

Constructs a request that starts a login shell on the channel identified by recipient. Normally a PTY must first have been connected to the channel.

Returns true if obj is a channel-request/shell packet.

Construct a packet that sends a signal to the program connected to the channel identified by recipient.

Returns true if obj is a channel-request/signal packet.

This field contains a signal name of the same type as that used by channel-request/exit-signal.

Constructs a request that a subsystem should be connected to the channel identified by recipient.

Returns true if obj is a channel-request/subsystem packet.

This field identifies the subsystem being requested, e.g. "sftp".

Construct a message that tells the server that the terminal window associated with a channel has been resized. The channel should have a PTY (see channel-request/pty-req).

Returns true if obj is a channel-request/window-change packet.

Contains the new character cell width of the terminal window.

Contains the new character cell height of the terminal window.

Contains the new pixel width of the terminal window.

Contains the new pixel height of the terminal window.

Constructs an X11 (X Window System) forwarding request.

Returns true if obj is a channel-request/x11-req packet.

If this field is true when only one X11 connection should be forwarded.

This field identifies an X11 authentication protocol. The most common value is "MIT-MAGIC-COOKIE-1".

This is a “magic cookie” encoded as a hexadecimal string. It is used with "MIT-MAGIC-COOKIE-1". It is recommended by RFC 4254 that this cookie should be different from the actual cookie used by the X11 server. When receiving a channel-open/x11 request the cookie can be intercepted, verified and replaced with the real one.

An X11 display can have, in X jargon, multiple screens. Normally this field would be 0.

Constructs a message that tells the client when it can do local processing of terminal flow control (C-s and C-q).

Returns true if obj is a channel-request/xon-xoff packet.

This flag is true if the client is allowed to do local processing of terminal flow control. If the flag is false then flow control is done on the server.

Registers the packet types for the transport layer so that they may be received and sent. A registrar may be obtained using ssh-conn-registrar.

Constructs a packet that closes the SSH connection. After sending or receiving this message the connection should be closed with close-ssh. The ssh-error procedure may be more convenient than manually constructing and sending a disconnect packet.

Returns #t if obj is a disconnect packet.

This field is an integer that represents the cause of the disconnect. The reason could be one of these (exported) constants:

SSH-DISCONNECT-HOST-NOT-ALLOWED-TO-CONNECT

SSH-DISCONNECT-PROTOCOL-ERROR

SSH-DISCONNECT-KEY-EXCHANGE-FAILED

SSH-DISCONNECT-RESERVED

SSH-DISCONNECT-MAC-ERROR

SSH-DISCONNECT-COMPRESSION-ERROR

SSH-DISCONNECT-SERVICE-NOT-AVAILABLE

SSH-DISCONNECT-PROTOCOL-VERSION-NOT-SUPPORTED

SSH-DISCONNECT-HOST-KEY-NOT-VERIFIABLE

SSH-DISCONNECT-CONNECTION-LOST

SSH-DISCONNECT-BY-APPLICATION

SSH-DISCONNECT-TOO-MANY-CONNECTIONS

SSH-DISCONNECT-AUTH-CANCELLED-BY-USER

SSH-DISCONNECT-NO-MORE-AUTH-METHODS-AVAILABLE

SSH-DISCONNECT-ILLEGAL-USER-NAME

This is a human-readable explanation for the disconnect.

Most commonly unused, "".

Construct a new ignore packet using the bytevector data as the payload. These packets are ignored by receivers but can be used to make traffic analysis more difficult.

Returns #t if obj is an ignore packet.

This constructs a message that should be sent when a received packet type is not implemented.

Returns #t if obj is an unimplemented packet.

Each packet sent over an SSH connection is given an implicit sequence number. This field exactly identifies one SSH packet.

Constructs a debug packet. It contains a message that a client or server may optionally display to the user.

Returns #t if obj is a debug packet.

If this field is true then the message should be displayed.

This is a string containing the debugging message. If it is displayed to the user it should first be filtered.

Most commonly unused, "".

This constructs a service request packet. The first service requested is normally "ssh-userauth". See net ssh userauth.

Returns #t if obj is a service-request packet.

This is the name of the service being requested, e.g. "ssh-userauth".

Constructs a request which indicates that access to a requested service was granted.

Returns #t if obj is a service-accept packet.

This field contains the name of the service to which access was granted.

Constructs a kexinit packet, which is used as part of the key exchange algorithm. The arguments are explained below. You probably want to use build-kexinit-packet instead of this procedure.

Returns #t if obj is a kexinit packet.

This field is a random bytevector. It is used in the key exchange to make things more difficult for an attacker.

A list of the supported key exchange algorithms (mostly variations on Diffie-Hellman).

A list of the supported host key algorithms.

A list of the supported encryption algorithms for packets sent from the client to the server.

A list of the supported encryption algorithms for packets sent from the server to the client.

A list of the supported Message Authentication Code (MAC) algorithms for packets sent from the client to the server.

A list of the supported Message Authentication Code (MAC) algorithms for packets sent from the server to the client.

A list of the supported compression algorithms for packets sent from the client to the server. The algorithm "none" is currently the only implemented compression algorithm.

A list of the supported compression algorithms for packets sent from the server to the client. The algorithm "none" is currently the only implemented compression algorithm.

Normally never used. Set to the empty list.

Normally never used. Set to the empty list.

If this field is true then the server and client will try to cooperate in order to make the key exchange run faster over connections with high latency. This optimization only works when the server and client both prefer the same algorithms.

This field must be zero.

Constructs a new newkeys packet. This message is used as part of key exchange to notify the remote side that new encryption keys are being used.

Returns #t if obj is a newkeys packet.

Registers the packet types for the authentication protocol so that they may be received and sent. A registrar may be obtained using ssh-conn-registrar.

Registers the packet types for the password authentication protocol. This is a supplement to register-userauth.

Registers the packet types for the public key authentication protocol. This is a supplement to register-userauth.

Deregisters all authentication protocol packet types.

Constructs a new user authentication request. This particular procedure is only good for constructing requests that use the "none" method. When such a request is sent to the server it will respond with a list of available authentication methods. To make a proper request use one of the make-userauth-request/* procedures below. Those procedures automatically include the correct method in the request. The service is normally "ssh-connection". See net ssh connection.

Returns true if obj is a userauth-request packet. This includes userauth-request/password packets, and so on.

This returns the user name field of request.

This returns the service name field of request.

This returns the method name field of request. Examples include "none", "password" and "publickey".

Constructs a message that indicates to the client that the user authentication request was not successful.

Returns true if obj is a userauth-failure packet. These packets indicate the the client was denied access to the requested service. The credentials might be incorrect or the server might be requesting additional authentication requests (see below).

This returns a list of authentication methods that “can continue”, i.e. methods that might be successful given that correct credentials are provided.

This is a boolean that indicates partial success. The server might require multiple successful authentication requests (see RFC 4252).

Constructs a packet that indicates to the client that the user authentication was successful. The client can now use the requested service (e.g. the connection protocol). This message has no fields.

Returns true if obj is a userauth-success packet.

This constructs a textual message that the server can send to the client. The client software can then display it to the user. This happens before user authentication is attempted and often contains a warning about unauthorized accesss.

Returns true if obj is a userauth-banner packet.

This field is a message that the client can show to the user.

This field might indicate the language of the text in the banner, but is most commonly empty and not used.

Constructs a user authentication request. This is a normal attempt to login with a user name and password. There is an alternative protocol for these types of login requests: the "keyboard-interactive" method (support is planned).

Returns true if obj is a userauth-request/password packet.

Returns the password field for this user authentication request.

This constructs a password change request. Some servers might send this packet if e.g. they use a password expiry system.

Returns true if obj is a userauth-request/changereq packet.

This is the message to show the user when prompting for the new password.

This is the language used in the password change request prompt.

Constructs a request to authenticate the user and at the same time change the user's password. This message may be sent without having received a userauth-request/changereq packet. Please see section 8 of RFC 4252 for the meaning of the packet that the server will send in response to this packet.

Returns true if obj is a userauth-request/password-change packet.

This field contains the user's current password.

This field contains the user's new password.

Before performing a potentially expensive private key operation the client may ask the server if a specific key might be used to authenticate.

Returns true if obj is a userauth-request/public-key-query packet.

This field is automatically filled in by make-userauth-request/public-key-query to contain the public key algorithm name of the key contained in the query.

This field contains an SSH public key.

The server sends userauth-public-key-ok to indicate that the user may try to authenticate with the given key.

Returns true if obj is a userauth-public-key-ok packet.

This is a copy of the algorithm name contained in the userauth-request/public-key-query packet.

This is a copy of the public key contained in the userauth-request/public-key-query packet.

This procedure creates an unsigned request to authenticate with public key cryptography. The client may try to authenticate itself by sending a signed request to the server. The server will have a copy of the public key on file, e.g. stored in the user's authorized_keys file. By using the public key it can confirm that the client is possession of the corresponding private key. The packet returned by this procedure may be signed with sign-userauth-request/public-key.

Returns true if obj is a userauth-request/public-key packet.

This field indicates the public key algorithm name of the public key in the request. It is automatically filled in when the request is constructed.

This field contains an SSH public key object. See crypto ssh-public-key.

This generates a signed userauth-request/public-key packet. It needs an unsigned request, which may be created with make-userauth-request/public-key. The session-id can be recovered with ssh-conn-session-id. The private-key must be a private DSA or ECDSA key (support for RSA signing is planned). The signed request uses the SSH connection's session ID and can therefore not be used with any other connection.

Initiates a TCP connection to the given hostname and portname (both of which are strings).

Returns an input-port and an output-port. They are not guaranteed to be distinct.

Initiates a TCP connection to the given hostname and portname (which are strings) and negotiates a TLS connection. Can hang forever.

Pay no attention to the optional client-certificates argument. It is not yet implemented.

This procedure returns three values: a binary input port, a binary output port, and a TLS connection object. The last value comes from the not-yet-documented (weinholt net tls) library. It is intended to be used to access the server's certificate chain, which can be verified using the not-yet-documented (weinholt crypto x509) library.

Negotiates TLS on two already opened ports. Same return values as tls-connect. This procedure can be used for protocols where the communication at first is in plaintext and then switches over to encrypted (i.e. STARTTLS). Some such protocols are SMTP, LDAP and XMPP.

Returns as many values as there are fields in the fmt string. The values are fetched from the bytevector starting at the offset (by default 0). For example, if the format string is "C", this translates into a bytevector-u8-ref call.

          (import (weinholt struct pack))
          (unpack "!xd" (pack "!xd" 3.14))
          ⇒ 3.14

          (number->string (unpack "!L" #vu8(#x00 #xFB #x42 #xE3)) 16)
          ⇒ "FB42E3"

          (unpack "!2CS" #vu8(1 2 0 3))
          ⇒ 1
          ⇒ 2
          ⇒ 3

Returns a new bytevector containing the values encoded as per the fmt string.

          (pack "!CCS" 1 2 3)
          ⇒ #vu8(1 2 0 3)

          (pack "!CSC" 1 2 3)
          ⇒ #vu8(1 0 0 2 3)

          (pack "!SS" (question-qtype x) (question-qclass x))
          ==>
          (let ((bv (make-bytevector 4)))
            (pack! "!SS" bv 0 (question-qtype x) (question-qclass x))
            bv)
          ==>
          (let ((bv (make-bytevector 4)))
            (let ((bv bv) (off 0))
              (bytevector-u16-set! bv 0 (question-qtype x)
                                   (endianness big))
              (bytevector-u16-set! bv 2 (question-qclass x)
                                   (endianness big))
              (values))
            bv)

The same as pack, except it modifies the given bytevector and returns no values.

Reads (format-size fmt) bytes from the binary-input-port and unpacks them according to the format string. Returns the same values as unpack would.

          (get-unpack port "4xCCxCC7x")
          ==>
          (let ((bv (get-bytevector-n port 16))
                (off 0))
            (values (bytevector-u8-ref bv 4) (bytevector-u8-ref bv 5)
                    (bytevector-u8-ref bv 7) (bytevector-u8-ref bv 8)))

Returns how many bytes the fields in the format string would use if packed together, including any padding.

          (format-size "!xQ")
          ⇒ 16

          (format-size "!uxQ")
          ⇒ 9

Encodes the bytevector bv in Base64 encoding. Optionally a range of bytes can be specified with start and end.

If a maximum line length is required, set line-length to an integer multiple of four (the default is #f). To omit padding at the end of the data, set no-padding or a non-false value. The alphabet is a string of length 64 (by default base64-alphabet).

The port is either a textual output port or #f, in which case this procedure returns a string.

Decodes the Base64 data in str. The string has to contain pure Base64 data, including padding, and no whitespace or other extra characters. The output is written to the binary output port. Returns a bytevector if port is #f.

Write the Base64 encoding of bv to the port. The output is delimited by BEGIN/END lines that include the type.

          (import (weinholt text base64))
          (put-delimited-base64 (current-output-port) "EXAMPLE"
                                (string->utf8 "POKEY THE PENGUIN"))
          -| -----BEGIN EXAMPLE-----
          -| UE9LRVkgVEhFIFBFTkdVSU4=
          -| -----END EXAMPLE-----

Reads a delimited Base64 encoded bytevector and returns two values: type (a string) and data (a bytevector). The data value is the end-of-file object if port-eof? would return #t.

Note: This procedure ignores MIME headers. Some delimited Base64 formats have headers on the line after BEGIN, followed by an empty line.

Note: This procedure ignores the Radix-64 checksum. The Radix-64 format (RFC 4880) is based on Base64, but appends a CRC-24 (prefixed by #\=) at the end of the data.

The rationale for ignoring headers and checksums is that it follows the Principle of Robustness: “Be conservative in what you send; be liberal in what you accept from others.” Lines before the BEGIN line are also ignored, because some applications (like OpenSSL) like to prepend a human readable version of the data.

You should probably use special parsers if you are reading data with headers or checksums. For some applications, e.g. MIME, you might need a Base64 decoder that also ignores characters outside the alphabet.

          (get-delimited-base64
           (open-string-input-port
            "-----BEGIN EXAMPLE-----\n\
          AAECAwQFBg==\n\
          -----END EXAMPLE-----\n"))
          ⇒ "EXAMPLE"
          ⇒ #vu8(0 1 2 3 4 5 6)

The alphabet used by the standard Base64 encoding. The alphabet is #\A–#\Z, #\a–#\z, #\0–#\9, #\+, #\/.

The alphabet used by the base64url encoding. The alphabet is #\A–#\Z, #\a–#\z, #\0–#\9, #\-, #\_.

The IPv4 address in bytevector is converted to the canonical string representation.

The textually represented IPv4 address in string is converted to its bytevector representation.

If the string does not represent an IPv4 address, #f is returned.

Note that this only handles the normal dotted-decimal notation. Some libraries, e.g. the standard C library, provide a function that parses addresses in octal, hex, and even handles some octets being missing. This library does none of that. Up to two leading zeroes may be used, though:

          (import (weinholt text internet))
          (ipv4->string (string->ipv4 "192.000.002.000"))
          ⇒ "192.0.2.0"

The IPv6 address in bytevector is converted to the string representation recommended by RFC 5952.

          (ipv6->string (string->ipv6 "2001:db8:0:0:0:0:0:1"))
          ⇒ "2001:db8::1"

The textually represented IPv6 address in string is converted to its bytevector representation. The input may be in any valid format.

If the string does not represent an IPv6 address, #f is returned.

          (string->ipv6 "2001:db8:0:0:0:0:1")
          ⇒ #f

          (string->ipv6 "2001:db8::1")
          ⇒ #vu8(32 1 13 184 0 0 0 0 0 0 0 0 0 0 0 1)

Appends the given bytevectors.

list is a list of bytevectors. The bytevectors are appended.

Analogous to substring. Returns a new bytevector containing the bytes of bytevector from index start to end (exclusive).

Searches bytevector for byte, from left to right. The optional arguments start and end give the range to search. By default the whole bytevector is searched. Returns #f is no match is found.

Analogous to bytevector-u8-index-right, except this procedure searches right-to-left.

bytevector is interpreted as an unsigned integer in big endian byte order and is converted to an integer. The empty bytevector is treated as zero.

integer is converted to an unsigned integer in big endian byte order. The returned bytevector has the minimum possible length. Zero is converted to the empty bytevector.

          (import (weinholt bytevectors))
          (uint->bytevector 256)
          ⇒ #vu8(1 0)
          (uint->bytevector 255)
          ⇒ #vu8(255)

True if bytevector1 and bytevector2 are of equal length and have the same contents.

This is a drop-in replacement for bytevector=? that does not leak information about the outcome of the comparison by how much time the comparison takes to perform. It works by accumulating the differences between the bytevectors. This kind of operation is most often needed when comparing fixed-length message digests, so the length comparison is done in the obvious (fast) way.