Crypto Functions

int wally_scrypt(const unsigned char *pass, size_t pass_len, const unsigned char *salt, size_t salt_len, uint32_t cost, uint32_t block_size, uint32_t parallelism, unsigned char *bytes_out, size_t len)

Derive a pseudorandom key from inputs using an expensive application of HMAC SHA-256.

Parameters:
  • pass – Password to derive from.
  • pass_len – Length of pass in bytes.
  • salt – Salt to derive from.
  • salt_len – Length of salt in bytes.
  • cost – The cost of the function. The larger this number, the longer the key will take to derive.
  • block_size – The size of memory blocks required.
  • parallelism – Parallelism factor.
  • bytes_out – Destination for the derived pseudorandom key.
  • len – The length of bytes_out in bytes.
Returns:

See Error Codes
int wally_aes(const unsigned char *key, size_t key_len, const unsigned char *bytes, size_t bytes_len, uint32_t flags, unsigned char *bytes_out, size_t len)

Encrypt/decrypt data using AES (ECB mode, no padding).

Parameters:
  • key – Key material for initialisation.
  • key_len – Length of key in bytes. Must be an AES_KEY_LEN_ constant.
  • bytes – Bytes to encrypt/decrypt.
  • bytes_len – Length of bytes in bytes. Must be a multiple of AES_BLOCK_LEN.
  • flags – AES_FLAG_ constants indicating the desired behavior.
  • bytes_out – Destination for the encrypted/decrypted data.
  • len – The length of bytes_out in bytes. Must be a multiple of AES_BLOCK_LEN.
Returns:

See Error Codes
int wally_aes_cbc(const unsigned char *key, size_t key_len, const unsigned char *iv, size_t iv_len, const unsigned char *bytes, size_t bytes_len, uint32_t flags, unsigned char *bytes_out, size_t len, size_t *written)

Encrypt/decrypt data using AES (CBC mode, PKCS#7 padding).

Parameters:
  • key – Key material for initialisation.
  • key_len – Length of key in bytes. Must be an AES_KEY_LEN_ constant.
  • iv – Initialisation vector.
  • iv_len – Length of iv in bytes. Must be AES_BLOCK_LEN.
  • bytes – Bytes to encrypt/decrypt.
  • bytes_len – Length of bytes in bytes. Must be a multiple of AES_BLOCK_LEN.
  • flags – AES_FLAG_ constants indicating the desired behavior.
  • bytes_out – Destination for the encrypted/decrypted data.
  • len – The length of bytes_out in bytes. Must be a multiple of AES_BLOCK_LEN.
  • written – Destination for the number of bytes written to bytes_out.
Returns:

See Variable Length Output Buffers
int wally_sha256(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

SHA-256(m)

Parameters:
  • bytes – The message to hash.
  • bytes_len – The length of bytes in bytes.
  • bytes_out – Destination for the resulting hash.
  • len – The length of bytes_out in bytes. Must be SHA256_LEN.
Returns:

See Error Codes
int wally_sha256_midstate(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

SHA-256(m) midstate

Parameters:
  • bytes – The message to hash.
  • bytes_len – The length of bytes in bytes.
  • bytes_out – Destination for the resulting hash.
  • len – The length of bytes_out in bytes. Must be SHA256_LEN.
Returns:

See Error Codes
int wally_sha256d(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

SHA-256(SHA-256(m)) (double SHA-256).

Parameters:
  • bytes – The message to hash.
  • bytes_len – The length of bytes in bytes.
  • bytes_out – Destination for the resulting hash.
  • len – The length of bytes_out in bytes. Must be SHA256_LEN.
Returns:

See Error Codes
int wally_sha512(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

SHA-512(m).

Parameters:
  • bytes – The message to hash.
  • bytes_len – The length of bytes in bytes.
  • bytes_out – Destination for the resulting hash.
  • len – The length of bytes_out in bytes. Must be SHA512_LEN.
Returns:

See Error Codes
int wally_ripemd160(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

RIPEMD-160(m).

Parameters:
  • bytes – The message to hash.
  • bytes_len – The length of bytes in bytes.
  • bytes_out – Destination for the resulting hash.
  • len – The length of bytes_out in bytes. Must be RIPEMD160_LEN.
Returns:

See Error Codes
int wally_hash160(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

RIPEMD-160(SHA-256(m)).

Parameters:
  • bytes – The message to hash.
  • bytes_len – The length of bytes in bytes.
  • bytes_out – Destination for the resulting hash.
  • len – The length of bytes_out in bytes. Must be HASH160_LEN.
Returns:

See Error Codes
int wally_hmac_sha256(const unsigned char *key, size_t key_len, const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

Compute an HMAC using SHA-256.

Parameters:
  • key – The key for the hash.
  • key_len – The length of key in bytes.
  • bytes – The message to hash.
  • bytes_len – The length of bytes in bytes.
  • bytes_out – Destination for the resulting HMAC.
  • len – The length of bytes_out in bytes. Must be HMAC_SHA256_LEN.
Returns:

See Error Codes
int wally_hmac_sha512(const unsigned char *key, size_t key_len, const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

Compute an HMAC using SHA-512.

Parameters:
  • key – The key for the hash.
  • key_len – The length of key in bytes.
  • bytes – The message to hash.
  • bytes_len – The length of bytes in bytes.
  • bytes_out – Destination for the resulting HMAC.
  • len – The length of bytes_out in bytes. Must be HMAC_SHA512_LEN.
Returns:

See Error Codes
int wally_pbkdf2_hmac_sha256(const unsigned char *pass, size_t pass_len, const unsigned char *salt, size_t salt_len, uint32_t flags, uint32_t cost, unsigned char *bytes_out, size_t len)

Derive a pseudorandom key from inputs using HMAC SHA-256.

Parameters:
  • pass – Password to derive from.
  • pass_len – Length of pass in bytes.
  • salt – Salt to derive from.
  • salt_len – Length of salt in bytes.
  • flags – Reserved, must be 0.
  • cost – The cost of the function. The larger this number, the longer the key will take to derive.
  • bytes_out – Destination for the derived pseudorandom key.
  • len – The length of bytes_out in bytes. This must be a multiple of PBKDF2_HMAC_SHA256_LEN.
Returns:

See Error Codes
int wally_pbkdf2_hmac_sha512(const unsigned char *pass, size_t pass_len, const unsigned char *salt, size_t salt_len, uint32_t flags, uint32_t cost, unsigned char *bytes_out, size_t len)

Derive a pseudorandom key from inputs using HMAC SHA-512.

Parameters:
  • pass – Password to derive from.
  • pass_len – Length of pass in bytes.
  • salt – Salt to derive from.
  • salt_len – Length of salt in bytes.
  • flags – Reserved, must be 0.
  • cost – The cost of the function. The larger this number, the longer the key will take to derive.
  • bytes_out – Destination for the derived pseudorandom key.
  • len – The length of bytes_out in bytes. This must be a multiple of PBKDF2_HMAC_SHA512_LEN.
Returns:

See Error Codes
int wally_ec_private_key_verify(const unsigned char *priv_key, size_t priv_key_len)

Verify that a private key is valid.

Parameters:
  • priv_key – The private key to validate.
  • priv_key_len – The length of priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.
Returns:

See Error Codes
int wally_ec_public_key_verify(const unsigned char *pub_key, size_t pub_key_len)

Verify that a public key is valid.

Parameters:
  • pub_key – The public key to validate.
  • pub_key_len – The length of pub_key in bytes. Must be EC_PUBLIC_KEY_LEN or EC_PUBLIC_KEY_UNCOMPRESSED_LEN.
Returns:

See Error Codes
int wally_ec_public_key_from_private_key(const unsigned char *priv_key, size_t priv_key_len, unsigned char *bytes_out, size_t len)

Create a public key from a private key.

Parameters:
  • priv_key – The private key to create a public key from.
  • priv_key_len – The length of priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.
  • bytes_out – Destination for the resulting public key.
  • len – The length of bytes_out in bytes. Must be EC_PUBLIC_KEY_LEN.
Returns:

See Error Codes
int wally_ec_public_key_decompress(const unsigned char *pub_key, size_t pub_key_len, unsigned char *bytes_out, size_t len)

Create an uncompressed public key from a compressed public key.

Parameters:
  • pub_key – The public key to decompress.
  • pub_key_len – The length of pub_key in bytes. Must be EC_PUBLIC_KEY_LEN.
  • bytes_out – Destination for the resulting public key.
  • len – The length of bytes_out in bytes. Must be EC_PUBLIC_KEY_UNCOMPRESSED_LEN.
Returns:

See Error Codes
int wally_ec_public_key_negate(const unsigned char *pub_key, size_t pub_key_len, unsigned char *bytes_out, size_t len)

Negates a public key.

Parameters:
  • pub_key – The public key to negate.
  • pub_key_len – The length of pub_key in bytes. Must be EC_PUBLIC_KEY_LEN.
  • bytes_out – Destination for the resulting public key.
  • len – The length of bytes_out in bytes. Must be EC_PUBLIC_KEY_LEN.
Returns:

See Error Codes
int wally_ec_sig_from_bytes(const unsigned char *priv_key, size_t priv_key_len, const unsigned char *bytes, size_t bytes_len, uint32_t flags, unsigned char *bytes_out, size_t len)

Sign a message hash with a private key, producing a compact signature.

Parameters:
  • priv_key – The private key to sign with.
  • priv_key_len – The length of priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.
  • bytes – The message hash to sign.
  • bytes_len – The length of bytes in bytes. Must be EC_MESSAGE_HASH_LEN.
  • flags – EC_FLAG_ flag values indicating desired behavior.
  • bytes_out – Destination for the resulting compact signature.
  • len – The length of bytes_out in bytes. Must be EC_SIGNATURE_LEN if EC_FLAG_RECOVERABLE is not set, otherwise must be EC_SIGNATURE_RECOVERABLE_LEN.
Returns:

See Error Codes
int wally_ec_sig_normalize(const unsigned char *sig, size_t sig_len, unsigned char *bytes_out, size_t len)

Convert a signature to low-s form.

Parameters:
  • sig – The compact signature to convert.
  • sig_len – The length of sig in bytes. Must be EC_SIGNATURE_LEN.
  • bytes_out – Destination for the resulting low-s signature.
  • len – The length of bytes_out in bytes. Must be EC_SIGNATURE_LEN.
Returns:

See Error Codes
int wally_ec_sig_to_der(const unsigned char *sig, size_t sig_len, unsigned char *bytes_out, size_t len, size_t *written)

Convert a compact signature to DER encoding.

Parameters:
  • sig – The compact signature to convert.
  • sig_len – The length of sig in bytes. Must be EC_SIGNATURE_LEN.
  • bytes_out – Destination for the resulting DER encoded signature.
  • len – The length of bytes_out in bytes. Must be EC_SIGNATURE_DER_MAX_LEN.
  • written – Destination for the number of bytes written to bytes_out.
Returns:

See Variable Length Output Buffers
int wally_ec_sig_from_der(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len)

Convert a DER encoded signature to a compact signature.

Parameters:
  • bytes – The DER encoded signature to convert.
  • bytes_len – The length of sig in bytes.
  • bytes_out – Destination for the resulting compact signature.
  • len – The length of bytes_out in bytes. Must be EC_SIGNATURE_LEN.
Returns:

See Error Codes
int wally_ec_sig_verify(const unsigned char *pub_key, size_t pub_key_len, const unsigned char *bytes, size_t bytes_len, uint32_t flags, const unsigned char *sig, size_t sig_len)

Verify a signed message hash.

Parameters:
  • pub_key – The public key to verify with.
  • pub_key_len – The length of pub_key in bytes. Must be EC_PUBLIC_KEY_LEN.
  • bytes – The message hash to verify.
  • bytes_len – The length of bytes in bytes. Must be EC_MESSAGE_HASH_LEN.
  • flags – EC_FLAG_ flag values indicating desired behavior.
  • sig – The compact signature of the message in bytes.
  • sig_len – The length of sig in bytes. Must be EC_SIGNATURE_LEN.
Returns:

See Error Codes
int wally_ec_sig_to_public_key(const unsigned char *bytes, size_t bytes_len, const unsigned char *sig, size_t sig_len, unsigned char *bytes_out, size_t len)

Recover compressed public key from a recoverable signature.

Parameters:
  • bytes – The message hash signed.
  • bytes_len – The length of bytes in bytes. Must be EC_MESSAGE_HASH_LEN.
  • sig – The recoverable compact signature of the message in bytes.
  • sig_len – The length of sig in bytes. Must be EC_SIGNATURE_RECOVERABLE_LEN.
  • bytes_out – Destination for recovered public key.
  • len – The length of bytes_out in bytes. Must be EC_PUBLIC_KEY_LEN.

Note

The successful recovery of the public key guarantees the correctness of the signature.

Returns:See Error Codes
int wally_format_bitcoin_message(const unsigned char *bytes, size_t bytes_len, uint32_t flags, unsigned char *bytes_out, size_t len, size_t *written)

Format a message for use as a bitcoin signed message.

Parameters:
  • bytes – The message string to sign.
  • bytes_len – The length of bytes in bytes. Must be less than or equal to BITCOIN_MESSAGE_MAX_LEN.
  • flags – BITCOIN_MESSAGE_FLAG_ flags indicating the desired output. if BITCOIN_MESSAGE_FLAG_HASH is passed, the double SHA256 hash of the message is placed in bytes_out instead of the formatted message. In this case len must be at least SHA256_LEN.
  • bytes_out – Destination for the formatted message or message hash.
  • len – The length of bytes_out in bytes.
  • written – Destination for the number of bytes written to bytes_out.
Returns:

See Variable Length Output Buffers
int wally_ecdh(const unsigned char *pub_key, size_t pub_key_len, const unsigned char *priv_key, size_t priv_key_len, unsigned char *bytes_out, size_t len)

Compute an EC Diffie-Hellman secret in constant time.

Parameters:
  • pub_key – The public key.
  • pub_key_len – The length of pub_key in bytes. Must be EC_PUBLIC_KEY_LEN.
  • priv_key – The private key.
  • priv_key_len – The length of priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.
  • bytes_out – Destination for the shared secret.
  • len – The length of bytes_out in bytes. Must be SHA256_LEN.
Returns:

See Error Codes
int wally_s2c_sig_from_bytes(const unsigned char *priv_key, size_t priv_key_len, const unsigned char *bytes, size_t bytes_len, const unsigned char *s2c_data, size_t s2c_data_len, uint32_t flags, unsigned char *s2c_opening_out, size_t s2c_opening_out_len, unsigned char *bytes_out, size_t len)

Sign a message hash with a private key, producing a compact signature which commits to additional data using sign-to-contract (s2c).

Parameters:
  • priv_key – The private key to sign with.
  • priv_key_len – The length of priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.
  • bytes – The message hash to sign.
  • bytes_len – The length of bytes in bytes. Must be EC_MESSAGE_HASH_LEN.
  • s2c_data – The data to commit to.
  • s2c_data_len – The length of s2c_data in bytes. Must be WALLY_S2C_DATA_LEN.
  • flags – Must be EC_FLAG_ECDSA.
  • s2c_opening_out – Destination for the resulting opening information.
  • s2c_opening_out_len – The length of s2c_opening_out in bytes. Must be WALLY_S2C_OPENING_LEN.
  • bytes_out – Destination for the resulting compact signature.
  • len – The length of bytes_out in bytes. Must be EC_SIGNATURE_LEN.
Returns:

See Error Codes
int wally_s2c_commitment_verify(const unsigned char *sig, size_t sig_len, const unsigned char *s2c_data, size_t s2c_data_len, const unsigned char *s2c_opening, size_t s2c_opening_len, uint32_t flags)

Verify a sign-to-contract (s2c) commitment.

Parameters:
  • sig – The compact signature.
  • sig_len – The length of sig in bytes. Must be EC_SIGNATURE_LEN.
  • s2c_data – The data that was committed to.
  • s2c_data_len – The length of s2c_data in bytes. Must be WALLY_S2C_DATA_LEN.
  • s2c_opening – The opening information produced during signing.
  • s2c_opening_len – The length of s2c_opening in bytes. Must be WALLY_S2C_OPENING_LEN.
  • flags – Must be EC_FLAG_ECDSA.
Returns:

See Error Codes