1 #ifndef WALLY_CORE_H 2 #define WALLY_CORE_H 3 4 #include <stdlib.h> 5 #include <stdint.h> 6 7 #ifdef __cplusplus 8 extern "C" { 9 #endif 10 11 #ifndef WALLY_CORE_API 12 # if defined(_WIN32) 13 # ifdef WALLY_CORE_BUILD 14 # define WALLY_CORE_API __declspec(dllexport) 15 # else 16 # define WALLY_CORE_API 17 # endif 18 # elif defined(__GNUC__) && defined(WALLY_CORE_BUILD) 19 # define WALLY_CORE_API __attribute__ ((visibility ("default"))) 20 # else 21 # define WALLY_CORE_API 22 # endif 23 #endif 24 25 /** Return codes */ 26 #define WALLY_OK 0 /** Success */ 27 #define WALLY_ERROR -1 /** General error */ 28 #define WALLY_EINVAL -2 /** Invalid argument */ 29 #define WALLY_ENOMEM -3 /** malloc() failed */ 30 31 /** 32 * Initialize wally. 33 * 34 * This function must be called once before threads are created by the application. 35 * 36 * :param flags: Flags controlling what to initialize. Currently must be zero. 37 */ 38 WALLY_CORE_API int wally_init(uint32_t flags); 39 40 /** 41 * Free any internally allocated memory. 42 * 43 * :param flags: Flags controlling what to clean up. Currently must be zero. 44 */ 45 WALLY_CORE_API int wally_cleanup(uint32_t flags); 46 47 #ifndef SWIG 48 /** 49 * Fetch the wally internal secp256k1 context object. 50 * 51 * By default, a single global context is created on demand. This behaviour 52 * can be overriden by providing a custom context fetching function when 53 * calling `wally_set_operations`. 54 */ 55 WALLY_CORE_API struct secp256k1_context_struct *wally_get_secp_context(void); 56 57 /** 58 * Create a new wally-suitable secp256k1 context object. 59 * 60 * The created context is initialised to be usable by all wally functions. 61 */ 62 WALLY_CORE_API struct secp256k1_context_struct *wally_get_new_secp_context(void); 63 64 /** 65 * Free a secp256k1 context object created by `wally_get_new_secp_context`. 66 * 67 * This function must only be called on context objects returned from 68 * `wally_get_new_secp_context`, it should not be called on the default 69 * context returned from `wally_get_secp_context`. 70 */ 71 WALLY_CORE_API void wally_secp_context_free(struct secp256k1_context_struct *ctx); 72 #endif 73 74 /** 75 * Securely wipe memory. 76 * 77 * :param bytes: Memory to wipe 78 * :param bytes_len: Size of ``bytes`` in bytes. 79 */ 80 WALLY_CORE_API int wally_bzero( 81 void *bytes, 82 size_t bytes_len); 83 84 /** 85 * Securely wipe and then free a string allocated by the library. 86 * 87 * :param str: String to free (must be NUL terminated UTF-8). 88 */ 89 WALLY_CORE_API int wally_free_string( 90 char *str); 91 92 /** Length of entropy required for ``wally_randomize_context`` */ 93 #define WALLY_SECP_RANDOMIZE_LEN 32 94 95 /** 96 * Provide entropy to randomize the libraries internal libsecp256k1 context. 97 * 98 * Random data is used in libsecp256k1 to blind the data being processed, 99 * making side channel attacks more difficult. By default, Wally uses a single 100 * internal context for secp functions that is not initially randomized. 101 * 102 * The caller should call this function before using any functions that rely on 103 * libsecp256k1 (i.e. Anything using public/private keys). If the caller 104 * has overriden the library's default libsecp context fetching using 105 * `wally_set_operations`, then it may be necessary to call this function 106 * before calling wally functions in each thread created by the caller. 107 * 108 * If wally is used in its default configuration, this function should either 109 * be called before threads are created or access to wally functions wrapped 110 * in an application level mutex. 111 * 112 * :param bytes: Entropy to use. 113 * :param bytes_len: Size of ``bytes`` in bytes. Must be ``WALLY_SECP_RANDOMIZE_LEN``. 114 */ 115 WALLY_CORE_API int wally_secp_randomize( 116 const unsigned char *bytes, 117 size_t bytes_len); 118 119 /** 120 * Convert bytes to a (lower-case) hexadecimal string. 121 * 122 * :param bytes: Bytes to convert. 123 * :param bytes_len: Size of ``bytes`` in bytes. 124 * :param output: Destination for the resulting hexadecimal string. 125 *| The string returned should be freed using `wally_free_string`. 126 */ 127 WALLY_CORE_API int wally_hex_from_bytes( 128 const unsigned char *bytes, 129 size_t bytes_len, 130 char **output); 131 132 /** 133 * Convert a hexadecimal string to bytes. 134 * 135 * :param hex: String to convert. 136 * :param bytes_out: Where to store the resulting bytes. 137 * :param len: The length of ``bytes_out`` in bytes. 138 * :param written: Destination for the number of bytes written to ``bytes_out``. 139 */ 140 WALLY_CORE_API int wally_hex_to_bytes( 141 const char *hex, 142 unsigned char *bytes_out, 143 size_t len, 144 size_t *written); 145 146 /* For ``wally_base58_from_bytes``, indicates that a checksum should 147 * be generated. For ``wally_base58_to_bytes``, indicates that the 148 * embedded checksum should be validated and stripped off the returned 149 * bytes. 150 */ 151 #define BASE58_FLAG_CHECKSUM 0x1 152 153 /** The number of extra bytes required to hold a base58 checksum */ 154 #define BASE58_CHECKSUM_LEN 4 155 156 /** 157 * Create a base 58 encoded string representing binary data. 158 * 159 * :param bytes: Binary data to convert. 160 * :param bytes_len: The length of ``bytes`` in bytes. 161 * :param flags: Pass ``BASE58_FLAG_CHECKSUM`` if ``bytes`` should have a 162 *| checksum calculated and appended before converting to base 58. 163 * :param output: Destination for the base 58 encoded string representing ``bytes``. 164 *| The string returned should be freed using `wally_free_string`. 165 */ 166 WALLY_CORE_API int wally_base58_from_bytes( 167 const unsigned char *bytes, 168 size_t bytes_len, 169 uint32_t flags, 170 char **output); 171 172 /** 173 * Decode a base 58 encoded string back into into binary data. 174 * 175 * :param str_in: Base 58 encoded string to decode. 176 * :param flags: Pass ``BASE58_FLAG_CHECKSUM`` if ``bytes_out`` should have a 177 *| checksum validated and removed before returning. In this case, ``len`` 178 *| must contain an extra ``BASE58_CHECKSUM_LEN`` bytes to calculate the 179 *| checksum into. The returned length will not include the checksum. 180 * :param bytes_out: Destination for converted binary data. 181 * :param len: The length of ``bytes_out`` in bytes. 182 * :param written: Destination for the length of the decoded bytes. 183 */ 184 WALLY_CORE_API int wally_base58_to_bytes( 185 const char *str_in, 186 uint32_t flags, 187 unsigned char *bytes_out, 188 size_t len, 189 size_t *written); 190 191 /** 192 * Return the length of a base 58 encoded string once decoded into bytes. 193 * 194 * Returns the exact number of bytes that would be required to store ``str_in`` 195 * as decoded binary, including any embedded checksum. If the string contains 196 * invalid characters then WALLY_EINVAL is returned. Note that no checksum 197 * validation takes place. 198 * 199 * In the worst case (an all zero buffer, represented by a string of '1' 200 * characters), this function will return strlen(``str_in``). You can therefore 201 * safely use the length of ``str_in`` as a buffer size to avoid calling this 202 * function in most cases. 203 * 204 * :param str_in: Base 58 encoded string to find the length of. 205 * :param written: Destination for the length of the decoded bytes. 206 * 207 */ 208 WALLY_CORE_API int wally_base58_get_length( 209 const char *str_in, 210 size_t *written); 211 212 /** 213 * Create a base64 encoded string representing binary data. 214 * 215 * :param bytes: Binary data to convert. 216 * :param bytes_len: The length of ``bytes`` in bytes. 217 * :param flags: Must be 0. 218 * :param output: Destination for the base64 encoded string representing ``bytes``. 219 *| The string returned should be freed using `wally_free_string`. 220 */ 221 WALLY_CORE_API int wally_base64_from_bytes( 222 const unsigned char *bytes, 223 size_t bytes_len, 224 uint32_t flags, 225 char **output); 226 227 /** 228 * Decode a base64 encoded string back into into binary data. 229 * 230 * :param str_in: Base64 encoded string to decode. 231 * :param flags: Must be 0. 232 * :param bytes_out: Destination for converted binary data. 233 * :param len: The length of ``bytes_out`` in bytes. See ``wally_base64_get_maximum_length`. 234 * :param written: Destination for the length of the decoded bytes. 235 */ 236 WALLY_CORE_API int wally_base64_to_bytes( 237 const char *str_in, 238 uint32_t flags, 239 unsigned char *bytes_out, 240 size_t len, 241 size_t *written); 242 243 /** 244 * Return the maximum length of a base64 encoded string once decoded into bytes. 245 * 246 * Since base64 strings may contain line breaks and padding, it is not 247 * possible to compute their decoded length without fully decoding them. 248 * This function cheaply calculates the maximum possible decoded length, 249 * which can be used to allocate a buffer for ``wally_base64_to_bytes``. 250 * In most cases the decoded data will be shorter than the value returned. 251 * 252 * :param str_in: Base64 encoded string to find the length of. 253 * :param flags: Must be 0. 254 * :param written: Destination for the maximum length of the decoded bytes. 255 * 256 */ 257 WALLY_CORE_API int wally_base64_get_maximum_length( 258 const char *str_in, 259 uint32_t flags, 260 size_t *written); 261 262 263 #ifndef SWIG 264 /** The type of an overridable function to allocate memory */ 265 typedef void *(*wally_malloc_t)( 266 size_t size); 267 268 /** The type of an overridable function to free memory */ 269 typedef void (*wally_free_t)( 270 void *ptr); 271 272 /** The type of an overridable function to clear memory */ 273 typedef void (*wally_bzero_t)( 274 void *ptr, size_t len); 275 276 /** The type of an overridable function to generate an EC nonce */ 277 typedef int (*wally_ec_nonce_t)( 278 unsigned char *nonce32, 279 const unsigned char *msg32, 280 const unsigned char *key32, 281 const unsigned char *algo16, 282 void *data, 283 unsigned int attempt 284 ); 285 286 /** The type of an overridable function to return a secp context */ 287 typedef struct secp256k1_context_struct *(*secp_context_t)( 288 void); 289 290 /** Structure holding function pointers for overridable wally operations */ 291 struct wally_operations { 292 uintptr_t struct_size; /* Must be initialised to sizeof(wally_operations) */ 293 wally_malloc_t malloc_fn; 294 wally_free_t free_fn; 295 wally_bzero_t bzero_fn; 296 wally_ec_nonce_t ec_nonce_fn; 297 secp_context_t secp_context_fn; 298 void *reserved_1; /* reserved_ pointers are reserved for future use */ 299 void *reserved_2; 300 void *reserved_3; 301 void *reserved_4; 302 }; 303 304 /** 305 * Fetch the current overridable operations used by wally. 306 * 307 * :param output: Destination for the overridable operations. 308 */ 309 WALLY_CORE_API int wally_get_operations( 310 struct wally_operations *output); 311 312 /** 313 * Set the current overridable operations used by wally. 314 * 315 * :param ops: The overridable operations to set. 316 * 317 * .. note:: Any NULL members in the passed structure are ignored. 318 */ 319 WALLY_CORE_API int wally_set_operations( 320 const struct wally_operations *ops); 321 322 #endif /* SWIG */ 323 324 /** 325 * Determine if the library was built with elements support. 326 * 327 * :param written: 1 if the library supports elements, otherwise 0. 328 */ 329 WALLY_CORE_API int wally_is_elements_build(size_t *written); 330 331 #ifdef __cplusplus 332 } 333 #endif 334 335 #endif /* WALLY_CORE_H */ 336