Monocypher

Boring crypto that simply works

Incremental public Key Signatures

Incremental public key signatures with EdDSA.

Synopsis

#include <monocypher.h>

void crypto_sign_init_first_pass(crypto_sign_ctx *ctx,
                                 const uint8_t    secret_key[32],
                                 const uint8_t    public_key[32]);

void crypto_sign_update(crypto_sign_ctx *ctx,
                        const uint8_t   *message,
                        size_t           message_size);

void crypto_sign_final(crypto_sign_ctx *ctx,
                       uint8_t          signature[64]);

void crypto_sign_init_second_pass(crypto_sign_ctx *ctx);

void crypto_check_init(crypto_check_ctx *ctx,
                       const uint8_t     signature[64],
                       const uint8_t     public_key[32]);

void crypto_check_update(crypto_check_ctx *ctx,
                         const uint8_t    *message,
                         size_t            message_size);

int crypto_check_final(crypto_check_ctx *ctx);

Description

These functions are variants of crypto_sign() and crypto_check(). Prefer those simpler functions if possible.

The arguments are the same as those described in crypto_sign().

This incremental interface can be used to sign or verify messages too large to fit in a single buffer. The arguments are the same as the direct interface described in crypto_sign() .

The direct and incremental interface produce and accept the same signatures.

Signing is done in two passes. This requires five steps:

Verification requires three steps:

Return values

crypto_sign_init_first_pass(), crypto_sign_init_second_pass(), crypto_sign_update(), crypto_sign_final(), crypto_check_init() and crypto_check_update() return nothing.

crypto_check_final() returns 0 for legitimate messages and -1 for forgeries.

Examples

Sign a message:

const uint8_t sk       [ 32]; /* Secret key            */
const uint8_t pk       [ 32]; /* Public key (optional) */
const uint8_t message  [500]; /* Message to sign       */
uint8_t       signature[ 64]; /* Output signature      */
crypto_sign_ctx ctx;
crypto_sign_init_first_pass(&ctx, sk, pk);
/* Wipe the secret key if no longer needed */
crypto_wipe(sk, 32);
for (size_t i = 0; i < 500; i += 100) {
    crypto_sign_update(&ctx, message + i, 100);
}
crypto_sign_init_second_pass(&ctx);
for (size_t i = 0; i < 500; i += 100) {
    crypto_sign_update(&ctx, message + i, 100);
}
crypto_sign_final(&ctx, signature);

Check the above:

const uint8_t pk       [ 32]; /* Public key         */
const uint8_t message  [500]; /* Message to sign    */
const uint8_t signature[ 64]; /* Signature to check */
crypto_check_ctx ctx;
crypto_check_init(&ctx, signature, pk);
for (size_t i = 0; i < 500; i += 100) {
    crypto_check_update(&ctx, message + i, 100);
}
if (crypto_check_final(&ctx)) {
    /* Message is corrupted, abort processing */
} else {
    /* Message is genuine */
}

Standards

These functions implement EdDSA with Curve25519 and Blake2b. This is the same as Ed25519, with Blake2b instead of SHA-512. Ed25519 is described in RFC 7748.

Security considerations

Messages are not verified until the call to crypto_check_final(). Messages may be stored before they are verified, but they cannot be trusted. Processing untrusted messages increases the attack surface of the system. Doing so securely is hard. Do not process messages before calling crypto_check_final().

When signing messages, the security considerations documented in public key signatures also apply.

Implementation details

EdDSA signatures require two passes that cannot be performed in parallel. There are ways around this limitation, but they all lower security in some way. For this reason, Monocypher does not support them.