Crypto Functions ================ .. c:function:: 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. :param pass: Password to derive from. :param pass_len: Length of ``pass`` in bytes. :param salt: Salt to derive from. :param salt_len: Length of ``salt`` in bytes. :param cost: The cost of the function. The larger this number, the longer the key will take to derive. :param block_size: The size of memory blocks required. :param parallelism: Parallelism factor. :param bytes_out: Destination for the derived pseudorandom key. :param len: The length of ``bytes_out`` in bytes. Must be a non-zero multiple of `PBKDF2_HMAC_SHA256_LEN`. :return: See :ref:`error-codes` .. c:function:: 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). :param key: Encryption/decryption key. :param key_len: Length of ``key`` in bytes. Must be one of the :ref:`aes-key-length`. :param bytes: Bytes to encrypt/decrypt. :param bytes_len: Length of ``bytes`` in bytes. Must be a multiple of `AES_BLOCK_LEN`. :param flags: :ref:`aes-operation-flag` indicating the desired behavior. :param written: Destination for the length of the encrypted/decrypted data. This function returns ``bytes_len`` assuming its arguments are valid. :return: See :ref:`error-codes` .. c:function:: 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). :param key: Encryption/decryption key. :param key_len: Length of ``key`` in bytes. Must be one of the :ref:`aes-key-length`. :param bytes: Bytes to encrypt/decrypt. :param bytes_len: Length of ``bytes`` in bytes. Must be a multiple of `AES_BLOCK_LEN`. :param flags: :ref:`aes-operation-flag` indicating the desired behavior. :param bytes_out: Destination for the encrypted/decrypted data. :param len: The length of ``bytes_out`` in bytes. Must be a multiple of `AES_BLOCK_LEN`. :return: See :ref:`error-codes` .. c:function:: 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). :param key: Encryption/decryption key. :param key_len: Length of ``key`` in bytes. Must be one of the :ref:`aes-key-length`. :param iv: Initialization vector. For encryption this should be secure entropy. For decryption the bytes used when encrypting must be given. :param iv_len: Length of ``iv`` in bytes. Must be `AES_BLOCK_LEN`. :param bytes: Bytes to encrypt/decrypt. :param bytes_len: Length of ``bytes`` in bytes. Can be of any length for encryption, must be a multiple of `AES_BLOCK_LEN` for decryption. :param flags: :ref:`aes-operation-flag` indicating the desired behavior. :param written: Destination for the maximum length of the encrypted/decrypted data. :return: See :ref:`error-codes` .. c:function:: 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). :param key: Encryption/decryption key. :param key_len: Length of ``key`` in bytes. Must be one of the :ref:`aes-key-length`. :param iv: Initialization vector. For encryption this should be secure entropy. For decryption the bytes used when encrypting must be given. :param iv_len: Length of ``iv`` in bytes. Must be `AES_BLOCK_LEN`. :param bytes: Bytes to encrypt/decrypt. :param bytes_len: Length of ``bytes`` in bytes. Can be of any length for encryption, must be a multiple of `AES_BLOCK_LEN` for decryption. :param flags: :ref:`aes-operation-flag` indicating the desired behavior. :param bytes_out: Destination for the encrypted/decrypted data. :param len: The length of ``bytes_out`` in bytes. Must be a multiple of `AES_BLOCK_LEN`. :param written: Destination for the number of bytes written to ``bytes_out``. :return: See :ref:`variable-length-output-buffers` .. c:function:: int wally_sha256(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len) SHA-256(m) :param bytes: The message to hash. :param bytes_len: The length of ``bytes`` in bytes. :param bytes_out: Destination for the resulting hash. :param len: Size of ``bytes_out``. Must be `SHA256_LEN`. :return: See :ref:`error-codes` .. c:function:: int wally_sha256_midstate(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len) SHA-256(m) midstate :param bytes: The message to hash. :param bytes_len: The length of ``bytes`` in bytes. :param bytes_out: Destination for the resulting hash. :param len: Size of ``bytes_out``. Must be `SHA256_LEN`. :return: See :ref:`error-codes` .. c:function:: 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). :param bytes: The message to hash. :param bytes_len: The length of ``bytes`` in bytes. :param bytes_out: Destination for the resulting hash. :param len: Size of ``bytes_out``. Must be `SHA256_LEN`. :return: See :ref:`error-codes` .. c:function:: int wally_sha512(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len) SHA-512(m). :param bytes: The message to hash. :param bytes_len: The length of ``bytes`` in bytes. :param bytes_out: Destination for the resulting hash. :param len: Size of ``bytes_out``. Must be `SHA512_LEN`. :return: See :ref:`error-codes` .. c:function:: 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). :param bytes: The message to hash. :param bytes_len: The length of ``bytes`` in bytes. :param tag: The BIP340 UTF-8 domain tag. :param bytes_out: Destination for the resulting hash. :param len: Size of ``bytes_out``. Must be `SHA256_LEN`. :return: See :ref:`error-codes` .. c:function:: int wally_ripemd160(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len) RIPEMD-160(m). :param bytes: The message to hash. :param bytes_len: The length of ``bytes`` in bytes. :param bytes_out: Destination for the resulting hash. :param len: Size of ``bytes_out``. Must be `RIPEMD160_LEN`. :return: See :ref:`error-codes` .. c:function:: int wally_hash160(const unsigned char *bytes, size_t bytes_len, unsigned char *bytes_out, size_t len) RIPEMD-160(SHA-256(m)). :param bytes: The message to hash. :param bytes_len: The length of ``bytes`` in bytes. :param bytes_out: Destination for the resulting hash. :param len: Size of ``bytes_out``. Must be `HASH160_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param key: The key for the hash. :param key_len: The length of ``key`` in bytes. :param bytes: The message to hash. :param bytes_len: The length of ``bytes`` in bytes. :param bytes_out: Destination for the resulting HMAC. :param len: Size of ``bytes_out``. Must be `HMAC_SHA256_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param key: The key for the hash. :param key_len: The length of ``key`` in bytes. :param bytes: The message to hash. :param bytes_len: The length of ``bytes`` in bytes. :param bytes_out: Destination for the resulting HMAC. :param len: Size of ``bytes_out``. Must be `HMAC_SHA512_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param pass: Password to derive from. :param pass_len: Length of ``pass`` in bytes. :param salt: Salt to derive from. :param salt_len: Length of ``salt`` in bytes. :param flags: Reserved, must be 0. :param cost: The cost of the function. The larger this number, the longer the key will take to derive. :param bytes_out: Destination for the derived pseudorandom key. :param len: Size of ``bytes_out``. Must be `PBKDF2_HMAC_SHA256_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param pass: Password to derive from. :param pass_len: Length of ``pass`` in bytes. :param salt: Salt to derive from. :param salt_len: Length of ``salt`` in bytes. :param flags: Reserved, must be 0. :param cost: The cost of the function. The larger this number, the longer the key will take to derive. :param bytes_out: Destination for the derived pseudorandom key. :param len: Size of ``bytes_out``. Must be `PBKDF2_HMAC_SHA512_LEN`. :return: See :ref:`error-codes` .. c:function:: int wally_ec_private_key_verify(const unsigned char *priv_key, size_t priv_key_len) Verify that a private key is valid. :param priv_key: The private key to validate. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :return: See :ref:`error-codes` .. c:function:: int wally_ec_public_key_verify(const unsigned char *pub_key, size_t pub_key_len) Verify that a public key is valid. :param pub_key: The public key to validate. :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN` or `EC_PUBLIC_KEY_UNCOMPRESSED_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param pub_key: The x-only public key to validate. :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_XONLY_PUBLIC_KEY_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param priv_key: The private key to create a public key from. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :param bytes_out: Destination for the resulting public key. :param len: Size of ``bytes_out``. Must be `EC_PUBLIC_KEY_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param pub_key: The public key to decompress. :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`. :param bytes_out: Destination for the resulting public key. :param len: Size of ``bytes_out``. Must be `EC_PUBLIC_KEY_UNCOMPRESSED_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param pub_key: The public key to negate. :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`. :param bytes_out: Destination for the resulting public key. :param len: Size of ``bytes_out``. Must be `EC_PUBLIC_KEY_LEN`. :return: See :ref:`error-codes` .. c:function:: int wally_ec_public_key_tweak(const unsigned char *pub_key, size_t pub_key_len, const unsigned char *tweak, size_t tweak_len, unsigned char *bytes_out, size_t len) Tweak a public key. :param pub_key: The public key to tweak. :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`. :param tweak: The scalar/private key to tweak by. :param tweak_len: The length of ``tweak``. Must be `EC_PRIVATE_KEY_LEN`. :param bytes_out: Destination for the tweaked public key. :param len: Size of ``bytes_out``. Must be `EC_PUBLIC_KEY_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param pub_key: The compressed or x-only public key to tweak. :param pub_key_len: The length of ``pub_key`` in bytes. Must be either `EC_PUBLIC_KEY_LEN` or `EC_XONLY_PUBLIC_KEY_LEN`. :param merkle_root: The taproot merkle root hash to tweak by, or NULL if none. :param merkle_root_len: The length of ``merkle_root``. Must be `SHA256_LEN` or 0. :param flags: Flags indicating desired behavior. Must be `EC_FLAG_ELEMENTS` or 0. :param bytes_out: Destination for the tweaked public key. :param 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. :return: See :ref:`error-codes` .. c:function:: 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. :param priv_key: The private key to tweak. :param priv_key_len: The length of ``priv_key`` in bytes. Must `EC_PRIVATE_KEY_LEN`. :param merkle_root: The taproot merkle root hash to tweak by, or NULL if none. :param merkle_root_len: The length of ``merkle_root``. Must be `SHA256_LEN` or 0. :param flags: Flags indicating desired behavior. Must be `EC_FLAG_ELEMENTS` or 0. :param bytes_out: Destination for the tweaked private key. :param len: Size of ``bytes_out``. Must be `EC_PRIVATE_KEY_LEN`. See `wally_ec_public_key_bip341_tweak`. :return: See :ref:`error-codes` .. c:function:: 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. :param priv_key: The private key to sign with. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :param bytes: The message hash to sign. :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`. :param flags: :ref:`ec-flags` indicating desired behavior. :param written: Destination for the expected length of the signature, either `EC_SIGNATURE_LEN` or `EC_SIGNATURE_RECOVERABLE_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param priv_key: The private key to sign with. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :param bytes: The message hash to sign. :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`. :param flags: :ref:`ec-flags` indicating desired behavior. :param bytes_out: Destination for the resulting compact signature. :param 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. :return: See :ref:`error-codes` .. c:function:: 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. :param priv_key: The private key to sign with. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :param bytes: The message hash to sign. :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`. :param aux_rand: Optional auxiliary data or NULL. See `wally_ec_sig_from_bytes_aux`. :param aux_rand_len: The length of ``aux_rand`` in bytes. See `wally_ec_sig_from_bytes_aux`. :param flags: :ref:`ec-flags` indicating desired behavior. :param written: Destination for the expected length of the signature, either `EC_SIGNATURE_LEN` or `EC_SIGNATURE_RECOVERABLE_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param priv_key: The private key to sign with. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :param bytes: The message hash to sign. :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`. :param 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. :param aux_rand_len: The length of ``aux_rand`` in bytes. Must be ``32`` or ``0`` if ``aux_rand`` is non-NULL. :param flags: :ref:`ec-flags` indicating desired behavior. :param bytes_out: Destination for the resulting compact signature. :param len: The length of ``bytes_out`` in bytes. Must be `EC_SIGNATURE_RECOVERABLE_LEN` if flags includes `EC_FLAG_RECOVERABLE`, otherwise `EC_SIGNATURE_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param sig: The compact signature to convert. :param sig_len: The length of ``sig`` in bytes. Must be `EC_SIGNATURE_LEN`. :param bytes_out: Destination for the resulting low-s signature. :param len: Size of ``bytes_out``. Must be `EC_SIGNATURE_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param sig: The compact signature to convert. :param sig_len: The length of ``sig`` in bytes. Must be `EC_SIGNATURE_LEN`. :param bytes_out: Destination for the resulting DER encoded signature. :param len: Size of ``bytes_out``. Passing `EC_SIGNATURE_DER_MAX_LEN` will ensure the buffer is large enough. :param written: Destination for the number of bytes written to ``bytes_out``. :return: See :ref:`variable-length-output-buffers` .. c:function:: 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. :param bytes: The DER encoded signature to convert. :param bytes_len: The length of ``sig`` in bytes. :param bytes_out: Destination for the resulting compact signature. :param len: Size of ``bytes_out``. Must be `EC_SIGNATURE_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param pub_key: The public key to verify with. :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`. :param bytes: The message hash to verify. :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`. :param flags: :ref:`ec-flags` indicating desired behavior. :param sig: The compact signature of the message in ``bytes``. :param sig_len: The length of ``sig`` in bytes. Must be `EC_SIGNATURE_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param bytes: The message hash signed. :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`. :param sig: The recoverable compact signature of the message in ``bytes``. :param sig_len: The length of ``sig`` in bytes. Must be `EC_SIGNATURE_RECOVERABLE_LEN`. :param bytes_out: Destination for recovered public key. :param 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. :return: See :ref:`error-codes` .. c:function:: int wally_ec_scalar_verify(const unsigned char *scalar, size_t scalar_len) Verify that a secp256k1 scalar value is valid. :param scalar: The starting scalar to have a value added to. :param scalar_len: The length of ``scalar`` in bytes. Must be `EC_SCALAR_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param scalar: The starting scalar to have a value added to. :param scalar_len: The length of ``scalar`` in bytes. Must be `EC_SCALAR_LEN`. :param operand: The scalar value to add to ``scalar``. :param operand_len: The length of ``operand`` in bytes. Must be `EC_SCALAR_LEN`. :param bytes_out: Destination for the resulting scalar. :param 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. :return: See :ref:`error-codes` .. c:function:: 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. :param scalar: The starting scalar to have a value subtracted from. :param scalar_len: The length of ``scalar`` in bytes. Must be `EC_SCALAR_LEN`. :param operand: The scalar value to subtract from ``scalar``. :param operand_len: The length of ``operand`` in bytes. Must be `EC_SCALAR_LEN`. :param bytes_out: Destination for the resulting scalar. :param 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. :return: See :ref:`error-codes` .. c:function:: 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. :param scalar: The starting scalar to multiply. :param scalar_len: The length of ``scalar`` in bytes. Must be `EC_SCALAR_LEN`. :param operand: The scalar value to multiply ``scalar`` by. :param operand_len: The length of ``operand`` in bytes. Must be `EC_SCALAR_LEN`. :param bytes_out: Destination for the resulting scalar. :param 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. :return: See :ref:`error-codes` .. c:function:: 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. :return: See :ref:`error-codes` .. c:function:: 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. :return: See :ref:`error-codes` .. c:function:: 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. :return: See :ref:`error-codes` .. c:function:: 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. :param bytes: The message string to sign. :param bytes_len: The length of ``bytes`` in bytes. Must be less than or equal to `BITCOIN_MESSAGE_MAX_LEN`. :param flags: :ref:`bitcoin-message-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`. :param bytes_out: Destination for the formatted message or message hash. :param len: The length of ``bytes_out`` in bytes. :param written: Destination for the number of bytes written to ``bytes_out``. :return: See :ref:`variable-length-output-buffers` .. c:function:: 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. :param pub_key: The public key. :param pub_key_len: The length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`. :param priv_key: The private key. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :param bytes_out: Destination for the shared secret. :param len: Size of ``bytes_out``. Must be `SHA256_LEN`. .. note:: If ``priv_key`` is invalid, this call returns `WALLY_ERROR`. :return: See :ref:`error-codes` .. c:function:: 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). :param priv_key: The private key to sign with. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :param bytes: The message hash to sign. :param bytes_len: The length of ``bytes`` in bytes. Must be `EC_MESSAGE_HASH_LEN`. :param s2c_data: The data to commit to. :param s2c_data_len: The length of ``s2c_data`` in bytes. Must be `WALLY_S2C_DATA_LEN`. :param flags: Must be `EC_FLAG_ECDSA`. :param s2c_opening_out: Destination for the resulting opening information. :param s2c_opening_out_len: Size of ``s2c_opening_out``. Must be `WALLY_S2C_OPENING_LEN`. :param bytes_out: Destination for the resulting compact signature. :param len: Size of ``bytes_out``. Must be `EC_SIGNATURE_LEN`. :return: See :ref:`error-codes` .. c:function:: 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. :param sig: The compact signature. :param sig_len: The length of ``sig`` in bytes. Must be `EC_SIGNATURE_LEN`. :param s2c_data: The data that was committed to. :param s2c_data_len: The length of ``s2c_data`` in bytes. Must be `WALLY_S2C_DATA_LEN`. :param s2c_opening: The opening information produced during signing. :param s2c_opening_len: The length of ``s2c_opening`` in bytes. Must be `WALLY_S2C_OPENING_LEN`. :param flags: Must be `EC_FLAG_ECDSA`. :return: See :ref:`error-codes` .. c:function:: 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`. :param priv_key: The callers private key used for Diffie-Helman exchange. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :param iv: Initialization vector. Only required when encrypting, otherwise pass NULL. :param iv_len: Length of ``iv`` in bytes. Must be `AES_BLOCK_LEN`. :param bytes: Bytes to encrypt/decrypt. :param bytes_len: Length of ``bytes`` in bytes. :param pub_key: The other parties public key used for Diffie-Helman exchange. :param pub_key_len: Length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`. :param label: A non-empty array of bytes for internal key generation. Must be the same (fixed) value when encrypting and decrypting. :param label_len: Length of ``label`` in bytes. :param flags: :ref:`aes-operation-flag` indicating the desired behavior. :param written: Destination for the maximum length of the encrypted/decrypted data. :return: See :ref:`error-codes` .. c:function:: 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. :param priv_key: The callers private key used for Diffie-Helman exchange. :param priv_key_len: The length of ``priv_key`` in bytes. Must be `EC_PRIVATE_KEY_LEN`. :param iv: Initialization vector. Only required when encrypting, otherwise pass NULL. :param iv_len: Length of ``iv`` in bytes. Must be `AES_BLOCK_LEN` if encrypting otherwise 0. :param bytes: Bytes to encrypt/decrypt. :param bytes_len: Length of ``bytes`` in bytes. :param pub_key: The other parties public key used for Diffie-Helman exchange. :param pub_key_len: Length of ``pub_key`` in bytes. Must be `EC_PUBLIC_KEY_LEN`. :param label: A non-empty array of bytes for internal key generation. Must be the same (fixed) value when encrypting and decrypting. :param label_len: Length of ``label`` in bytes. :param flags: :ref:`aes-operation-flag` indicating the desired behavior. :param bytes_out: Destination for the encrypted/decrypted data. :param len: The length of ``bytes_out`` in bytes. :param 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. :return: See :ref:`variable-length-output-buffers` Crypto Constants ---------------- .. c:macro:: AES_BLOCK_LEN Length of AES encrypted blocks .. _aes-key-length: AES key length constants ^^^^^^^^^^^^^^^^^^^^^^^^ .. c:macro:: AES_KEY_LEN_128 AES-128 Key length, 128 bits .. c:macro:: AES_KEY_LEN_192 AES-192 Key length, 192 bits .. c:macro:: AES_KEY_LEN_256 AES-256 Key length, 256 bits .. _aes-operation-flag: AES operation flags ^^^^^^^^^^^^^^^^^^^ .. c:macro:: AES_FLAG_ENCRYPT Encrypt .. c:macro:: AES_FLAG_DECRYPT Decrypt .. c:macro:: SHA256_LEN Output length for `wally_sha256` .. c:macro:: SHA512_LEN Output length for `wally_sha512` .. c:macro:: RIPEMD160_LEN Output length for `wally_ripemd160` .. c:macro:: HASH160_LEN Output length for `wally_hash160` .. c:macro:: HMAC_SHA256_LEN Output length for `wally_hmac_sha256` .. c:macro:: HMAC_SHA512_LEN Output length for `wally_hmac_sha512` .. c:macro:: PBKDF2_HMAC_SHA256_LEN Output length for `wally_pbkdf2_hmac_sha256` .. c:macro:: PBKDF2_HMAC_SHA512_LEN Output length for `wally_pbkdf2_hmac_sha512` .. c:macro:: EC_PRIVATE_KEY_LEN The length of a private key used for EC signing .. c:macro:: EC_PUBLIC_KEY_LEN The length of a public key used for EC signing .. c:macro:: EC_XONLY_PUBLIC_KEY_LEN The length of an x-only public key used for EC signing .. c:macro:: EC_PUBLIC_KEY_UNCOMPRESSED_LEN The length of an uncompressed public key .. c:macro:: EC_MESSAGE_HASH_LEN The length of a message hash to EC sign .. c:macro:: EC_SIGNATURE_LEN The length of a compact signature produced by EC signing .. c:macro:: EC_SIGNATURE_RECOVERABLE_LEN The length of a compact recoverable signature produced by EC signing .. c:macro:: EC_SIGNATURE_DER_MAX_LEN The maximum encoded length of a DER signature (High-R, High-S), excluding sighash byte .. c:macro:: 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 .. c:macro:: EC_SCALAR_LEN The length of a secp256k1 scalar value .. _ec-flags: EC signing flags ^^^^^^^^^^^^^^^^ .. c:macro:: EC_FLAG_ECDSA Indicates that a signature using ECDSA/secp256k1 is required .. c:macro:: EC_FLAG_SCHNORR Indicates that a signature using EC-Schnorr-SHA256 is required .. c:macro:: EC_FLAG_GRIND_R ECDSA only: indicates that the signature nonce should be incremented until the signature is low-R .. c:macro:: EC_FLAG_RECOVERABLE ECDSA only: Indicates that the signature is recoverable .. c:macro:: EC_FLAG_ELEMENTS Schnorr only: Indicates that the Elements/Liquid tagged hashes should be used where needed .. c:macro:: EC_FLAGS_ALL .. c:macro:: BITCOIN_MESSAGE_MAX_LEN The maximum size of input message that can be formatted .. _bitcoin-message-flags: Bitcoin message processing flags ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. c:macro:: BITCOIN_MESSAGE_FLAG_HASH Indicates that SHA256D(message) should be returned .. c:macro:: WALLY_S2C_DATA_LEN The length of a data committed using sign-to-contract (s2c) .. c:macro:: WALLY_S2C_OPENING_LEN The length of a sign-to-contract (s2c) opening