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. Must be a non-zero multiple of PBKDF2_HMAC_SHA256_LEN.

Returns:

See Error Codes

int wally_aes_len(const unsigned char *key, size_t key_len, const unsigned char *bytes, size_t bytes_len, uint32_t flags, size_t *written)

Get the length of encrypted/decrypted data using AES (ECB mode, no padding).

Parameters:

key – Encryption/decryption key.
key_len – Length of key in bytes. Must be one of the AES key length constants.
bytes – Bytes to encrypt/decrypt.
bytes_len – Length of bytes in bytes. Must be a multiple of AES_BLOCK_LEN.
flags – AES operation flags indicating the desired behavior.
written – Destination for the length of the encrypted/decrypted data.

This function returns bytes_len assuming its arguments are valid.

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 – Encryption/decryption key.
key_len – Length of key in bytes. Must be one of the AES key length constants.
bytes – Bytes to encrypt/decrypt.
bytes_len – Length of bytes in bytes. Must be a multiple of AES_BLOCK_LEN.
flags – AES operation flags 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_get_maximum_length(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, size_t *written)

Get the maximum length of encrypted/decrypted data using AES (CBC mode, PKCS#7 padding).

Parameters:

key – Encryption/decryption key.
key_len – Length of key in bytes. Must be one of the AES key length constants.
iv – Initialization vector. For encryption this should be secure entropy. For decryption the bytes used when encrypting must be given.
iv_len – Length of iv in bytes. Must be AES_BLOCK_LEN.
bytes – Bytes to encrypt/decrypt.
bytes_len – Length of bytes in bytes. Can be of any length for encryption, must be a multiple of AES_BLOCK_LEN for decryption.
flags – AES operation flags indicating the desired behavior.
written – Destination for the maximum length of the encrypted/decrypted data.

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 – Encryption/decryption key.
key_len – Length of key in bytes. Must be one of the AES key length constants.
iv – Initialization vector. For encryption this should be secure entropy. For decryption the bytes used when encrypting must be given.
iv_len – Length of iv in bytes. Must be AES_BLOCK_LEN.
bytes – Bytes to encrypt/decrypt.
bytes_len – Length of bytes in bytes. Can be of any length for encryption, must be a multiple of AES_BLOCK_LEN for decryption.
flags – AES operation flags 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 – Size of bytes_out. 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 – Size of bytes_out. 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 – Size of bytes_out. 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 – Size of bytes_out. Must be SHA512_LEN.

Returns:

See Error Codes

int wally_bip340_tagged_hash(const unsigned char *bytes, size_t bytes_len, const char *tag, unsigned char *bytes_out, size_t len)

BIP340 tagged hash: SHA-256(SHA-256(tag) || SHA-256(tag) || m).

Parameters:

bytes – The message to hash.
bytes_len – The length of bytes in bytes.
tag – The BIP340 UTF-8 domain tag.
bytes_out – Destination for the resulting hash.
len – Size of bytes_out. Must be SHA256_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 – Size of bytes_out. 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 – Size of bytes_out. 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 – Size of bytes_out. 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 – Size of bytes_out. 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 – Size of bytes_out. Must be 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 – Size of bytes_out. Must be 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_xonly_public_key_verify(const unsigned char *pub_key, size_t pub_key_len)

Verify that an x-only public key is valid.

Parameters:

pub_key – The x-only public key to validate.
pub_key_len – The length of pub_key in bytes. Must be EC_XONLY_PUBLIC_KEY_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 – Size of bytes_out. 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 – Size of bytes_out. 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)

Negate 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 – Size of bytes_out. Must be EC_PUBLIC_KEY_LEN.

Returns:

See Error Codes

int wally_ec_public_key_bip341_tweak(const unsigned char *pub_key, size_t pub_key_len, const unsigned char *merkle_root, size_t merkle_root_len, uint32_t flags, unsigned char *bytes_out, size_t len)

Tweak a compressed or x-only public key for taproot.

Parameters:

pub_key – The compressed or x-only public key to tweak.
pub_key_len – The length of pub_key in bytes. Must be either EC_PUBLIC_KEY_LEN or EC_XONLY_PUBLIC_KEY_LEN.
merkle_root – The taproot merkle root hash to tweak by, or NULL if none.
merkle_root_len – The length of merkle_root. Must be SHA256_LEN or 0.
flags – Flags indicating desired behavior. Must be EC_FLAG_ELEMENTS or 0.
bytes_out – Destination for the tweaked public key.
len – Size of bytes_out. Must be EC_PUBLIC_KEY_LEN.

When merkle_root is NULL, the BIP341-suggested commitment P + int(hashTapTweak(bytes(P)))G is used. Otherwise, the merkle root is included, i.e. P + int(hashTapTweak(bytes(P)||merkle_root))G.

Note

This function returns a compressed (not x-only) public key.

Returns:: See Error Codes

int wally_ec_private_key_bip341_tweak(const unsigned char *priv_key, size_t priv_key_len, const unsigned char *merkle_root, size_t merkle_root_len, uint32_t flags, unsigned char *bytes_out, size_t len)

Tweak a private key for taproot.

Parameters:

priv_key – The private key to tweak.
priv_key_len – The length of priv_key in bytes. Must EC_PRIVATE_KEY_LEN.
merkle_root – The taproot merkle root hash to tweak by, or NULL if none.
merkle_root_len – The length of merkle_root. Must be SHA256_LEN or 0.
flags – Flags indicating desired behavior. Must be EC_FLAG_ELEMENTS or 0.
bytes_out – Destination for the tweaked private key.
len – Size of bytes_out. Must be EC_PRIVATE_KEY_LEN.

See wally_ec_public_key_bip341_tweak.

Returns:: See Error Codes

int wally_ec_sig_from_bytes_len(const unsigned char *priv_key, size_t priv_key_len, const unsigned char *bytes, size_t bytes_len, uint32_t flags, size_t *written)

Get the expected length of a signature in bytes.

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 signing flags indicating desired behavior.
written – Destination for the expected length of the signature, either EC_SIGNATURE_LEN or EC_SIGNATURE_RECOVERABLE_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 signing flags indicating desired behavior.
bytes_out – Destination for the resulting compact signature.
len – The length of bytes_out in bytes. Must be EC_SIGNATURE_RECOVERABLE_LEN if flags includes EC_FLAG_RECOVERABLE, otherwise EC_SIGNATURE_LEN.

Equivalent to calling wally_ec_sig_from_bytes_aux with aux_rand set to NULL.

Returns:: See Error Codes

int wally_ec_sig_from_bytes_aux_len(const unsigned char *priv_key, size_t priv_key_len, const unsigned char *bytes, size_t bytes_len, const unsigned char *aux_rand, size_t aux_rand_len, uint32_t flags, size_t *written)

Get the expected length of a signature with auxiliary data in bytes.

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.
aux_rand – Optional auxiliary data or NULL. See wally_ec_sig_from_bytes_aux.
aux_rand_len – The length of aux_rand in bytes. See wally_ec_sig_from_bytes_aux.
flags – EC signing flags indicating desired behavior.
written – Destination for the expected length of the signature, either EC_SIGNATURE_LEN or EC_SIGNATURE_RECOVERABLE_LEN.

Returns:

See Error Codes

int wally_ec_sig_from_bytes_aux(const unsigned char *priv_key, size_t priv_key_len, const unsigned char *bytes, size_t bytes_len, const unsigned char *aux_rand, size_t aux_rand_len, uint32_t flags, unsigned char *bytes_out, size_t len)

Sign a message hash with a private key and auxiliary data, 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.
aux_rand – Optional auxiliary data or NULL. Must be NULL if flags includes EC_FLAG_GRIND_R. For BIP340/schnorr signatures it is strongly advised to pass fresh entropy as a defense in depth measure.
aux_rand_len – The length of aux_rand in bytes. Must be 32 or 0 if aux_rand is non-NULL.
flags – EC signing flags indicating desired behavior.
bytes_out – Destination for the resulting compact signature.
len – The length of bytes_out in bytes. Must be EC_SIGNATURE_RECOVERABLE_LEN if flags includes EC_FLAG_RECOVERABLE, otherwise EC_SIGNATURE_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 – Size of bytes_out. 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 – Size of bytes_out. Passing EC_SIGNATURE_DER_MAX_LEN will ensure the buffer is large enough.
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 – Size of bytes_out. 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 signing flags 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 – Size of bytes_out. 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_ec_scalar_verify(const unsigned char *scalar, size_t scalar_len)

Verify that a secp256k1 scalar value is valid.

Parameters:

scalar – The starting scalar to have a value added to.
scalar_len – The length of scalar in bytes. Must be EC_SCALAR_LEN.

Returns:

See Error Codes

int wally_ec_scalar_add(const unsigned char *scalar, size_t scalar_len, const unsigned char *operand, size_t operand_len, unsigned char *bytes_out, size_t len)

Add one secp256k1 scalar to another.

Parameters:

scalar – The starting scalar to have a value added to.
scalar_len – The length of scalar in bytes. Must be EC_SCALAR_LEN.
operand – The scalar value to add to scalar.
operand_len – The length of operand in bytes. Must be EC_SCALAR_LEN.
bytes_out – Destination for the resulting scalar.
len – Size of bytes_out. Must be EC_SCALAR_LEN.

Note

Computes (scalar + operand) % n. Returns WALLY_ERROR if either input is not within the secp256k1 group order n.

Returns:: See Error Codes

int wally_ec_scalar_subtract(const unsigned char *scalar, size_t scalar_len, const unsigned char *operand, size_t operand_len, unsigned char *bytes_out, size_t len)

Subtract one secp256k1 scalar from another.

Parameters:

scalar – The starting scalar to have a value subtracted from.
scalar_len – The length of scalar in bytes. Must be EC_SCALAR_LEN.
operand – The scalar value to subtract from scalar.
operand_len – The length of operand in bytes. Must be EC_SCALAR_LEN.
bytes_out – Destination for the resulting scalar.
len – Size of bytes_out. Must be EC_SCALAR_LEN.

Note

Computes (scalar - operand) % n. Returns WALLY_ERROR if either input is not within the secp256k1 group order n.

Returns:: See Error Codes

int wally_ec_scalar_multiply(const unsigned char *scalar, size_t scalar_len, const unsigned char *operand, size_t operand_len, unsigned char *bytes_out, size_t len)

Multiply one secp256k1 scalar by another.

Parameters:

scalar – The starting scalar to multiply.
scalar_len – The length of scalar in bytes. Must be EC_SCALAR_LEN.
operand – The scalar value to multiply scalar by.
operand_len – The length of operand in bytes. Must be EC_SCALAR_LEN.
bytes_out – Destination for the resulting scalar.
len – Size of bytes_out. Must be EC_SCALAR_LEN.

Note

Computes (scalar * operand) % n. Returns WALLY_ERROR if either input is not within the secp256k1 group order n.

Returns:: See Error Codes

int wally_ec_scalar_add_to(unsigned char *scalar, size_t scalar_len, const unsigned char *operand, size_t operand_len)

Add one secp256k1 scalar to another in place.

Note

As per wally_ec_scalar_add with scalar modified in place.

Returns:: See Error Codes

int wally_ec_scalar_subtract_from(unsigned char *scalar, size_t scalar_len, const unsigned char *operand, size_t operand_len)

Subtract one secp256k1 scalar from another in place.

Note

As per wally_ec_scalar_subtract with scalar modified in place.

Returns:: See Error Codes

int wally_ec_scalar_multiply_by(unsigned char *scalar, size_t scalar_len, const unsigned char *operand, size_t operand_len)

Multiply one secp256k1 scalar by another in place.

Note

As per wally_ec_scalar_multiply with scalar modified in place.

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 processing 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 – Size of bytes_out. Must be SHA256_LEN.

Note

If priv_key is invalid, this call returns WALLY_ERROR.

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 – Size of s2c_opening_out. Must be WALLY_S2C_OPENING_LEN.
bytes_out – Destination for the resulting compact signature.
len – Size of bytes_out. 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

int wally_aes_cbc_with_ecdh_key_get_maximum_length(const unsigned char *priv_key, size_t priv_key_len, const unsigned char *iv, size_t iv_len, const unsigned char *bytes, size_t bytes_len, const unsigned char *pub_key, size_t pub_key_len, const unsigned char *label, size_t label_len, uint32_t flags, size_t *written)

Get the maximum length of data encrypted/decrypted using wally_aes_cbc_with_ecdh_key.

Parameters:

priv_key – The callers private key used for Diffie-Helman exchange.
priv_key_len – The length of priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.
iv – Initialization vector. Only required when encrypting, otherwise pass NULL.
iv_len – Length of iv in bytes. Must be AES_BLOCK_LEN.
bytes – Bytes to encrypt/decrypt.
bytes_len – Length of bytes in bytes.
pub_key – The other parties public key used for Diffie-Helman exchange.
pub_key_len – Length of pub_key in bytes. Must be EC_PUBLIC_KEY_LEN.
label – A non-empty array of bytes for internal key generation. Must be the same (fixed) value when encrypting and decrypting.
label_len – Length of label in bytes.
flags – AES operation flags indicating the desired behavior.
written – Destination for the maximum length of the encrypted/decrypted data.

Returns:

See Error Codes

int wally_aes_cbc_with_ecdh_key(const unsigned char *priv_key, size_t priv_key_len, const unsigned char *iv, size_t iv_len, const unsigned char *bytes, size_t bytes_len, const unsigned char *pub_key, size_t pub_key_len, const unsigned char *label, size_t label_len, uint32_t flags, unsigned char *bytes_out, size_t len, size_t *written)

Encrypt/decrypt data using AES-256 (CBC mode, PKCS#7 padding) and a shared Diffie-Helman secret.

Parameters:

priv_key – The callers private key used for Diffie-Helman exchange.
priv_key_len – The length of priv_key in bytes. Must be EC_PRIVATE_KEY_LEN.
iv – Initialization vector. Only required when encrypting, otherwise pass NULL.
iv_len – Length of iv in bytes. Must be AES_BLOCK_LEN if encrypting otherwise 0.
bytes – Bytes to encrypt/decrypt.
bytes_len – Length of bytes in bytes.
pub_key – The other parties public key used for Diffie-Helman exchange.
pub_key_len – Length of pub_key in bytes. Must be EC_PUBLIC_KEY_LEN.
label – A non-empty array of bytes for internal key generation. Must be the same (fixed) value when encrypting and decrypting.
label_len – Length of label in bytes.
flags – AES operation flags indicating the desired behavior.
bytes_out – Destination for the encrypted/decrypted data.
len – The length of bytes_out in bytes.
written – Destination for the number of bytes written to bytes_out.

This function implements a scheme for sharing data using a derived secret. Alice creates an ephemeral key pair and sends her public key to Bob along with any request details. Bob creates an ephemeral key pair and calls this function with his private key and Alices public key to encrypt bytes (the request payload). Bob returns his public key and the encrypted data to Alice, who calls this function with her private key and Bobs public key to decrypt and authenticate the payload. The label parameter must be be the same for both Alice and Bob for a given request/response.

Returns:: See Variable Length Output Buffers

Crypto Constants

AES_BLOCK_LEN: Length of AES encrypted blocks

AES key length constants

AES_KEY_LEN_128: AES-128 Key length, 128 bits

AES_KEY_LEN_192: AES-192 Key length, 192 bits

AES_KEY_LEN_256: AES-256 Key length, 256 bits

AES operation flags

AES_FLAG_ENCRYPT: Encrypt

AES_FLAG_DECRYPT: Decrypt

SHA256_LEN: Output length for wally_sha256

SHA512_LEN: Output length for wally_sha512

RIPEMD160_LEN: Output length for wally_ripemd160

HASH160_LEN: Output length for wally_hash160

HMAC_SHA256_LEN: Output length for wally_hmac_sha256

HMAC_SHA512_LEN: Output length for wally_hmac_sha512

PBKDF2_HMAC_SHA256_LEN: Output length for wally_pbkdf2_hmac_sha256

PBKDF2_HMAC_SHA512_LEN: Output length for wally_pbkdf2_hmac_sha512

EC_PRIVATE_KEY_LEN: The length of a private key used for EC signing

EC_PUBLIC_KEY_LEN: The length of a public key used for EC signing

EC_XONLY_PUBLIC_KEY_LEN: The length of an x-only public key used for EC signing

EC_PUBLIC_KEY_UNCOMPRESSED_LEN: The length of an uncompressed public key

EC_MESSAGE_HASH_LEN: The length of a message hash to EC sign

EC_SIGNATURE_LEN: The length of a compact signature produced by EC signing

EC_SIGNATURE_RECOVERABLE_LEN: The length of a compact recoverable signature produced by EC signing

EC_SIGNATURE_DER_MAX_LEN: The maximum encoded length of a DER signature (High-R, High-S), excluding sighash byte

EC_SIGNATURE_DER_MAX_LOW_R_LEN: The maximum encoded length of a DER signature created with EC_FLAG_GRIND_R (Low-R, Low-S), excluding sighash byte

EC_SCALAR_LEN: The length of a secp256k1 scalar value

EC signing flags

EC_FLAG_ECDSA: Indicates that a signature using ECDSA/secp256k1 is required

EC_FLAG_SCHNORR: Indicates that a signature using EC-Schnorr-SHA256 is required

EC_FLAG_GRIND_R: ECDSA only: indicates that the signature nonce should be incremented until the signature is low-R

EC_FLAG_RECOVERABLE: ECDSA only: Indicates that the signature is recoverable

EC_FLAG_ELEMENTS: Schnorr only: Indicates that the Elements/Liquid tagged hashes should be used where needed

EC_FLAGS_ALL

BITCOIN_MESSAGE_MAX_LEN: The maximum size of input message that can be formatted

Bitcoin message processing flags

BITCOIN_MESSAGE_FLAG_HASH: Indicates that SHA256D(message) should be returned

WALLY_S2C_DATA_LEN: The length of a data committed using sign-to-contract (s2c)

WALLY_S2C_OPENING_LEN: The length of a sign-to-contract (s2c) opening