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 ofPBKDF2_HMAC_SHA256_LEN
.
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 ofAES_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 ofAES_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 beAES_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 ofAES_BLOCK_LEN
for decryption. - 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 ofAES_BLOCK_LEN
. - written – Destination for the number of bytes written to
bytes_out
.
Returns:
-
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 beSHA256_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 beSHA256_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 beSHA256_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 beSHA512_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 beRIPEMD160_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 beHASH160_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 beHMAC_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 beHMAC_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 bePBKDF2_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 bePBKDF2_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 beEC_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 beEC_PUBLIC_KEY_LEN
orEC_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 beEC_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 beEC_PRIVATE_KEY_LEN
. - bytes_out – Destination for the resulting public key.
- len – Size of
bytes_out
. Must beEC_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 beEC_PUBLIC_KEY_LEN
. - bytes_out – Destination for the resulting public key.
- len – Size of
bytes_out
. Must beEC_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 beEC_PUBLIC_KEY_LEN
. - bytes_out – Destination for the resulting public key.
- len – Size of
bytes_out
. Must beEC_PUBLIC_KEY_LEN
.
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 beEC_PRIVATE_KEY_LEN
. - bytes – The message hash to sign.
- bytes_len – The length of
bytes
in bytes. Must beEC_MESSAGE_HASH_LEN
. - flags – EC_FLAG_ flag values indicating desired behavior.
- written – Destination for the expected length of the signature, either
EC_SIGNATURE_LEN
orEC_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 beEC_PRIVATE_KEY_LEN
. - bytes – The message hash to sign.
- bytes_len – The length of
bytes
in bytes. Must beEC_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 beEC_SIGNATURE_RECOVERABLE_LEN
if flags includesEC_FLAG_RECOVERABLE
, otherwiseEC_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 beEC_SIGNATURE_LEN
. - bytes_out – Destination for the resulting low-s signature.
- len – Size of
bytes_out
. Must beEC_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 beEC_SIGNATURE_LEN
. - bytes_out – Destination for the resulting DER encoded signature.
- n – Size of
bytes_out
. PassingEC_SIGNATURE_DER_MAX_LEN
will ensure the buffer is large enough. - written – Destination for the number of bytes written to
bytes_out
.
Returns:
-
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 beEC_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 beEC_PUBLIC_KEY_LEN
. - bytes – The message hash to verify.
- bytes_len – The length of
bytes
in bytes. Must beEC_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 beEC_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 beEC_MESSAGE_HASH_LEN
. - sig – The recoverable compact signature of the message in
bytes
. - sig_len – The length of
sig
in bytes. Must beEC_SIGNATURE_RECOVERABLE_LEN
. - bytes_out – Destination for recovered public key.
- len – Size of
bytes_out
. Must beEC_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 beEC_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 beEC_SCALAR_LEN
. - operand – The scalar value to add to
scalar
. - operand_len – The length of
operand
in bytes. Must beEC_SCALAR_LEN
. - bytes_out – Destination for the resulting scalar.
- len – Size of
bytes_out
. Must beEC_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 beEC_SCALAR_LEN
. - operand – The scalar value to subtract from
scalar
. - operand_len – The length of
operand
in bytes. Must beEC_SCALAR_LEN
. - bytes_out – Destination for the resulting scalar.
- len – Size of
bytes_out
. Must beEC_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 beEC_SCALAR_LEN
. - operand – The scalar value to multiply
scalar
by. - operand_len – The length of
operand
in bytes. Must beEC_SCALAR_LEN
. - bytes_out – Destination for the resulting scalar.
- len – Size of
bytes_out
. Must beEC_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
withscalar
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
withscalar
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
withscalar
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_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 caselen
must be at leastSHA256_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:
-
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 beEC_PUBLIC_KEY_LEN
. - priv_key – The private key.
- priv_key_len – The length of
priv_key
in bytes. Must beEC_PRIVATE_KEY_LEN
. - bytes_out – Destination for the shared secret.
- len – Size of
bytes_out
. Must beSHA256_LEN
.
Note
If
priv_key
is invalid, this call returnsWALLY_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 beEC_PRIVATE_KEY_LEN
. - bytes – The message hash to sign.
- bytes_len – The length of
bytes
in bytes. Must beEC_MESSAGE_HASH_LEN
. - s2c_data – The data to commit to.
- s2c_data_len – The length of
s2c_data
in bytes. Must beWALLY_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 beWALLY_S2C_OPENING_LEN
. - bytes_out – Destination for the resulting compact signature.
- len – Size of
bytes_out
. Must beEC_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 beEC_SIGNATURE_LEN
. - s2c_data – The data that was committed to.
- s2c_data_len – The length of
s2c_data
in bytes. Must beWALLY_S2C_DATA_LEN
. - s2c_opening – The opening information produced during signing.
- s2c_opening_len – The length of
s2c_opening
in bytes. Must beWALLY_S2C_OPENING_LEN
. - flags – Must be
EC_FLAG_ECDSA
.
Returns: See Error Codes