Home

Awesome

asignify

Yet another signify tool

Introduction

Asignify is heavily inspired by signify, used in OpenBSD. However, the main goal of this project is to define a high-level API for signing files, validating signatures and encrypting files using public key cryptography. Asignify is designed to be portable and self-contained with zero external dependencies. It uses blake2b as the hash function and the ed25519 implementation from tweetnacl.

Asignify can verify OpenBSD signatures (but it cannot sign messages in OpenBSD format yet).

Key Features

Intel(R) Core(TM)2 Quad CPU    Q6600  @ 2.40GHz (-O3)

asignify encrypt sec1 sec2.pub test   7,66s user 2,48s system 88% cpu 11,482 total
gpg --encrypt --sign -r bob@example.com test   20,61s user 0,51s system 99% cpu 21,197 total

Usage Examples

Here are some (descriptive) usage examples of the asignify utility:

$ asignify help
$ asignify help <command>

$ asignify generate privkey
$ asignify generate --no-password privkey pubkey

$ asignify generate -s sshkey privkey
$ asignify generate --no-password -s sshkey privkey

$ asignify sign secretkey digests.sig file1 file2 ...

$ asignify verify publickey digests.sig

$ asignify check publickey digests.sig file1 file2 ...

$ asignify check sshpubkey digests.sig file1 file2 ...

$ asignify encrypt ownprivkey peerpubkey in out

$ asignify decrypt peerprivkey ownpubkey in out
$ asignify encrypt -d peerprivkey ownpubkey in out

Cryptographic Basis

Asignify relies on the same primitives as the signify utility. However, for the native format, asignify uses the blake2 cryptographic hash function instead of sha512. I decided this mainly because of the performance of blake2. Since this function was in the final of SHA3 competition (along with the current keccak winner), I believe that it is secure enough for use as a collision-resistant hash function. Moreover, unlike sha2, blake2 is not vulnerable to extension attacks.

For digital signatures, asignify uses the ed25519 algorithm which is blazingly fast and proven to be secure even without a random oracle (based on Schnorr scheme). The tweetnacl library is very small and precisely analyzed.

To sign a file, asignify does the following steps:

  1. Calculates the digest of a file (e.g. blake2 or sha512)
  2. Opens the secret key file (decrypting it if needed)
  3. Write all the digests to the output buffer in format:
SHA256 (filename) = deadbeef....
SIZE (filename) = 666
...
  1. Calculates the ed25519 signature over using secret key and the following fields:
    • version
    • data
  2. Afterwards, a signature is packed into the asignify signature line and prepended to the digests content

To verify a signature, asignify loads the public key, verifies the signature in the same way, loads the files' digest(s) and verifies the corresponding files agains those digests.

Hence, asignify only signs digests of files and not files themselves, and a signature contains both digests and its ed25519 signature.

Key Storage

The secret key for asignify can be encrypted using a password-based key derivation function, namely pbkdf2-blake2. This function can be tuned for the number of rounds to increase amount of work required for an adversary to brute force the encryption password into a valid encryption key.

Currently, asignify uses the following fields for private keys:

asignify-private-key
version: 1
data: <hex_blob|64 bytes>
id: <hex_blob|64 bytes>
kdf: pbkdf2-blake2
rounds: 42000
salt: <hex_blob|16 bytes>
checksum: <hex_blob|64 bytes>

The checksum is used to validate the password against the original encryption key. The current minimum rounds count is 10000. However, it can be changed in future.

Public keys and signatures have nearly the same format:

magic:version:<b64_key_id>:<b64_key_data>
asignify-pubkey:1:kEjp3MrX5fE=:Hut...bl/mQ=
asignify-sig:1:kEjp3MrX5fE=:Sfg...A==

The key ID is used to match keypairs and the corresponding signatures.

Libasignify API

libasignify provides a high-level API for the most common signature operations.

To verify a signature, you should do the following:

/* Init context */
vrf = asignify_verify_init();

/* Load pubkey */
if (!asignify_verify_load_pubkey(vrf, pubkeyfile)) {
	errx(1, "cannot load pubkey %s: %s", pubkeyfile,
		asignify_verify_get_error(vrf));
}

/* Load and verify digests file */
if (!asignify_verify_load_signature(vrf, sigfile)) {
	errx(1, "cannot load signature %s: %s", sigfile,
		asignify_verify_get_error(vrf));
}

/* Verify files with digests */
for (i = 0; i < argc; i ++) {
	if (!asignify_verify_file(vrf, argv[i])) {
		errx(1, "cannot verify file %s: %s", argv[i],
			asignify_verify_get_error(vrf));
	}
}

/* Cleanup */
asignify_verify_free(vrf);

To sign files, you should provide a callback for the password prompt (e.g. by BSD function readpassphrase):

static int
read_password(char *buf, size_t len, void *d)
{
	char password[512];
	int l;

	if (readpassphrase("Password:", password, sizeof(password), 0) != NULL) {
		l = strlen(password);
		memcpy(buf, password, l);
		
		/* Securely clean password data */
		explicit_memzero(password, sizeof(password));

		return (l);
	}

	return (-1);
}

If you want to use unencrypted private keys, then just pass NULL as a password callback when trying to open a secret key file.

Afterwards, signing is not so hard:


/* Init sign context */
sgn = asignify_sign_init();

/* Load encrypted private key with the provided password callback */
if (!asignify_sign_load_privkey(sgn, seckeyfile, read_password, NULL)) {
	errx(1, "cannot load private key %s: %s", seckeyfile,
		asignify_sign_get_error(sgn));
}

/* Add files digests */
for (i = 0; i < argc; i ++) {
	if (!asignify_sign_add_file(sgn, argv[i], ASIGNIFY_DIGEST_BLAKE2)) {
		errx(1, "cannot sign file %s: %s", argv[i],
			asignify_sign_get_error(sgn));
	}
}

/* Sign digests and write everything to a file */
if (!asignify_sign_write_signature(sgn, sigfile)) {
	errx(1, "cannot write sign file %s: %s", sigfile,
		asignify_sign_get_error(sgn));
}

/* Cleanup */
asignify_sign_free(sgn);

Generation of keypairs is served by libasignify as well:

if (!asignify_generate(seckeyfile, pubkeyfile, 1, rounds,
		read_password_verify, NULL)) {
	errx(1, "Cannot generate keypair");
}

Specifying NULL as a password callback leads to unencrypted secret keys being produced.

Supported Digest Formats

For sha2, libasignify can use openssl if it is available in the system since it provides highly optimized versions of SHA that calculates checksums much quicker than the sha2 code embedded into libasignify.

OpenBSD Signatures

libasignify automatically recognises and parses OpenBSD signatures and public keys, allowing verification of signatures produced by the signify utility transparently. Secret keys and signing are currently unsupported, however support is planned in the future.

Roadmap

License and Authors

This code is licensed under simplified BSD license and includes portions of third party code designed and written by various authors: