Zqlu is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install zqlu

It will make the zqlu command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall zqlu uninstalls.

Adding `zqlu` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add zqlu

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

zqlu = "0.3.0"

The zqlu library will be automatically available globally. Read the zqlu library documentation.

Back to the crate overview.

Readme

zqlu

zqlu is a text-based format for public keys designed to be efficient and convenient. A key looks something like this: zq.luAAhI0TjjRFd5K5vfy4hig23m7bppmotzOLVIkwFnPMfVWDp

Public key cryptography algorithms based on elliptic curves have many advantages, one of them being small key sizes. However, that benefit is not fully taken advantage of using common key encoding methods such as OpenSSH or PEM.

Features

Compact representation
Using only copy-and-paste friendly characters
Relatively easy to visually confirm the format of a key
A checksum is added, so a corrupted key can be detected

Credits and prior art

The design of zqlu was influenced by the nkey format. Thank you for the inspiration!

Naming

I picked zqlu because I had the idea to use a very short domain name for the magic value at the beginning of each key. It would be unique, and if you encounter a key somewhere without context, you can use the first five bytes as a web address and get more information about the format. It turned out that zq.lu was available for registration, so that determined the name.

Format

zqlu is a text-based format that encodes keys into the upper and lower case alphanumeric characters, numbers 0 through 9, and the period character "." as defined in the Basic Latin chart in the Unicode standard.

Each key consists of three parts:

The identifier string zq.lu
The key type character
The binary key data in a key-specific encoding, concatenated with a crc16 checksum and encoded with Base62

Every key starts with the string zq.lu identifying the format.

The next character holds information about the type of key, or "Key Algorithm" in using the terminology of the ssh specifications. The table below maps keys to their equivalent SSH key.

A   ssh-ed25519
B   ssh-rsa, 2048-bit modulus with exponent 65537
C   ecdsa-sha2-nistp256 with odd y value
D   ecdsa-sha2-nistp256 with even y value
E   ecdsa-sha2-nistp384 with odd y value
F   ecdsa-sha2-nistp384 with even y value
G   ecdsa-sha2-nistp521 with odd y value
H   ecdsa-sha2-nistp521 with even y value
I   ssh-rsa, 3072-bit modulus with exponent 65537
J   ssh-rsa, 4096-bit modulus with exponent 65537
K   ssh-rsa, exotic parameters
L-W reserved for future use
X   extended header
Y-Z reserved for future use

The different variations belonging to the ECDSA family of keys map to two different compressed y values as described in the elliptic curve point compression scheme in SEC 1 Section 2.3.3.

The RSA key types B, I, and J are compact encodings for common RSA public keys using the Fermat F4 public exponent 65537, or 2**16 + 1. Their key data is the unsigned big-endian modulus encoded in exactly 256, 384, or 512 octets, respectively. The fixed-length modulus MUST match the modulus size implied by the key type character.

The RSA key type K is reserved for RSA public keys that do not fit the compact B, I, or J profiles. Its key data is a sequence of two length-value fields: the public exponent followed by the modulus. Each value is encoded as an unsigned big-endian integer using the minimum number of octets needed to represent it, with no leading zero octets. Each length is encoded as an unsigned base-128 variable-length integer: the low seven bits of each octet carry data, the high bit is set when another length octet follows, and the least significant seven-bit group is encoded first. This is the same integer representation used by Protocol Buffers varints.

The extended header value is a mechanism for future extensibility, where the value X indicates that an extended header to be defined at a later date is prepended to the key data.

Checksum

The crd16 checksum is calculated over the first 6 characters of the key converted to bytes using the US-ASCII character set, followed by the key bits. Once calculated, the checksum is appended to the key data in network byte order. The specific algorithm we use is CRC-16/IBM-STLC as specified in RFC 1662, so the string 123456789 should produce the value 0x906e

Please note that this checksum algorithm will work the same even for future versions of this format.

Base62 encoding

The alphabet used for base62 encoding the binary key data uses an alphabet containing the numbers 0-9 followed by the upper case letters A-Z and lower case letters a-z.

When encoding binary data as Base62, the key data plus checksum is treated as a big-endian integer. This means that leading zero bytes would normally be lost. To preserve them, each leading zero byte is encoded as a leading 0 character in the Base62 output, followed by the Base62 encoding of the remaining bytes.

This follows the same general approach as the Base58 encoding draft, which preserves leading zero bytes using a dedicated leading character. In Base58 that character is 1, because 1 is the zero-valued digit in the Bitcoin Base58 alphabet. In zqlu Base62, the corresponding character is 0, because the alphabet begins with 0.

White space

ASCII whitespace and newline characters are ignored in the key, which means that a key can be stored in a multiline string, or even indented to match some formatting if put in for example a YAML file.

Rust usage

If you already parse SSH public keys with ssh_key::PublicKey::from_openssh(), the smallest change is to switch those call sites to zqlu::parse():

let public_key = zqlu::parse(input)?;

This returns ssh_key::PublicKey and accepts standard OpenSSH public key text, a zqlu key, or a PEM/SPKI public key such as what OpenSSL emits from openssl ec -pubout or openssl pkey -pubout.

License

This project is licensed under either of:

MIT
Apache-2.0

at your option.

Installing the command-line executable

Adding zqlu library as a dependency

Adding `zqlu` library as a dependency