Botan  1.11.15
src/lib/ffi/ffi.h
Go to the documentation of this file.
00001 /*
00002 * (C) 2015 Jack Lloyd
00003 *
00004 * Botan is released under the Simplified BSD License (see license.txt)
00005 */
00006 
00007 #ifndef BOTAN_FFI_H__
00008 #define BOTAN_FFI_H__
00009 
00010 #ifdef __cplusplus
00011 extern "C" {
00012 #endif
00013 
00014 #include <botan/build.h>
00015 #include <stdint.h>
00016 #include <stddef.h>
00017 
00018 /*
00019 * TODO:
00020 * - Better error reporting
00021 * - User callback for exception logging
00022 * - Doxygen comments for all functions/params
00023 * - X.509 certs and PKIX path validation goo
00024 * - TLS
00025 */
00026 
00027 /*
00028 * Versioning
00029 */
00030 BOTAN_DLL uint32_t botan_ffi_api_version();
00031 
00032 BOTAN_DLL const char* botan_version_string();
00033 BOTAN_DLL uint32_t botan_version_major();
00034 BOTAN_DLL uint32_t botan_version_minor();
00035 BOTAN_DLL uint32_t botan_version_patch();
00036 BOTAN_DLL uint32_t botan_version_datestamp();
00037 
00038 /*
00039 * Error handling
00040 */
00041 #define BOTAN_FFI_ERROR_EXCEPTION_THROWN (-20)
00042 #define BOTAN_FFI_ERROR_BAD_FLAG (-30)
00043 #define BOTAN_FFI_ERROR_NULL_POINTER (-31)
00044 #define BOTAN_FFI_ERROR_NULL_POINTER (-31)
00045 
00046 //const char* botan_error_description(int err);
00047 
00048 /*
00049 * Utility
00050 */
00051 BOTAN_DLL int botan_same_mem(const uint8_t* x, const uint8_t* y, size_t len);
00052 
00053 /*
00054 * RNG
00055 */
00056 typedef struct botan_rng_struct* botan_rng_t;
00057 
00058 BOTAN_DLL int botan_rng_init(botan_rng_t* rng, const char* rng_type);
00059 BOTAN_DLL int botan_rng_get(botan_rng_t rng, uint8_t* out, size_t out_len);
00060 BOTAN_DLL int botan_rng_reseed(botan_rng_t rng, size_t bits);
00061 BOTAN_DLL int botan_rng_destroy(botan_rng_t rng);
00062 
00063 /*
00064 * Hashing
00065 */
00066 typedef struct botan_hash_struct* botan_hash_t;
00067 
00068 BOTAN_DLL int botan_hash_init(botan_hash_t* hash, const char* hash_name, uint32_t flags);
00069 BOTAN_DLL int botan_hash_output_length(botan_hash_t hash, size_t* output_length);
00070 BOTAN_DLL int botan_hash_update(botan_hash_t hash, const uint8_t* in, size_t in_len);
00071 BOTAN_DLL int botan_hash_final(botan_hash_t hash, uint8_t out[]);
00072 BOTAN_DLL int botan_hash_clear(botan_hash_t hash);
00073 BOTAN_DLL int botan_hash_destroy(botan_hash_t hash);
00074 
00075 /*
00076 * Message Authentication
00077 */
00078 typedef struct botan_mac_struct* botan_mac_t;
00079 
00080 BOTAN_DLL int botan_mac_init(botan_mac_t* mac, const char* mac_name, uint32_t flags);
00081 BOTAN_DLL int botan_mac_output_length(botan_mac_t mac, size_t* output_length);
00082 BOTAN_DLL int botan_mac_set_key(botan_mac_t mac, const uint8_t* key, size_t key_len);
00083 BOTAN_DLL int botan_mac_update(botan_mac_t mac, const uint8_t* buf, size_t len);
00084 BOTAN_DLL int botan_mac_final(botan_mac_t mac, uint8_t out[]);
00085 BOTAN_DLL int botan_mac_clear(botan_mac_t hash);
00086 BOTAN_DLL int botan_mac_destroy(botan_mac_t mac);
00087 
00088 /*
00089 * Cipher modes
00090 */
00091 typedef struct botan_cipher_struct* botan_cipher_t;
00092 
00093 #define BOTAN_CIPHER_INIT_FLAG_MASK_DIRECTION 1
00094 #define BOTAN_CIPHER_INIT_FLAG_ENCRYPT 0
00095 #define BOTAN_CIPHER_INIT_FLAG_DECRYPT 1
00096 
00097 BOTAN_DLL int botan_cipher_init(botan_cipher_t* cipher, const char* name, uint32_t flags);
00098 
00099 BOTAN_DLL int botan_cipher_valid_nonce_length(botan_cipher_t cipher, size_t nl);
00100 BOTAN_DLL int botan_cipher_get_tag_length(botan_cipher_t cipher, size_t* tag_size);
00101 BOTAN_DLL int botan_cipher_get_default_nonce_length(botan_cipher_t cipher, size_t* nl);
00102 
00103 BOTAN_DLL int botan_cipher_set_key(botan_cipher_t cipher,
00104                                    const uint8_t* key, size_t key_len);
00105 
00106 BOTAN_DLL int botan_cipher_set_associated_data(botan_cipher_t cipher,
00107                                                const uint8_t* ad, size_t ad_len);
00108 
00109 BOTAN_DLL int botan_cipher_start(botan_cipher_t cipher,
00110                                  const uint8_t* nonce, size_t nonce_len);
00111 
00112 #define BOTAN_CIPHER_UPDATE_FLAG_FINAL (1U << 0)
00113 
00114 BOTAN_DLL int botan_cipher_update(botan_cipher_t cipher,
00115                                   uint32_t flags,
00116                                   uint8_t output[],
00117                                   size_t output_size,
00118                                   size_t* output_written,
00119                                   const uint8_t input_bytes[],
00120                                   size_t input_size,
00121                                   size_t* input_consumed);
00122 
00123 BOTAN_DLL int botan_cipher_clear(botan_cipher_t hash);
00124 BOTAN_DLL int botan_cipher_destroy(botan_cipher_t cipher);
00125 
00126 /*
00127 * PBKDF
00128 */
00129 BOTAN_DLL int botan_pbkdf(const char* pbkdf_algo,
00130                           uint8_t out[], size_t out_len,
00131                           const char* password,
00132                           const uint8_t salt[], size_t salt_len,
00133                           size_t iterations);
00134 
00135 BOTAN_DLL int botan_pbkdf_timed(const char* pbkdf_algo,
00136                                 uint8_t out[], size_t out_len,
00137                                 const char* password,
00138                                 const uint8_t salt[], size_t salt_len,
00139                                 size_t milliseconds_to_run,
00140                                 size_t* out_iterations_used);
00141 
00142 /*
00143 * KDF
00144 */
00145 BOTAN_DLL int botan_kdf(const char* kdf_algo,
00146                         uint8_t out[], size_t out_len,
00147                         const uint8_t secret[], size_t secret_len,
00148                         const uint8_t salt[], size_t salt_len);
00149 
00150 /*
00151 * Bcrypt
00152 */
00153 #if defined(BOTAN_HAS_BCRYPT)
00154 
00155 BOTAN_DLL int botan_bcrypt_generate(uint8_t* out, size_t* out_len,
00156                                     const char* pass,
00157                                     botan_rng_t rng,
00158                                     size_t work_factor,
00159                                     uint32_t flags);
00160 
00161 /**
00162 * Returns 0 if if this password/hash combination is valid
00163 * Returns 1 if the combination is not valid (but otherwise well formed)
00164 * Returns negative on error
00165 */
00166 BOTAN_DLL int botan_bcrypt_is_valid(const char* pass, const char* hash);
00167 
00168 #endif
00169 
00170 /*
00171 * Public/private key creation, import, ...
00172 */
00173 typedef struct botan_privkey_struct* botan_privkey_t;
00174 
00175 BOTAN_DLL int botan_privkey_create_rsa(botan_privkey_t* key, botan_rng_t rng, size_t n_bits);
00176 //BOTAN_DLL int botan_privkey_create_dsa(botan_privkey_t* key, botan_rng_t rng, size_t p_bits, size_t q_bits);
00177 //BOTAN_DLL int botan_privkey_create_dh(botan_privkey_t* key, botan_rng_t rng, size_t p_bits);
00178 BOTAN_DLL int botan_privkey_create_ecdsa(botan_privkey_t* key, botan_rng_t rng, const char* params);
00179 BOTAN_DLL int botan_privkey_create_ecdh(botan_privkey_t* key, botan_rng_t rng, const char* params);
00180 //BOTAN_DLL int botan_privkey_create_mceliece(botan_privkey_t* key, botan_rng_t rng, size_t n, size_t t);
00181 
00182 /*
00183 * Input currently assumed to be PKCS #8 structure;
00184 * Set password to NULL to indicate no encryption expected
00185 */
00186 BOTAN_DLL int botan_privkey_load(botan_privkey_t* key, botan_rng_t rng,
00187                                  const uint8_t bits[], size_t len,
00188                                  const char* password);
00189 
00190 BOTAN_DLL int botan_privkey_destroy(botan_privkey_t key);
00191 
00192 #define BOTAN_PRIVKEY_EXPORT_FLAG_DER 0
00193 #define BOTAN_PRIVKEY_EXPORT_FLAG_PEM 1
00194 
00195 /*
00196 * On input *out_len is number of bytes in out[]
00197 * On output *out_len is number of bytes written (or required)
00198 * If out is not big enough no output is written, *out_len is set and 1 is returned
00199 * Returns 0 on success and sets
00200 * If some other error occurs a negative integer is returned.
00201 */
00202 BOTAN_DLL int botan_privkey_export(botan_privkey_t key,
00203                                    uint8_t out[], size_t* out_len,
00204                                    uint32_t flags);
00205 
00206 /*
00207 * Set encryption_algo to NULL or "" to have the library choose a default (recommended)
00208 */
00209 BOTAN_DLL int botan_privkey_export_encrypted(botan_privkey_t key,
00210                                              uint8_t out[], size_t* out_len,
00211                                              botan_rng_t rng,
00212                                              const char* passphrase,
00213                                              const char* encryption_algo,
00214                                              uint32_t flags);
00215 
00216 typedef struct botan_pubkey_struct* botan_pubkey_t;
00217 
00218 BOTAN_DLL int botan_pubkey_load(botan_pubkey_t* key, const uint8_t bits[], size_t len);
00219 
00220 BOTAN_DLL int botan_privkey_export_pubkey(botan_pubkey_t* out, botan_privkey_t in);
00221 
00222 BOTAN_DLL int botan_pubkey_export(botan_pubkey_t key, uint8_t out[], size_t* out_len, uint32_t flags);
00223 
00224 BOTAN_DLL int botan_pubkey_algo_name(botan_pubkey_t key, char out[], size_t* out_len);
00225 
00226 BOTAN_DLL int botan_pubkey_estimated_strength(botan_pubkey_t key, size_t* estimate);
00227 
00228 BOTAN_DLL int botan_pubkey_fingerprint(botan_pubkey_t key, const char* hash,
00229                                        uint8_t out[], size_t* out_len);
00230 
00231 BOTAN_DLL int botan_pubkey_destroy(botan_privkey_t key);
00232 
00233 
00234 /*
00235 * Public Key Encryption
00236 */
00237 typedef struct botan_pk_op_encrypt_struct* botan_pk_op_encrypt_t;
00238 
00239 BOTAN_DLL int botan_pk_op_encrypt_create(botan_pk_op_encrypt_t* op,
00240                                          botan_pubkey_t key,
00241                                          const char* padding,
00242                                          uint32_t flags);
00243 
00244 BOTAN_DLL int botan_pk_op_encrypt_destroy(botan_pk_op_encrypt_t op);
00245 
00246 BOTAN_DLL int botan_pk_op_encrypt(botan_pk_op_encrypt_t op,
00247                                   botan_rng_t rng,
00248                                   uint8_t out[], size_t* out_len,
00249                                   const uint8_t plaintext[], size_t plaintext_len);
00250 
00251 /*
00252 * Public Key Decryption
00253 */
00254 typedef struct botan_pk_op_decrypt_struct* botan_pk_op_decrypt_t;
00255 
00256 BOTAN_DLL int botan_pk_op_decrypt_create(botan_pk_op_decrypt_t* op,
00257                                          botan_privkey_t key,
00258                                          const char* padding,
00259                                          uint32_t flags);
00260 BOTAN_DLL int botan_pk_op_decrypt_destroy(botan_pk_op_decrypt_t op);
00261 
00262 BOTAN_DLL int botan_pk_op_decrypt(botan_pk_op_decrypt_t op,
00263                                   uint8_t out[], size_t* out_len,
00264                                   uint8_t ciphertext[], size_t ciphertext_len);
00265 
00266 /*
00267 * Signature Generation
00268 */
00269 typedef struct botan_pk_op_sign_struct* botan_pk_op_sign_t;
00270 
00271 BOTAN_DLL int botan_pk_op_sign_create(botan_pk_op_sign_t* op,
00272                                       botan_privkey_t key,
00273                                       const char* hash_and_padding,
00274                                       uint32_t flags);
00275 BOTAN_DLL int botan_pk_op_sign_destroy(botan_pk_op_sign_t op);
00276 
00277 BOTAN_DLL int botan_pk_op_sign_update(botan_pk_op_sign_t op, const uint8_t in[], size_t in_len);
00278 BOTAN_DLL int botan_pk_op_sign_finish(botan_pk_op_sign_t op, botan_rng_t rng,
00279                                       uint8_t sig[], size_t* sig_len);
00280 
00281 /*
00282 * Signature Verification
00283 */
00284 typedef struct botan_pk_op_verify_struct* botan_pk_op_verify_t;
00285 
00286 BOTAN_DLL int botan_pk_op_verify_create(botan_pk_op_verify_t* op,
00287                                         botan_pubkey_t key,
00288                                         const char* hash_and_padding,
00289                                         uint32_t flags);
00290 BOTAN_DLL int botan_pk_op_verify_destroy(botan_pk_op_verify_t op);
00291 
00292 BOTAN_DLL int botan_pk_op_verify_update(botan_pk_op_verify_t op, const uint8_t in[], size_t in_len);
00293 BOTAN_DLL int botan_pk_op_verify_finish(botan_pk_op_verify_t op, const uint8_t sig[], size_t sig_len);
00294 
00295 /*
00296 * Key Agreement
00297 */
00298 typedef struct botan_pk_op_ka_struct* botan_pk_op_ka_t;
00299 
00300 BOTAN_DLL int botan_pk_op_key_agreement_create(botan_pk_op_ka_t* op,
00301                                                botan_privkey_t key,
00302                                                const char* kdf,
00303                                                uint32_t flags);
00304 BOTAN_DLL int botan_pk_op_key_agreement_destroy(botan_pk_op_ka_t op);
00305 
00306 BOTAN_DLL int botan_pk_op_key_agreement_export_public(botan_privkey_t key,
00307                                                       uint8_t out[], size_t* out_len);
00308 
00309 BOTAN_DLL int botan_pk_op_key_agreement(botan_pk_op_ka_t op,
00310                                         uint8_t out[], size_t* out_len,
00311                                         const uint8_t other_key[], size_t other_key_len,
00312                                         const uint8_t salt[], size_t salt_len);
00313 
00314 /*
00315 * TLS (WIP)
00316 */
00317 #if defined(BOTAN_HAS_TLS) && 0
00318 
00319 typedef struct botan_tls_session_struct* botan_tls_session_t;
00320 
00321 BOTAN_DLL int botan_tls_session_get_version(botan_tls_session_t* session, uint16_t* tls_version);
00322 BOTAN_DLL int botan_tls_session_get_ciphersuite(botan_tls_session_t* session, uint16_t* ciphersuite);
00323 // TODO: peer certs, validation, ...
00324 
00325 typedef struct botan_tls_channel_struct* botan_tls_channel_t;
00326 
00327 typedef void (*botan_tls_channel_output_fn)(void*, const uint8_t*, size_t);
00328 typedef void (*botan_tls_channel_data_cb)(void*, const uint8_t*, size_t);
00329 typedef void (*botan_tls_channel_alert_cb)(void*, uint16_t, const char*);
00330 typedef void (*botan_tls_channel_session_established)(void*, botan_tls_session_t);
00331 
00332 BOTAN_DLL int botan_tls_channel_init_client(botan_tls_channel_t* channel,
00333                                             botan_tls_channel_output_fn output_fn,
00334                                             botan_tls_channel_data_cb data_cb,
00335                                             botan_tls_channel_alert_cb alert_cb,
00336                                             botan_tls_channel_session_established session_cb,
00337                                             const char* server_name);
00338 
00339 BOTAN_DLL int botan_tls_channel_init_server(botan_tls_channel_t* channel,
00340                                             botan_tls_channel_output_fn output_fn,
00341                                             botan_tls_channel_data_cb data_cb,
00342                                             botan_tls_channel_alert_cb alert_cb,
00343                                             botan_tls_channel_session_established session_cb);
00344 
00345 BOTAN_DLL int botan_tls_channel_received_data(botan_tls_channel_t chan,
00346                                               const uint8_t input[], size_t len);
00347 
00348 BOTAN_DLL int botan_tls_channel_send(botan_tls_channel_t chan,
00349                                      const uint8_t input[], size_t len);
00350 
00351 BOTAN_DLL int botan_tls_channel_close(botan_tls_channel_t chan);
00352 
00353 BOTAN_DLL int botan_tls_channel_destroy(botan_tls_channel_t chan);
00354 
00355 #endif
00356 
00357 #ifdef __cplusplus
00358 }
00359 #endif
00360 
00361 #endif