1 2FFI (C Binding) 3======================================== 4 5.. versionadded:: 1.11.14 6 7Botan's ffi module provides a C89 binding intended to be easily usable with other 8language's foreign function interface (FFI) libraries. For instance the included 9Python wrapper uses Python's ``ctypes`` module and the C89 API. This API is of 10course also useful for programs written directly in C. 11 12Code examples can be found in 13`the tests <https://github.com/randombit/botan/blob/master/src/tests/test_ffi.cpp>`_. 14 15Return Codes 16--------------- 17 18Almost all functions in the Botan C interface return an ``int`` error code. The 19only exceptions are a handful of functions (like 20:cpp:func:`botan_ffi_api_version`) which cannot fail in any circumstances. 21 22The FFI functions return a non-negative integer (usually 0) to indicate success, 23or a negative integer to represent an error. A few functions (like 24:cpp:func:`botan_block_cipher_block_size`) return positive integers instead of 25zero on success. 26 27The error codes returned in certain error situations may change over time. This 28especially applies to very generic errors like 29:cpp:enumerator:`BOTAN_FFI_ERROR_EXCEPTION_THROWN` and 30:cpp:enumerator:`BOTAN_FFI_ERROR_UNKNOWN_ERROR`. For instance, before 2.8, setting 31an invalid key length resulted in :cpp:enumerator:`BOTAN_FFI_ERROR_EXCEPTION_THROWN` 32but now this is specially handled and returns 33:cpp:enumerator:`BOTAN_FFI_ERROR_INVALID_KEY_LENGTH` instead. 34 35The following enum values are defined in the FFI header: 36 37.. cpp:enumerator:: BOTAN_FFI_SUCCESS = 0 38 39 Generally returned to indicate success 40 41.. cpp:enumerator:: BOTAN_FFI_INVALID_VERIFIER = 1 42 43 Note this value is positive, but still represents an error condition. In 44 indicates that the function completed successfully, but the value provided 45 was not correct. For example :cpp:func:`botan_bcrypt_is_valid` returns this 46 value if the password did not match the hash. 47 48.. cpp:enumerator:: BOTAN_FFI_ERROR_INVALID_INPUT = -1 49 50 The input was invalid. (Currently this error return is not used.) 51 52.. cpp:enumerator:: BOTAN_FFI_ERROR_BAD_MAC = -2 53 54 While decrypting in an AEAD mode, the tag failed to verify. 55 56.. cpp:enumerator:: BOTAN_FFI_ERROR_INSUFFICIENT_BUFFER_SPACE = -10 57 58 Functions which write a variable amount of space return this if the indicated 59 buffer length was insufficient to write the data. In that case, the output 60 length parameter is set to the size that is required. 61 62.. cpp:enumerator:: BOTAN_FFI_ERROR_EXCEPTION_THROWN = -20 63 64 An exception was thrown while processing this request, but no further 65 details are available. 66 67 .. note:: 68 69 If the environment variable ``BOTAN_FFI_PRINT_EXCEPTIONS`` is set to any 70 non-empty value, then any exception which is caught by the FFI layer will 71 first print the exception message to stderr before returning an 72 error. This is sometimes useful for debugging. 73 74.. cpp:enumerator:: BOTAN_FFI_ERROR_OUT_OF_MEMORY = -21 75 76 Memory allocation failed 77 78.. cpp:enumerator:: BOTAN_FFI_ERROR_BAD_FLAG = -30 79 80 A value provided in a `flag` variable was unknown. 81 82.. cpp:enumerator:: BOTAN_FFI_ERROR_NULL_POINTER = -31 83 84 A null pointer was provided as an argument where that is not allowed. 85 86.. cpp:enumerator:: BOTAN_FFI_ERROR_BAD_PARAMETER = -32 87 88 An argument did not match the function. 89 90.. cpp:enumerator:: BOTAN_FFI_ERROR_KEY_NOT_SET = -33 91 92 An object that requires a key normally must be keyed before use (eg before 93 encrypting or MACing data). If this is not done, the operation will fail and 94 return this error code. 95 96.. cpp:enumerator:: BOTAN_FFI_ERROR_INVALID_KEY_LENGTH = -34 97 98 An invalid key length was provided with a call to ``x_set_key``. 99 100.. cpp:enumerator:: BOTAN_FFI_ERROR_NOT_IMPLEMENTED = -40 101 102 This is returned if the functionality is not available for some reason. For 103 example if you call :cpp:func:`botan_hash_init` with a named hash function 104 which is not enabled, this error is returned. 105 106.. cpp:enumerator:: BOTAN_FFI_ERROR_INVALID_OBJECT = -50 107 108 This is used if an object provided did not match the function. For example 109 calling :cpp:func:`botan_hash_destroy` on a ``botan_rng_t`` object will cause 110 this return. 111 112.. cpp:enumerator:: BOTAN_FFI_ERROR_UNKNOWN_ERROR = -100 113 114 Something bad happened, but we are not sure why or how. 115 116Versioning 117---------------------------------------- 118 119.. cpp:function:: uint32_t botan_ffi_api_version() 120 121 Returns the version of the currently supported FFI API. This is 122 expressed in the form YYYYMMDD of the release date of this version 123 of the API. 124 125.. cpp:function:: int botan_ffi_supports_api(uint32_t version) 126 127 Returns 0 iff the FFI version specified is supported by this 128 library. Otherwise returns -1. The expression 129 botan_ffi_supports_api(botan_ffi_api_version()) will always 130 evaluate to 0. A particular version of the library may also support 131 other (older) versions of the FFI API. 132 133.. cpp:function:: const char* botan_version_string() 134 135 Returns a free-form string describing the version. The return 136 value is a statically allocated string. 137 138.. cpp:function:: uint32_t botan_version_major() 139 140 Returns the major version of the library 141 142.. cpp:function:: uint32_t botan_version_minor() 143 144 Returns the minor version of the library 145 146.. cpp:function:: uint32_t botan_version_patch() 147 148 Returns the patch version of the library 149 150.. cpp:function:: uint32_t botan_version_datestamp() 151 152 Returns the date this version was released as an integer YYYYMMDD, 153 or 0 if an unreleased version 154 155 156FFI Versions 157^^^^^^^^^^^^^ 158 159This maps the FFI API version to the first version of the library that 160supported it. 161 162============== =================== 163FFI Version Supported Starting 164============== =================== 16520191214 2.13.0 16620180713 2.8.0 16720170815 2.3.0 16820170327 2.1.0 16920150515 2.0.0 170============== =================== 171 172Utility Functions 173---------------------------------------- 174 175.. const char* botan_error_description(int err) 176 177 Return a string representation of the provided error code. If the error code 178 is unknown, returns the string "Unknown error". The return values are static 179 constant strings and should not be freed. 180 181.. cpp:function:: int botan_same_mem(const uint8_t* x, const uint8_t* y, size_t len) 182 183 Returns 0 if `x[0..len] == y[0..len]`, -1 otherwise. 184 185.. cpp:function:: int botan_hex_encode(const uint8_t* x, size_t len, char* out, uint32_t flags) 186 187 Performs hex encoding of binary data in *x* of size *len* bytes. 188 The output buffer *out* must be of at least *x*2* bytes in size. 189 If *flags* contains ``BOTAN_FFI_HEX_LOWER_CASE``, hex encoding 190 will only contain lower-case letters, upper-case letters otherwise. 191 Returns 0 on success, 1 otherwise. 192 193.. cpp:function:: int botan_hex_decode(const char* hex_str, size_t in_len, uint8_t* out, size_t* out_len) 194 195 Hex decode some data 196 197Random Number Generators 198---------------------------------------- 199 200.. cpp:type:: opaque* botan_rng_t 201 202 An opaque data type for a random number generator. Don't mess with it. 203 204.. cpp:function:: int botan_rng_init(botan_rng_t* rng, const char* rng_type) 205 206 Initialize a random number generator object from the given 207 *rng_type*: "system" (or ``nullptr``): ``System_RNG``, 208 "user": ``AutoSeeded_RNG``, 209 "user-threadsafe": serialized ``AutoSeeded_RNG``, 210 "null": ``Null_RNG`` (always fails), 211 "hwrnd" or "rdrand": ``Processor_RNG`` (if available) 212 213.. cpp:function:: int botan_rng_get(botan_rng_t rng, uint8_t* out, size_t out_len) 214 215 Get random bytes from a random number generator. 216 217.. cpp:function:: int botan_rng_reseed(botan_rng_t rng, size_t bits) 218 219 Reseeds the random number generator with *bits* number of bits 220 from the `System_RNG`. 221 222.. cpp:function:: int botan_rng_reseed_from_rng(botan_rng_t rng, botan_rng_t src, size_t bits) 223 224 Reseeds the random number generator with *bits* number of bits 225 taken from the given source RNG. 226 227.. cpp:function:: int botan_rng_add_entropy(botan_rng_t rng, const uint8_t seed[], size_t len) 228 229 Adds the provided seed material to the internal RNG state. 230 231 This call may be ignored by certain RNG instances (such as RDRAND 232 or, on some systems, the system RNG). 233 234.. cpp:function:: int botan_rng_destroy(botan_rng_t rng) 235 236 Destroy the object created by :cpp:func:`botan_rng_init`. 237 238Block Ciphers 239---------------------------------------- 240 241.. versionadded:: 2.1.0 242 243This is a 'raw' interface to ECB mode block ciphers. Most applications 244want the higher level cipher API which provides authenticated 245encryption. This API exists as an escape hatch for applications which 246need to implement custom primitives using a PRP. 247 248.. cpp:type:: opaque* botan_block_cipher_t 249 250 An opaque data type for a block cipher. Don't mess with it. 251 252.. cpp:function:: int botan_block_cipher_init(botan_block_cipher_t* bc, const char* cipher_name) 253 254 Create a new cipher mode object, `cipher_name` should be for example "AES-128" or "Threefish-512" 255 256.. cpp:function:: int botan_block_cipher_block_size(botan_block_cipher_t bc) 257 258 Return the block size of this cipher. 259 260.. cpp:function:: int botan_block_cipher_name(botan_block_cipher_t cipher, \ 261 char* name, size_t* name_len) 262 263 Return the name of this block cipher algorithm, which may nor may not exactly 264 match what was passed to :cpp:func:`botan_block_cipher_init`. 265 266.. cpp:function:: int botan_block_cipher_get_keyspec(botan_block_cipher_t cipher, \ 267 size_t* out_minimum_keylength, \ 268 size_t* out_maximum_keylength, \ 269 size_t* out_keylength_modulo) 270 271 Return the limits on the key which can be provided to this cipher. If any of the 272 parameters are null, no output is written to that field. This allows retrieving only 273 (say) the maximum supported keylength, if that is the only information needed. 274 275.. cpp:function:: int botan_block_cipher_clear(botan_block_cipher_t bc) 276 277 Clear the internal state (such as keys) of this cipher object, but do not deallocate it. 278 279.. cpp:function:: int botan_block_cipher_set_key(botan_block_cipher_t bc, const uint8_t key[], size_t key_len) 280 281 Set the cipher key, which is required before encrypting or decrypting. 282 283.. cpp:function:: int botan_block_cipher_encrypt_blocks(botan_block_cipher_t bc, const uint8_t in[], uint8_t out[], size_t blocks) 284 285 The key must have been set first with :cpp:func:`botan_block_cipher_set_key`. 286 Encrypt *blocks* blocks of data stored in *in* and place the ciphertext into *out*. 287 The two parameters may be the same buffer, but must not overlap. 288 289.. cpp:function:: int botan_block_cipher_decrypt_blocks(botan_block_cipher_t bc, const uint8_t in[], uint8_t out[], size_t blocks) 290 291 The key must have been set first with :cpp:func:`botan_block_cipher_set_key`. 292 Decrypt *blocks* blocks of data stored in *in* and place the ciphertext into *out*. 293 The two parameters may be the same buffer, but must not overlap. 294 295.. cpp:function:: int botan_block_cipher_destroy(botan_block_cipher_t rng) 296 297 Destroy the object created by :cpp:func:`botan_block_cipher_init`. 298 299 300Hash Functions 301---------------------------------------- 302 303.. cpp:type:: opaque* botan_hash_t 304 305 An opaque data type for a hash. Don't mess with it. 306 307.. cpp:function:: botan_hash_t botan_hash_init(const char* hash, uint32_t flags) 308 309 Creates a hash of the given name, e.g., "SHA-384". 310 Returns null on failure. Flags should always be zero in this version of the API. 311 312.. cpp:function:: int botan_hash_destroy(botan_hash_t hash) 313 314 Destroy the object created by :cpp:func:`botan_hash_init`. 315 316.. cpp:function:: int botan_hash_name(botan_hash_t hash, char* name, size_t* name_len) 317 318 Write the name of the hash function to the provided buffer. 319 320.. cpp:function:: int botan_hash_copy_state(botan_hash_t* dest, const botan_hash_t source) 321 322 Copies the state of the hash object to a new hash object. 323 324.. cpp:function:: int botan_hash_clear(botan_hash_t hash) 325 326 Reset the state of this object back to clean, as if no input has 327 been supplied. 328 329.. cpp:function:: size_t botan_hash_output_length(botan_hash_t hash) 330 331 Return the output length of the hash function. 332 333.. cpp:function:: int botan_hash_update(botan_hash_t hash, const uint8_t* input, size_t len) 334 335 Add input to the hash computation. 336 337.. cpp:function:: int botan_hash_final(botan_hash_t hash, uint8_t out[]) 338 339 Finalize the hash and place the output in out. Exactly 340 :cpp:func:`botan_hash_output_length` bytes will be written. 341 342Message Authentication Codes 343---------------------------------------- 344.. cpp:type:: opaque* botan_mac_t 345 346 An opaque data type for a MAC. Don't mess with it, but do remember 347 to set a random key first. 348 349.. cpp:function:: botan_mac_t botan_mac_init(const char* mac, uint32_t flags) 350 351 Creates a MAC of the given name, e.g., "HMAC(SHA-384)". 352 Returns null on failure. Flags should always be zero in this version of the API. 353 354.. cpp:function:: int botan_mac_destroy(botan_mac_t mac) 355 356 Destroy the object created by :cpp:func:`botan_mac_init`. 357 358.. cpp:function:: int botan_mac_clear(botan_mac_t mac) 359 360 Reset the state of this object back to clean, as if no key and input have 361 been supplied. 362 363.. cpp:function:: size_t botan_mac_output_length(botan_mac_t mac) 364 365 Return the output length of the MAC. 366 367.. cpp:function:: int botan_mac_set_key(botan_mac_t mac, const uint8_t* key, size_t key_len) 368 369 Set the random key. 370 371.. cpp:function:: int botan_mac_update(botan_mac_t mac, uint8_t buf[], size_t len) 372 373 Add input to the MAC computation. 374 375.. cpp:function:: int botan_mac_final(botan_mac_t mac, uint8_t out[], size_t* out_len) 376 377 Finalize the MAC and place the output in out. Exactly 378 :cpp:func:`botan_mac_output_length` bytes will be written. 379 380Symmetric Ciphers 381---------------------------------------- 382 383.. cpp:type:: opaque* botan_cipher_t 384 385 An opaque data type for a symmetric cipher object. Don't mess with it, but do remember 386 to set a random key first. And please use an AEAD. 387 388.. cpp:function:: botan_cipher_t botan_cipher_init(const char* cipher_name, uint32_t flags) 389 390 Create a cipher object from a name such as "AES-256/GCM" or "Serpent/OCB". 391 392 Flags is a bitfield; the low bitof ``flags`` specifies if encrypt or decrypt, 393 ie use 0 for encryption and 1 for decryption. 394 395.. cpp:function:: int botan_cipher_destroy(botan_cipher_t cipher) 396 397.. cpp:function:: int botan_cipher_clear(botan_cipher_t hash) 398 399.. cpp:function:: int botan_cipher_set_key(botan_cipher_t cipher, \ 400 const uint8_t* key, size_t key_len) 401 402.. cpp:function:: int botan_cipher_is_authenticated(botan_cipher_t cipher) 403 404.. cpp:function:: size_t botan_cipher_get_tag_length(botan_cipher_t cipher, size_t* tag_len) 405 406 Write the tag length of the cipher to ``tag_len``. This will be zero for non-authenticated 407 ciphers. 408 409.. cpp:function:: int botan_cipher_valid_nonce_length(botan_cipher_t cipher, size_t nl) 410 411 Returns 1 if the nonce length is valid, or 0 otherwise. Returns -1 on error (such as 412 the cipher object being invalid). 413 414.. cpp:function:: size_t botan_cipher_get_default_nonce_length(botan_cipher_t cipher, size_t* nl) 415 416 Return the default nonce length 417 418.. cpp:function:: int botan_cipher_set_associated_data(botan_cipher_t cipher, \ 419 const uint8_t* ad, size_t ad_len) 420 421 Set associated data. Will fail unless the cipher is an AEAD. 422 423.. cpp:function:: int botan_cipher_start(botan_cipher_t cipher, \ 424 const uint8_t* nonce, size_t nonce_len) 425 426 Start processing a message using the provided nonce. 427 428.. cpp:function:: int botan_cipher_update(botan_cipher_t cipher, \ 429 uint32_t flags, \ 430 uint8_t output[], \ 431 size_t output_size, \ 432 size_t* output_written, \ 433 const uint8_t input_bytes[], \ 434 size_t input_size, \ 435 size_t* input_consumed) 436 437 Encrypt or decrypt data. 438 439PBKDF 440---------------------------------------- 441 442.. cpp:function:: int botan_pbkdf(const char* pbkdf_algo, \ 443 uint8_t out[], size_t out_len, \ 444 const char* passphrase, \ 445 const uint8_t salt[], size_t salt_len, \ 446 size_t iterations) 447 448 Derive a key from a passphrase for a number of iterations 449 using the given PBKDF algorithm, e.g., "PBKDF2". 450 451.. cpp:function:: int botan_pbkdf_timed(const char* pbkdf_algo, \ 452 uint8_t out[], size_t out_len, \ 453 const char* passphrase, \ 454 const uint8_t salt[], size_t salt_len, \ 455 size_t milliseconds_to_run, \ 456 size_t* out_iterations_used) 457 458 Derive a key from a passphrase using the given PBKDF algorithm, 459 e.g., "PBKDF2". If *out_iterations_used* is zero, instead the 460 PBKDF is run until *milliseconds_to_run* milliseconds have passed. 461 In this case, the number of iterations run will be written to 462 *out_iterations_used*. 463 464KDF 465---------------------------------------- 466 467.. cpp:function:: int botan_kdf(const char* kdf_algo, \ 468 uint8_t out[], size_t out_len, \ 469 const uint8_t secret[], size_t secret_len, \ 470 const uint8_t salt[], size_t salt_len, \ 471 const uint8_t label[], size_t label_len) 472 473 Derive a key using the given KDF algorithm, e.g., "SP800-56C". 474 The derived key of length *out_len* bytes will be placed in *out*. 475 476Multiple Precision Integers 477---------------------------------------- 478 479.. versionadded: 2.1.0 480 481.. cpp:type:: opaque* botan_mp_t 482 483 An opaque data type for a multiple precision integer. Don't mess with it. 484 485.. cpp:function:: int botan_mp_init(botan_mp_t* mp) 486 487 Initialize a ``botan_mp_t``. Initial value is zero, use `botan_mp_set_X` to load a value. 488 489.. cpp:function:: int botan_mp_destroy(botan_mp_t mp) 490 491 Free a ``botan_mp_t`` 492 493.. cpp:function:: int botan_mp_to_hex(botan_mp_t mp, char* out) 494 495 Writes exactly ``botan_mp_num_bytes(mp)*2 + 1`` bytes to out 496 497.. cpp:function:: int botan_mp_to_str(botan_mp_t mp, uint8_t base, char* out, size_t* out_len) 498 499 Base can be either 10 or 16. 500 501.. cpp:function:: int botan_mp_set_from_int(botan_mp_t mp, int initial_value) 502 503 Set ``botan_mp_t`` from an integer value. 504 505.. cpp:function:: int botan_mp_set_from_mp(botan_mp_t dest, botan_mp_t source) 506 507 Set ``botan_mp_t`` from another MP. 508 509.. cpp:function:: int botan_mp_set_from_str(botan_mp_t dest, const char* str) 510 511 Set ``botan_mp_t`` from a string. Leading prefix of "0x" is accepted. 512 513.. cpp:function:: int botan_mp_num_bits(botan_mp_t n, size_t* bits) 514 515 Return the size of ``n`` in bits. 516 517.. cpp:function:: int botan_mp_num_bytes(botan_mp_t n, size_t* uint8_ts) 518 519 Return the size of ``n`` in bytes. 520 521.. cpp:function:: int botan_mp_to_bin(botan_mp_t mp, uint8_t vec[]) 522 523 Writes exactly ``botan_mp_num_bytes(mp)`` to ``vec``. 524 525.. cpp:function:: int botan_mp_from_bin(botan_mp_t mp, const uint8_t vec[], size_t vec_len) 526 527 Loads ``botan_mp_t`` from a binary vector (as produced by ``botan_mp_to_bin``). 528 529.. cpp:function:: int botan_mp_is_negative(botan_mp_t mp) 530 531 Return 1 if ``mp`` is negative, otherwise 0. 532 533.. cpp:function:: int botan_mp_flip_sign(botan_mp_t mp) 534 535 Flip the sign of ``mp``. 536 537.. cpp:function:: int botan_mp_add(botan_mp_t result, botan_mp_t x, botan_mp_t y) 538 539 Add two ``botan_mp_t`` and store the output in ``result``. 540 541.. cpp:function:: int botan_mp_sub(botan_mp_t result, botan_mp_t x, botan_mp_t y) 542 543 Subtract two ``botan_mp_t`` and store the output in ``result``. 544 545.. cpp:function:: int botan_mp_mul(botan_mp_t result, botan_mp_t x, botan_mp_t y) 546 547 Multiply two ``botan_mp_t`` and store the output in ``result``. 548 549.. cpp:function:: int botan_mp_div(botan_mp_t quotient, botan_mp_t remainder, \ 550 botan_mp_t x, botan_mp_t y) 551 552 Divide ``x`` by ``y`` and store the output in ``quotient`` and ``remainder``. 553 554.. cpp:function:: int botan_mp_mod_mul(botan_mp_t result, botan_mp_t x, botan_mp_t y, botan_mp_t mod) 555 556 Set ``result`` to ``x`` times ``y`` modulo ``mod``. 557 558.. cpp:function:: int botan_mp_equal(botan_mp_t x, botan_mp_t y) 559 560 Return 1 if ``x`` is equal to ``y``, 0 if ``x`` is not equal to ``y`` 561 562.. cpp:function:: int botan_mp_is_zero(const botan_mp_t x) 563 564 Return 1 if ``x`` is equal to zero, otherwise 0. 565 566.. cpp:function:: int botan_mp_is_odd(const botan_mp_t x) 567 568 Return 1 if ``x`` is odd, otherwise 0. 569 570.. cpp:function:: int botan_mp_is_even(const botan_mp_t x) 571 572 Return 1 if ``x`` is even, otherwise 0. 573 574.. cpp:function:: int botan_mp_is_positive(const botan_mp_t x) 575 576 Return 1 if ``x`` is greater than or equal to zero. 577 578.. cpp:function:: int botan_mp_is_negative(const botan_mp_t x) 579 580 Return 1 if ``x`` is less than zero. 581 582.. cpp:function:: int botan_mp_to_uint32(const botan_mp_t x, uint32_t* val) 583 584 If x fits in a 32-bit integer, set val to it and return 0. If x is out of 585 range an error is returned. 586 587.. cpp:function:: int botan_mp_cmp(int* result, botan_mp_t x, botan_mp_t y) 588 589 Three way comparison: set result to -1 if ``x`` is less than ``y``, 590 0 if ``x`` is equal to ``y``, and 1 if ``x`` is greater than ``y``. 591 592.. cpp:function:: int botan_mp_swap(botan_mp_t x, botan_mp_t y) 593 594 Swap two ``botan_mp_t`` values. 595 596.. cpp:function:: int botan_mp_powmod(botan_mp_t out, botan_mp_t base, botan_mp_t exponent, botan_mp_t modulus) 597 598 Modular exponentiation. 599 600.. cpp:function:: int botan_mp_lshift(botan_mp_t out, botan_mp_t in, size_t shift) 601 602 Left shift by specified bit count, place result in ``out``. 603 604.. cpp:function:: int botan_mp_rshift(botan_mp_t out, botan_mp_t in, size_t shift) 605 606 Right shift by specified bit count, place result in ``out``. 607 608.. cpp:function:: int botan_mp_mod_inverse(botan_mp_t out, botan_mp_t in, botan_mp_t modulus) 609 610 Compute modular inverse. If no modular inverse exists (for instance because ``in`` and 611 ``modulus`` are not relatively prime), then sets ``out`` to -1. 612 613.. cpp:function:: int botan_mp_rand_bits(botan_mp_t rand_out, botan_rng_t rng, size_t bits) 614 615 Create a random ``botan_mp_t`` of the specified bit size. 616 617.. cpp:function:: int botan_mp_rand_range(botan_mp_t rand_out, botan_rng_t rng, \ 618 botan_mp_t lower_bound, botan_mp_t upper_bound) 619 620 Create a random ``botan_mp_t`` within the provided range. 621 622.. cpp:function:: int botan_mp_gcd(botan_mp_t out, botan_mp_t x, botan_mp_t y) 623 624 Compute the greatest common divisor of ``x`` and ``y``. 625 626.. cpp:function:: int botan_mp_is_prime(botan_mp_t n, botan_rng_t rng, size_t test_prob) 627 628 Test if ``n`` is prime. The algorithm used (Miller-Rabin) is probabilistic, 629 set ``test_prob`` to the desired assurance level. For example if 630 ``test_prob`` is 64, then sufficient Miller-Rabin iterations will run to 631 assure there is at most a ``1/2**64`` chance that ``n`` is composite. 632 633.. cpp:function:: int botan_mp_get_bit(botan_mp_t n, size_t bit) 634 635 Returns 0 if the specified bit of ``n`` is not set, 1 if it is set. 636 637.. cpp:function:: int botan_mp_set_bit(botan_mp_t n, size_t bit) 638 639 Set the specified bit of ``n`` 640 641.. cpp:function:: int botan_mp_clear_bit(botan_mp_t n, size_t bit) 642 643 Clears the specified bit of ``n`` 644 645 646Password Hashing 647---------------------------------------- 648 649.. cpp:function:: int botan_bcrypt_generate(uint8_t* out, size_t* out_len, \ 650 const char* password, \ 651 botan_rng_t rng, \ 652 size_t work_factor, \ 653 uint32_t flags) 654 655 Create a password hash using Bcrypt. 656 The output buffer *out* should be of length 64 bytes. 657 The output is formatted bcrypt $2a$... 658 659.. cpp:function:: int botan_bcrypt_is_valid(const char* pass, const char* hash) 660 661 Check a previously created password hash. Returns 662 :cpp:enumerator:`BOTAN_SUCCESS` if if this password/hash 663 combination is valid, :cpp:enumerator:`BOTAN_FFI_INVALID_VERIFIER` 664 if the combination is not valid (but otherwise well formed), 665 negative on error. 666 667Public Key Creation, Import and Export 668---------------------------------------- 669 670.. cpp:type:: opaque* botan_privkey_t 671 672 An opaque data type for a private key. Don't mess with it. 673 674.. cpp:function:: int botan_privkey_create(botan_privkey_t* key, \ 675 const char* algo_name, \ 676 const char* algo_params, \ 677 botan_rng_t rng) 678 679.. cpp:function:: int botan_privkey_create_rsa(botan_privkey_t* key, botan_rng_t rng, size_t n_bits) 680 681 Create an RSA key of the given size 682 683.. cpp:function:: int botan_privkey_create_ecdsa(botan_privkey_t* key, botan_rng_t rng, const char* curve) 684 685 Create a ECDSA key of using a named curve 686 687.. cpp:function:: int botan_privkey_create_ecdh(botan_privkey_t* key, botan_rng_t rng, const char* curve) 688 689 Create a ECDH key of using a named curve 690 691.. cpp:function:: int botan_privkey_create_mceliece(botan_privkey_t* key, botan_rng_t rng, size_t n, size_t t) 692 693 Create a McEliece key using the specified parameters. See 694 :ref:`mceliece` for details on choosing parameters. 695 696.. cpp:function:: int botan_privkey_create_dh(botan_privkey_t* key, botan_rng_t rng, const char* params) 697 698 Create a finite field Diffie-Hellman key using the specified named group, for example 699 "modp/ietf/3072". 700 701.. cpp:function:: int botan_privkey_load(botan_privkey_t* key, botan_rng_t rng, \ 702 const uint8_t bits[], size_t len, \ 703 const char* password) 704 705 Load a private key. If the key is encrypted, ``password`` will be 706 used to attempt decryption. 707 708.. cpp:function:: int botan_privkey_destroy(botan_privkey_t key) 709 710 Destroy the object. 711 712.. cpp:function:: int botan_privkey_export(botan_privkey_t key, \ 713 uint8_t out[], size_t* out_len, \ 714 uint32_t flags) 715 716 Export a public key. If flags is 1 then PEM format is used. 717 718.. cpp:function:: int botan_privkey_export_encrypted(botan_privkey_t key, \ 719 uint8_t out[], size_t* out_len, \ 720 botan_rng_t rng, \ 721 const char* passphrase, \ 722 const char* encryption_algo, \ 723 uint32_t flags) 724 725 Deprecated, use ``botan_privkey_export_encrypted_msec`` or ``botan_privkey_export_encrypted_iter`` 726 727.. cpp::function:: int botan_privkey_export_encrypted_pbkdf_msec(botan_privkey_t key, 728 uint8_t out[], size_t* out_len, \ 729 botan_rng_t rng, \ 730 const char* passphrase, \ 731 uint32_t pbkdf_msec_runtime, \ 732 size_t* pbkdf_iterations_out, \ 733 const char* cipher_algo, \ 734 const char* pbkdf_algo, \ 735 uint32_t flags); 736 737 Encrypt a key, running the key derivation function for ``pbkdf_msec_runtime`` milliseconds. 738 Returns the number of iterations used in ``pbkdf_iterations_out``. 739 740 ``cipher_algo`` must specify a CBC mode cipher (such as "AES-128/CBC") or as 741 a Botan-specific extension a GCM mode may be used. 742 743.. cpp::function:: int botan_privkey_export_encrypted_pbkdf_iter(botan_privkey_t key, \ 744 uint8_t out[], size_t* out_len, \ 745 botan_rng_t rng, \ 746 const char* passphrase, \ 747 size_t pbkdf_iterations, \ 748 const char* cipher_algo, \ 749 const char* pbkdf_algo, \ 750 uint32_t flags); 751 752 Encrypt a private key. The PBKDF function runs for the specified number of iterations. 753 At least 100,000 is recommended. 754 755.. cpp:function:: int botan_privkey_export_pubkey(botan_pubkey_t* out, botan_privkey_t in) 756 757.. cpp:function:: int botan_privkey_get_field(botan_mp_t output, \ 758 botan_privkey_t key, \ 759 const char* field_name) 760 761 Read an algorithm specific field from the private key object, placing it into output. 762 For example "p" or "q" for RSA keys, or "x" for DSA keys or ECC keys. 763 764.. cpp:type:: opaque* botan_pubkey_t 765 766 An opaque data type for a public key. Don't mess with it. 767 768.. cpp:function:: int botan_pubkey_load(botan_pubkey_t* key, const uint8_t bits[], size_t len) 769 770.. cpp:function:: int botan_pubkey_export(botan_pubkey_t key, uint8_t out[], size_t* out_len, uint32_t flags) 771 772.. cpp:function:: int botan_pubkey_algo_name(botan_pubkey_t key, char out[], size_t* out_len) 773 774.. cpp:function:: int botan_pubkey_estimated_strength(botan_pubkey_t key, size_t* estimate) 775 776.. cpp:function:: int botan_pubkey_fingerprint(botan_pubkey_t key, const char* hash, \ 777 uint8_t out[], size_t* out_len) 778 779.. cpp:function:: int botan_pubkey_destroy(botan_pubkey_t key) 780 781.. cpp:function:: int botan_pubkey_get_field(botan_mp_t output, \ 782 botan_pubkey_t key, \ 783 const char* field_name) 784 785 Read an algorithm specific field from the public key object, placing it into output. 786 For example "n" or "e" for RSA keys or "p", "q", "g", and "y" for DSA keys. 787 788RSA specific functions 789---------------------------------------- 790 791.. cpp:function:: int botan_privkey_rsa_get_p(botan_mp_t p, botan_privkey_t rsa_key) 792 793 Set ``p`` to the first RSA prime. 794 795.. cpp:function:: int botan_privkey_rsa_get_q(botan_mp_t q, botan_privkey_t rsa_key) 796 797 Set ``q`` to the second RSA prime. 798 799.. cpp:function:: int botan_privkey_rsa_get_d(botan_mp_t d, botan_privkey_t rsa_key) 800 801 Set ``d`` to the RSA private exponent. 802 803.. cpp:function:: int botan_privkey_rsa_get_n(botan_mp_t n, botan_privkey_t rsa_key) 804 805 Set ``n`` to the RSA modulus. 806 807.. cpp:function:: int botan_privkey_rsa_get_e(botan_mp_t e, botan_privkey_t rsa_key) 808 809 Set ``e`` to the RSA public exponent. 810 811.. cpp:function:: int botan_pubkey_rsa_get_e(botan_mp_t e, botan_pubkey_t rsa_key) 812 813 Set ``e`` to the RSA public exponent. 814 815.. cpp:function:: int botan_pubkey_rsa_get_n(botan_mp_t n, botan_pubkey_t rsa_key) 816 817 Set ``n`` to the RSA modulus. 818 819.. cpp:function:: int botan_privkey_load_rsa(botan_privkey_t* key, \ 820 botan_mp_t p, botan_mp_t q, botan_mp_t e) 821 822 Initialize a private RSA key using parameters p, q, and e. 823 824.. cpp:function:: int botan_pubkey_load_rsa(botan_pubkey_t* key, \ 825 botan_mp_t n, botan_mp_t e) 826 827 Initialize a public RSA key using parameters n and e. 828 829DSA specific functions 830---------------------------------------- 831 832.. cpp:function:: int botan_privkey_load_dsa(botan_privkey_t* key, \ 833 botan_mp_t p, botan_mp_t q, botan_mp_t g, botan_mp_t x) 834 835 Initialize a private DSA key using group parameters p, q, and g and private key x. 836 837.. cpp:function:: int botan_pubkey_load_dsa(botan_pubkey_t* key, \ 838 botan_mp_t p, botan_mp_t q, botan_mp_t g, botan_mp_t y) 839 840 Initialize a private DSA key using group parameters p, q, and g and public key y. 841 842ElGamal specific functions 843---------------------------------------- 844 845.. cpp:function:: int botan_privkey_load_elgamal(botan_privkey_t* key, \ 846 botan_mp_t p, botan_mp_t g, botan_mp_t x) 847 848 Initialize a private ElGamal key using group parameters p and g and private key x. 849 850.. cpp:function:: int botan_pubkey_load_elgamal(botan_pubkey_t* key, \ 851 botan_mp_t p, botan_mp_t g, botan_mp_t y) 852 853 Initialize a public ElGamal key using group parameters p and g and public key y. 854 855Diffie-Hellman specific functions 856---------------------------------------- 857 858.. cpp:function:: int botan_privkey_load_dh(botan_privkey_t* key, \ 859 botan_mp_t p, botan_mp_t g, botan_mp_t x) 860 861 Initialize a private Diffie-Hellman key using group parameters p and g and private key x. 862 863.. cpp:function:: int botan_pubkey_load_dh(botan_pubkey_t* key, \ 864 botan_mp_t p, botan_mp_t g, botan_mp_t y) 865 866 Initialize a public Diffie-Hellman key using group parameters p and g and public key y. 867 868Public Key Encryption/Decryption 869---------------------------------------- 870 871.. cpp:type:: opaque* botan_pk_op_encrypt_t 872 873 An opaque data type for an encryption operation. Don't mess with it. 874 875.. cpp:function:: int botan_pk_op_encrypt_create(botan_pk_op_encrypt_t* op, \ 876 botan_pubkey_t key, \ 877 const char* padding, \ 878 uint32_t flags) 879 880 Create a new operation object which can be used to encrypt using the provided 881 key and the specified padding scheme (such as "OAEP(SHA-256)" for use with 882 RSA). Flags should be 0 in this version. 883 884.. cpp:function:: int botan_pk_op_encrypt_destroy(botan_pk_op_encrypt_t op) 885 886 Destroy the object. 887 888.. cpp:function:: int botan_pk_op_encrypt_output_length(botan_pk_op_encrypt_t op, \ 889 size_t ptext_len, size_t* ctext_len) 890 891 Returns an upper bound on the output length if a plaintext of length ``ptext_len`` 892 is encrypted with this key/parameter setting. This allows correctly sizing the 893 buffer that is passed to :cpp:func:`botan_pk_op_encrypt`. 894 895.. cpp:function:: int botan_pk_op_encrypt(botan_pk_op_encrypt_t op, \ 896 botan_rng_t rng, \ 897 uint8_t out[], size_t* out_len, \ 898 const uint8_t plaintext[], size_t plaintext_len) 899 900 Encrypt the provided data using the key, placing the output in `out`. If 901 `out` is NULL, writes the length of what the ciphertext would have been to 902 `*out_len`. However this is computationally expensive (the encryption 903 actually occurs, then the result is discarded), so it is better to use 904 :cpp:func:`botan_pk_op_encrypt_output_length` to correctly size the buffer. 905 906.. cpp:type:: opaque* botan_pk_op_decrypt_t 907 908 An opaque data type for a decryption operation. Don't mess with it. 909 910.. cpp:function:: int botan_pk_op_decrypt_create(botan_pk_op_decrypt_t* op, \ 911 botan_privkey_t key, \ 912 const char* padding, \ 913 uint32_t flags) 914 915.. cpp:function:: int botan_pk_op_decrypt_destroy(botan_pk_op_decrypt_t op) 916 917.. cpp:function:: int botan_pk_op_decrypt_output_length(botan_pk_op_decrypt_t op, \ 918 size_t ctext_len, size_t* ptext_len) 919 920 For a given ciphertext length, returns the upper bound on the size of the 921 plaintext that might be enclosed. This allows properly sizing the output 922 buffer passed to :cpp:func:`botan_pk_op_decrypt`. 923 924.. cpp:function:: int botan_pk_op_decrypt(botan_pk_op_decrypt_t op, \ 925 uint8_t out[], size_t* out_len, \ 926 uint8_t ciphertext[], size_t ciphertext_len) 927 928Signature Generation 929---------------------------------------- 930 931.. cpp:type:: opaque* botan_pk_op_sign_t 932 933 An opaque data type for a signature generation operation. Don't mess with it. 934 935.. cpp:function:: int botan_pk_op_sign_create(botan_pk_op_sign_t* op, \ 936 botan_privkey_t key, \ 937 const char* hash_and_padding, \ 938 uint32_t flags) 939 940 Create a signature operator for the provided key. The padding string 941 specifies what hash function and padding should be used, for example 942 "PKCS1v15(SHA-256)" or "EMSA1(SHA-384)". 943 944.. cpp:function:: int botan_pk_op_sign_destroy(botan_pk_op_sign_t op) 945 946 Destroy an object created by :cpp:func:`botan_pk_op_sign_create`. 947 948.. cpp:function:: int botan_pk_op_sign_output_length(botan_pk_op_sign_t op, size_t* sig_len) 949 950 Writes the length of the signatures that this signer will produce. This 951 allows properly sizing the buffer passed to 952 :cpp:func:`botan_pk_op_sign_finish`. 953 954.. cpp:function:: int botan_pk_op_sign_update(botan_pk_op_sign_t op, \ 955 const uint8_t in[], size_t in_len) 956 957 Add bytes of the message to be signed. 958 959.. cpp:function:: int botan_pk_op_sign_finish(botan_pk_op_sign_t op, botan_rng_t rng, \ 960 uint8_t sig[], size_t* sig_len) 961 962 Produce a signature over all of the bytes passed to :cpp:func:`botan_pk_op_sign_update`. 963 Afterwards, the sign operator is reset and may be used to sign a new message. 964 965Signature Verification 966---------------------------------------- 967 968.. cpp:type:: opaque* botan_pk_op_verify_t 969 970 An opaque data type for a signature verification operation. Don't mess with it. 971 972.. cpp:function:: int botan_pk_op_verify_create(botan_pk_op_verify_t* op, \ 973 botan_pubkey_t key, \ 974 const char* hash_and_padding, \ 975 uint32_t flags) 976 977.. cpp:function:: int botan_pk_op_verify_destroy(botan_pk_op_verify_t op) 978 979.. cpp:function:: int botan_pk_op_verify_update(botan_pk_op_verify_t op, \ 980 const uint8_t in[], size_t in_len) 981 982 Add bytes of the message to be verified 983 984.. cpp:function:: int botan_pk_op_verify_finish(botan_pk_op_verify_t op, \ 985 const uint8_t sig[], size_t sig_len) 986 987 Verify if the signature provided matches with the message provided as calls 988 to :cpp:func:`botan_pk_op_verify_update`. 989 990Key Agreement 991---------------------------------------- 992 993.. cpp:type:: opaque* botan_pk_op_ka_t 994 995 An opaque data type for a key agreement operation. Don't mess with it. 996 997.. cpp:function:: int botan_pk_op_key_agreement_create(botan_pk_op_ka_t* op, \ 998 botan_privkey_t key, \ 999 const char* kdf, \ 1000 uint32_t flags) 1001 1002.. cpp:function:: int botan_pk_op_key_agreement_destroy(botan_pk_op_ka_t op) 1003 1004.. cpp:function:: int botan_pk_op_key_agreement_export_public(botan_privkey_t key, \ 1005 uint8_t out[], size_t* out_len) 1006 1007.. cpp:function:: int botan_pk_op_key_agreement(botan_pk_op_ka_t op, \ 1008 uint8_t out[], size_t* out_len, \ 1009 const uint8_t other_key[], size_t other_key_len, \ 1010 const uint8_t salt[], size_t salt_len) 1011 1012.. cpp:function:: int botan_mceies_encrypt(botan_pubkey_t mce_key, \ 1013 botan_rng_t rng, \ 1014 const char* aead, \ 1015 const uint8_t pt[], size_t pt_len, \ 1016 const uint8_t ad[], size_t ad_len, \ 1017 uint8_t ct[], size_t* ct_len) 1018 1019.. cpp:function:: int botan_mceies_decrypt(botan_privkey_t mce_key, \ 1020 const char* aead, \ 1021 const uint8_t ct[], size_t ct_len, \ 1022 const uint8_t ad[], size_t ad_len, \ 1023 uint8_t pt[], size_t* pt_len) 1024 1025X.509 Certificates 1026---------------------------------------- 1027 1028.. cpp:type:: opaque* botan_x509_cert_t 1029 1030 An opaque data type for an X.509 certificate. Don't mess with it. 1031 1032.. cpp:function:: int botan_x509_cert_load(botan_x509_cert_t* cert_obj, \ 1033 const uint8_t cert[], size_t cert_len) 1034 1035 Load a certificate from the DER or PEM representation 1036 1037.. cpp:function:: int botan_x509_cert_load_file(botan_x509_cert_t* cert_obj, const char* filename) 1038 1039 Load a certificate from a file. 1040 1041.. cpp:function:: int botan_x509_cert_dup(botan_x509_cert_t* cert_obj, botan_x509_cert_t cert) 1042 1043 Create a new object that refers to the same certificate. 1044 1045.. cpp:function:: int botan_x509_cert_destroy(botan_x509_cert_t cert) 1046 1047 Destroy the certificate object 1048 1049.. cpp:function:: int botan_x509_cert_gen_selfsigned(botan_x509_cert_t* cert, \ 1050 botan_privkey_t key, \ 1051 botan_rng_t rng, \ 1052 const char* common_name, \ 1053 const char* org_name) 1054 1055.. cpp:function:: int botan_x509_cert_get_time_starts(botan_x509_cert_t cert, char out[], size_t* out_len) 1056 1057 Return the time the certificate becomes valid, as a string in form 1058 "YYYYMMDDHHMMSSZ" where Z is a literal character reflecting that this time is 1059 relative to UTC. Prefer :cpp:func:`botan_x509_cert_not_before`. 1060 1061.. cpp:function:: int botan_x509_cert_get_time_expires(botan_x509_cert_t cert, char out[], size_t* out_len) 1062 1063 Return the time the certificate expires, as a string in form 1064 "YYYYMMDDHHMMSSZ" where Z is a literal character reflecting that this time is 1065 relative to UTC. Prefer :cpp:func:`botan_x509_cert_not_after`. 1066 1067.. cpp:function:: int botan_x509_cert_not_before(botan_x509_cert_t cert, uint64_t* time_since_epoch) 1068 1069 Return the time the certificate becomes valid, as seconds since epoch. 1070 1071.. cpp:function:: int botan_x509_cert_not_after(botan_x509_cert_t cert, uint64_t* time_since_epoch) 1072 1073 Return the time the certificate expires, as seconds since epoch. 1074 1075.. cpp:function:: int botan_x509_cert_get_fingerprint(botan_x509_cert_t cert, const char* hash, uint8_t out[], size_t* out_len) 1076 1077.. cpp:function:: int botan_x509_cert_get_serial_number(botan_x509_cert_t cert, uint8_t out[], size_t* out_len) 1078 1079 Return the serial number of the certificate. 1080 1081.. cpp:function:: int botan_x509_cert_get_authority_key_id(botan_x509_cert_t cert, uint8_t out[], size_t* out_len) 1082 1083 Return the authority key ID set in the certificate, which may be empty. 1084 1085.. cpp:function:: int botan_x509_cert_get_subject_key_id(botan_x509_cert_t cert, uint8_t out[], size_t* out_len) 1086 1087 Return the subject key ID set in the certificate, which may be empty. 1088 1089.. cpp:function:: int botan_x509_cert_get_public_key_bits(botan_x509_cert_t cert, \ 1090 uint8_t out[], size_t* out_len) 1091 1092 Get the serialized representation of the public key included in this certificate 1093 1094.. cpp:function:: int botan_x509_cert_get_public_key(botan_x509_cert_t cert, botan_pubkey_t* key) 1095 1096 Get the public key included in this certificate as a newly allocated object 1097 1098.. cpp:function:: int botan_x509_cert_get_issuer_dn(botan_x509_cert_t cert, \ 1099 const char* key, size_t index, \ 1100 uint8_t out[], size_t* out_len) 1101 1102 Get a value from the issuer DN field. 1103 1104.. cpp:function:: int botan_x509_cert_get_subject_dn(botan_x509_cert_t cert, \ 1105 const char* key, size_t index, \ 1106 uint8_t out[], size_t* out_len) 1107 1108 Get a value from the subject DN field. 1109 1110.. cpp:function:: int botan_x509_cert_to_string(botan_x509_cert_t cert, char out[], size_t* out_len) 1111 1112 Format the certificate as a free-form string. 1113 1114.. cpp:enum:: botan_x509_cert_key_constraints 1115 1116 Certificate key usage constraints. Allowed values: `NO_CONSTRAINTS`, 1117 `DIGITAL_SIGNATURE`, `NON_REPUDIATION`, `KEY_ENCIPHERMENT`, 1118 `DATA_ENCIPHERMENT`, `KEY_AGREEMENT`, `KEY_CERT_SIGN`, 1119 `CRL_SIGN`, `ENCIPHER_ONLY`, `DECIPHER_ONLY`. 1120 1121.. cpp:function:: int botan_x509_cert_allowed_usage(botan_x509_cert_t cert, unsigned int key_usage) 1122 1123 1124.. cpp:function:: int botan_x509_cert_verify(int* validation_result, \ 1125 botan_x509_cert_t cert, \ 1126 const botan_x509_cert_t* intermediates, \ 1127 size_t intermediates_len, \ 1128 const botan_x509_cert_t* trusted, \ 1129 size_t trusted_len, \ 1130 const char* trusted_path, \ 1131 size_t required_strength, \ 1132 const char* hostname, \ 1133 uint64_t reference_time) 1134 1135 Verify a certificate. Returns 0 if validation was successful, 1 if 1136 unsuccessful, or negative on error. 1137 1138 Sets ``validation_result`` to a code that provides more information. 1139 1140 If not needed, set ``intermediates`` to NULL and ``intermediates_len`` to 1141 zero. 1142 1143 If not needed, set ``trusted`` to NULL and ``trusted_len`` to zero. 1144 1145 The ``trusted_path`` refers to a directory where one or more trusted CA 1146 certificates are stored. It may be NULL if not needed. 1147 1148 Set ``required_strength`` to indicate the minimum key and hash strength 1149 that is allowed. For instance setting to 80 allows 1024-bit RSA and SHA-1. 1150 Setting to 110 requires 2048-bit RSA and SHA-256 or higher. Set to zero 1151 to accept a default. 1152 1153 Set ``reference_time`` to be the time which the certificate chain is 1154 validated against. Use zero to use the current system clock. 1155 1156.. cpp:function:: int botan_x509_cert_verify_with_crl(int* validation_result, \ 1157 botan_x509_cert_t cert, \ 1158 const botan_x509_cert_t* intermediates, \ 1159 size_t intermediates_len, \ 1160 const botan_x509_cert_t* trusted, \ 1161 size_t trusted_len, \ 1162 const botan_x509_crl_t* crls, \ 1163 size_t crls_len, \ 1164 const char* trusted_path, \ 1165 size_t required_strength, \ 1166 const char* hostname, \ 1167 uint64_t reference_time) 1168 1169 Certificate path validation supporting Certificate Revocation Lists. 1170 1171 Works the same as ``botan_x509_cert_cerify``. 1172 1173 ``crls`` is an array of ``botan_x509_crl_t`` objects, ``crls_len`` is its length. 1174 1175.. cpp:function:: const char* botan_x509_cert_validation_status(int code) 1176 1177 Return a (statically allocated) string associated with the verification 1178 result. 1179 1180X.509 Certificate Revocation Lists 1181---------------------------------------- 1182 1183.. cpp:type:: opaque* botan_x509_crl_t 1184 1185 An opaque data type for an X.509 CRL. 1186 1187.. cpp:function:: int botan_x509_crl_load(botan_x509_crl_t* crl_obj, \ 1188 const uint8_t crl[], size_t crl_len) 1189 1190 Load a CRL from the DER or PEM representation. 1191 1192.. cpp:function:: int botan_x509_crl_load_file(botan_x509_crl_t* crl_obj, const char* filename) 1193 1194 Load a CRL from a file. 1195 1196.. cpp:function:: int botan_x509_crl_destroy(botan_x509_crl_t crl) 1197 1198 Destroy the CRL object. 1199 1200.. cpp:function:: int botan_x509_is_revoked(botan_x509_crl_t crl, botan_x509_cert_t cert) 1201 1202 Check whether a given ``crl`` contains a given ``cert``. 1203 Return ``0`` when the certificate is revoked, ``-1`` otherwise. 1204