Crypt4GH Key Format

This utility supports OpenSSH key-format (version 6.5 or above) if the key was generated with type ed25519 (i.e. with ssh-keygen -t ed25519 ...). Otherwise, this utility can generate keys in the following format:

Keys

A key is stored in the following PEM format:

-----BEGIN CRYPT4GH <type> KEY-----
BASE64-ENCODED DATA
-----END CRYPT4GH <type> KEY-----

where <type> is either PUBLIC or PRIVATE.

Public key data

For a public key, the key data is the byte representation of the plaintext key material.

Private key data

For a private key, we use the following encoding format.

byte[]  MAGIC_WORD
string  kdfname
string  (rounds || salt)     # included if kdfname is not "none"
string  ciphername
string  private blob         # Key material encrypted or not
string  comment              # Optional

  1. The MAGIC_WORD is the byte-representation of the ASCII word "c4gh-v1".

    Everything string consists of a length n (encoded as 2 big-endian bytes) and a sequence of n bytes (i.e. the string "hello", is encoded as \x00\x05hello).

  2. The kdfname is the name of the Key Derivation Function. We support either "scrypt", "pbkdf2_hmac_sha256", "bcrypt", or "none". The Rust implementation uses scrypt when available, and defaults to bcrypt for generating keys.

  3. The rounds is a 4 big-endian bytes representation of the number of iterations used in the KDF.

  4. The ciphername describes which symmetric algorithm is used to generate the encrypted data, as follows. The only supported cipher is "chacha20_poly1305" (so far), or "none".

    When kdfname is none, so should the ciphername be (and vice-versa), and the (rounds || salt) string is not included. This is used when the key material is not encrypted.

  5. In case the key material is encrypted, the KDF is used to derive a secret from a user-supplied passphrase. A nonce is randomly generated, and used in conjunction with the secret to encrypt the private key, using Chacha20 and authenticated with Poly1305. The nonce is prepended to the encrypted data.

  6. Finally, an optional comment can be used at the end of the encoded format.

Examples

Crypt4GH Key generation

crypt4gh keygen --sk user.sec --pk user.pub

OpenSSH Key generation

ssh-keygen -t ed25519 -f <output_filepath> -N <passphrase>