lib/fko.h

   1 /*
   2  *****************************************************************************
   3  *
   4  * File:    fko.h
   5  *
   6  * Author:  Damien S. Stuart
   7  *
   8  * Purpose: Header for libfko.
   9  *
  10  * Copyright 2009-2010 Damien Stuart (dstuart@dstuart.org)
  11  *
  12  *  License (GNU Public License):
  13  *
  14  *  This program is free software; you can redistribute it and/or
  15  *  modify it under the terms of the GNU General Public License
  16  *  as published by the Free Software Foundation; either version 2
  17  *  of the License, or (at your option) any later version.
  18  *
  19  *  This program is distributed in the hope that it will be useful,
  20  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  *  GNU General Public License for more details.
  23  *
  24  *  You should have received a copy of the GNU General Public License
  25  *  along with this program; if not, write to the Free Software
  26  *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
  27  *  USA
  28  *
  29  *****************************************************************************
  30 */
  31 #ifndef FKO_H
  32 #define FKO_H 1
  33
  34 #include <time.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 #ifdef WIN32
  41   #ifdef DLL_EXPORTS
  42     #define DLL_API __declspec(dllexport)
  43   #else
  44         #ifdef DLL_IMPORTS
  45                 #define DLL_API __declspec(dllimport)
  46         #else
  47                 #define DLL_API
  48         #endif
  49   #endif
  50 #else
  51   #define DLL_API
  52 #endif
  53
  54 /* General params
  55 */
  56 #define FKO_PROTOCOL_VERSION "2.5.0" /* The fwknop protocol version */
  57
  58 /* Supported FKO Message types...
  59 */
  60 typedef enum {
  61     FKO_COMMAND_MSG = 0,
  62     FKO_ACCESS_MSG,
  63     FKO_NAT_ACCESS_MSG,
  64     FKO_CLIENT_TIMEOUT_ACCESS_MSG,
  65     FKO_CLIENT_TIMEOUT_NAT_ACCESS_MSG,
  66     FKO_LOCAL_NAT_ACCESS_MSG,
  67     FKO_CLIENT_TIMEOUT_LOCAL_NAT_ACCESS_MSG,
  68     FKO_LAST_MSG_TYPE /* Always leave this as the last one */
  69 } fko_message_type_t;
  70
  71 /* Supported digest types...
  72 */
  73 typedef enum {
  74     FKO_DIGEST_INVALID_DATA = -1,
  75     FKO_DIGEST_UNKNOWN = 0,
  76     FKO_DIGEST_MD5,
  77     FKO_DIGEST_SHA1,
  78     FKO_DIGEST_SHA256,
  79     FKO_DIGEST_SHA384,
  80     FKO_DIGEST_SHA512,
  81     FKO_LAST_DIGEST_TYPE /* Always leave this as the last one */
  82 } fko_digest_type_t;
  83
  84 /* Supported hmac digest types...
  85 */
  86 typedef enum {
  87     FKO_HMAC_INVALID_DATA = -1,
  88     FKO_HMAC_UNKNOWN = 0,
  89     FKO_HMAC_MD5,
  90     FKO_HMAC_SHA1,
  91     FKO_HMAC_SHA256,
  92     FKO_HMAC_SHA384,
  93     FKO_HMAC_SHA512,
  94     FKO_LAST_HMAC_MODE /* Always leave this as the last one */
  95 } fko_hmac_type_t;
  96
  97 /* Supported encryption types...
  98 */
  99 typedef enum {
 100     FKO_ENCRYPTION_INVALID_DATA = -1,
 101     FKO_ENCRYPTION_UNKNOWN = 0,
 102     FKO_ENCRYPTION_RIJNDAEL,
 103     FKO_ENCRYPTION_GPG,
 104     FKO_LAST_ENCRYPTION_TYPE /* Always leave this as the last one */
 105 } fko_encryption_type_t;
 106
 107 /* Symmetric encryption modes to correspond to rijndael.h
 108 */
 109 typedef enum {
 110     FKO_ENC_MODE_UNKNOWN = 0,
 111     FKO_ENC_MODE_ECB,
 112     FKO_ENC_MODE_CBC,
 113     FKO_ENC_MODE_CFB,
 114     FKO_ENC_MODE_PCBC,
 115     FKO_ENC_MODE_OFB,
 116     FKO_ENC_MODE_CTR,
 117     FKO_ENC_MODE_ASYMMETRIC,  /* placeholder when GPG is used */
 118     FKO_ENC_MODE_CBC_LEGACY_IV,  /* for the old zero-padding strategy */
 119     FKO_LAST_ENC_MODE /* Always leave this as the last one */
 120 } fko_encryption_mode_t;
 121
 122 /* FKO ERROR_CODES
 123  *
 124  * Note: If you change this list in any way, please be sure to make the
 125  *       appropriate corresponding change to the error message list in
 126  *       fko_error.c.
 127 */
 128 typedef enum {
 129     FKO_SUCCESS = 0,
 130     FKO_ERROR_CTX_NOT_INITIALIZED,
 131     FKO_ERROR_MEMORY_ALLOCATION,
 132     FKO_ERROR_FILESYSTEM_OPERATION,
 133     FKO_ERROR_INVALID_DATA,
 134     FKO_ERROR_DATA_TOO_LARGE,
 135     FKO_ERROR_INVALID_KEY_LEN,
 136     FKO_ERROR_USERNAME_UNKNOWN,
 137     FKO_ERROR_INCOMPLETE_SPA_DATA,
 138     FKO_ERROR_MISSING_ENCODED_DATA,
 139     FKO_ERROR_INVALID_DIGEST_TYPE,
 140     FKO_ERROR_INVALID_ALLOW_IP,
 141     FKO_ERROR_INVALID_SPA_COMMAND_MSG,
 142     FKO_ERROR_INVALID_SPA_ACCESS_MSG,
 143     FKO_ERROR_INVALID_SPA_NAT_ACCESS_MSG,
 144     FKO_ERROR_INVALID_ENCRYPTION_TYPE,
 145     FKO_ERROR_WRONG_ENCRYPTION_TYPE,
 146     FKO_ERROR_DECRYPTION_SIZE,
 147     FKO_ERROR_DECRYPTION_FAILURE,
 148     FKO_ERROR_DIGEST_VERIFICATION_FAILED,
 149     FKO_ERROR_INVALID_HMAC_KEY_LEN,
 150     FKO_ERROR_UNSUPPORTED_HMAC_MODE,
 151     FKO_ERROR_UNSUPPORTED_FEATURE,
 152     FKO_ERROR_UNKNOWN,
 153
 154     /* Start GPGME-related errors */
 155     GPGME_ERR_START,
 156     FKO_ERROR_MISSING_GPG_KEY_DATA,
 157     FKO_ERROR_GPGME_NO_OPENPGP,
 158     FKO_ERROR_GPGME_CONTEXT,
 159     FKO_ERROR_GPGME_PLAINTEXT_DATA_OBJ,
 160     FKO_ERROR_GPGME_SET_PROTOCOL,
 161     FKO_ERROR_GPGME_CIPHER_DATA_OBJ,
 162     FKO_ERROR_GPGME_BAD_PASSPHRASE,
 163     FKO_ERROR_GPGME_ENCRYPT_SIGN,
 164     FKO_ERROR_GPGME_CONTEXT_SIGNER_KEY,
 165     FKO_ERROR_GPGME_SIGNER_KEYLIST_START,
 166     FKO_ERROR_GPGME_SIGNER_KEY_NOT_FOUND,
 167     FKO_ERROR_GPGME_SIGNER_KEY_AMBIGUOUS,
 168     FKO_ERROR_GPGME_ADD_SIGNER,
 169     FKO_ERROR_GPGME_CONTEXT_RECIPIENT_KEY,
 170     FKO_ERROR_GPGME_RECIPIENT_KEYLIST_START,
 171     FKO_ERROR_GPGME_RECIPIENT_KEY_NOT_FOUND,
 172     FKO_ERROR_GPGME_RECIPIENT_KEY_AMBIGUOUS,
 173     FKO_ERROR_GPGME_DECRYPT_FAILED,
 174     FKO_ERROR_GPGME_DECRYPT_UNSUPPORTED_ALGORITHM,
 175     FKO_ERROR_GPGME_BAD_GPG_EXE,
 176     FKO_ERROR_GPGME_BAD_HOME_DIR,
 177     FKO_ERROR_GPGME_SET_HOME_DIR,
 178     FKO_ERROR_GPGME_NO_SIGNATURE,
 179     FKO_ERROR_GPGME_BAD_SIGNATURE,
 180     FKO_ERROR_GPGME_SIGNATURE_VERIFY_DISABLED,
 181
 182     FKO_LAST_ERROR
 183 } fko_error_codes_t;
 184
 185 /* Macro that returns true if the given error code is a gpg-related error.
 186 */
 187 #define IS_GPG_ERROR(x) (x > GPGME_ERR_START && x < FKO_LAST_ERROR)
 188
 189 /* General Defaults
 190 */
 191 #define FKO_DEFAULT_MSG_TYPE     FKO_ACCESS_MSG
 192 #define FKO_DEFAULT_DIGEST       FKO_DIGEST_SHA256
 193 #define FKO_DEFAULT_ENCRYPTION   FKO_ENCRYPTION_RIJNDAEL
 194 #define FKO_DEFAULT_ENC_MODE     FKO_ENC_MODE_CBC
 195 #define FKO_DEFAULT_KEY_LEN      0
 196 #define FKO_DEFAULT_HMAC_KEY_LEN 0
 197 #define FKO_DEFAULT_HMAC_MODE    FKO_HMAC_SHA256
 198
 199 /* Define the consistent prefixes or salt on some encryption schemes.
 200 */
 201 #define B64_RIJNDAEL_SALT "U2FsdGVkX1"
 202 #define B64_RIJNDAEL_SALT_STR_LEN 10
 203
 204 #define B64_GPG_PREFIX "hQ"
 205 #define B64_GPG_PREFIX_STR_LEN 2
 206
 207 /* Specify whether libfko is allowed to call exit()
 208 */
 209 #define EXIT_UPON_ERR 1
 210 #define NO_EXIT_UPON_ERR 0
 211
 212 /* The context holds the global state and config options, as
 213  * well as some intermediate results during processing. This
 214  * is an opaque pointer.
 215 */
 216 struct fko_context;
 217 typedef struct fko_context *fko_ctx_t;
 218
 219 /* Some gpg-specifc data types and constants.
 220 */
 221 #if HAVE_LIBGPGME
 222
 223 enum {
 224     FKO_GPG_NO_SIG_VERIFY_SIGS  = 0x01,
 225     FKO_GPG_ALLOW_BAD_SIG       = 0x02,
 226     FKO_GPG_NO_SIG_INFO         = 0x04,
 227     FKO_GPG_ALLOW_EXPIRED_SIG   = 0x08,
 228     FKO_GPG_ALLOW_REVOKED_SIG   = 0x10
 229 };
 230
 231 #define FKO_GPG_GOOD_SIGSUM     3
 232
 233 #endif /* HAVE_LIBGPGME */
 234
 235 /* Function prototypes */
 236
 237 /* General api calls
 238 */
 239 DLL_API int fko_new(fko_ctx_t *ctx);
 240 DLL_API int fko_new_with_data(fko_ctx_t *ctx, const char * const enc_msg,
 241     const char * const dec_key, const int dec_key_len, int encryption_mode,
 242     const char * const hmac_key, const int hmac_key_len, const int hmac_type);
 243 DLL_API void fko_destroy(fko_ctx_t ctx);
 244 DLL_API int fko_spa_data_final(fko_ctx_t ctx, const char * const enc_key,
 245     const int enc_key_len, const char * const hmac_key, const int hmac_key_len);
 246
 247
 248 /* Set context data functions
 249 */
 250 DLL_API int fko_set_rand_value(fko_ctx_t ctx, const char * const val);
 251 DLL_API int fko_set_username(fko_ctx_t ctx, const char * const spoof_user);
 252 DLL_API int fko_set_timestamp(fko_ctx_t ctx, const int offset);
 253 DLL_API int fko_set_spa_message_type(fko_ctx_t ctx, const short msg_type);
 254 DLL_API int fko_set_spa_message(fko_ctx_t ctx, const char * const msg_string);
 255 DLL_API int fko_set_spa_nat_access(fko_ctx_t ctx, const char * const nat_access);
 256 DLL_API int fko_set_spa_server_auth(fko_ctx_t ctx, const char * const server_auth);
 257 DLL_API int fko_set_spa_client_timeout(fko_ctx_t ctx, const int timeout);
 258 DLL_API int fko_set_spa_digest_type(fko_ctx_t ctx, const short digest_type);
 259 DLL_API int fko_set_spa_digest(fko_ctx_t ctx);
 260 DLL_API int fko_set_raw_spa_digest_type(fko_ctx_t ctx, const short raw_digest_type);
 261 DLL_API int fko_set_raw_spa_digest(fko_ctx_t ctx);
 262 DLL_API int fko_set_spa_encryption_type(fko_ctx_t ctx, const short encrypt_type);
 263 DLL_API int fko_set_spa_encryption_mode(fko_ctx_t ctx, const int encrypt_mode);
 264 DLL_API int fko_set_spa_data(fko_ctx_t ctx, const char * const enc_msg);
 265 DLL_API int fko_set_spa_hmac_type(fko_ctx_t ctx, const short hmac_type);
 266
 267 /* Data processing and misc utility functions
 268 */
 269 DLL_API const char* fko_errstr(const int err_code);
 270 DLL_API int fko_encryption_type(const char * const enc_data);
 271 DLL_API int fko_key_gen(char * const key_base64, const int key_len,
 272         char * const hmac_key_base64, const int hmac_ken_len,
 273         const int hmac_type);
 274 DLL_API int fko_base64_encode(unsigned char * const in, char * const out, int in_len);
 275 DLL_API int fko_base64_decode(const char * const in, unsigned char *out);
 276
 277 DLL_API int fko_encode_spa_data(fko_ctx_t ctx);
 278 DLL_API int fko_decode_spa_data(fko_ctx_t ctx);
 279 DLL_API int fko_encrypt_spa_data(fko_ctx_t ctx, const char * const enc_key,
 280     const int enc_key_len);
 281 DLL_API int fko_decrypt_spa_data(fko_ctx_t ctx, const char * const dec_key,
 282     const int dec_key_len);
 283 DLL_API int fko_verify_hmac(fko_ctx_t ctx, const char * const hmac_key,
 284     const int hmac_key_len);
 285 DLL_API int fko_set_spa_hmac(fko_ctx_t ctx, const char * const hmac_key,
 286     const int hmac_key_len);
 287 DLL_API int fko_get_spa_hmac(fko_ctx_t ctx, char **enc_data);
 288
 289 DLL_API int fko_get_encoded_data(fko_ctx_t ctx, char **enc_data);
 290
 291
 292 /* Get context data functions
 293 */
 294 DLL_API int fko_get_rand_value(fko_ctx_t ctx, char **rand_val);
 295 DLL_API int fko_get_username(fko_ctx_t ctx, char **username);
 296 DLL_API int fko_get_timestamp(fko_ctx_t ctx, time_t *ts);
 297 DLL_API int fko_get_spa_message_type(fko_ctx_t ctx, short *spa_msg);
 298 DLL_API int fko_get_spa_message(fko_ctx_t ctx, char **spa_message);
 299 DLL_API int fko_get_spa_nat_access(fko_ctx_t ctx, char **nat_access);
 300 DLL_API int fko_get_spa_server_auth(fko_ctx_t ctx, char **server_auth);
 301 DLL_API int fko_get_spa_client_timeout(fko_ctx_t ctx, int *client_timeout);
 302 DLL_API int fko_get_spa_digest_type(fko_ctx_t ctx, short *spa_digest_type);
 303 DLL_API int fko_get_raw_spa_digest_type(fko_ctx_t ctx, short *raw_spa_digest_type);
 304 DLL_API int fko_get_spa_hmac_type(fko_ctx_t ctx, short *spa_hmac_type);
 305 DLL_API int fko_get_spa_digest(fko_ctx_t ctx, char **spa_digest);
 306 DLL_API int fko_get_raw_spa_digest(fko_ctx_t ctx, char **raw_spa_digest);
 307 DLL_API int fko_get_spa_encryption_type(fko_ctx_t ctx, short *spa_enc_type);
 308 DLL_API int fko_get_spa_encryption_mode(fko_ctx_t ctx, int *spa_enc_mode);
 309 DLL_API int fko_get_spa_data(fko_ctx_t ctx, char **spa_data);
 310
 311 DLL_API int fko_get_version(fko_ctx_t ctx, char **version);
 312
 313 /* GPG-related functions */
 314 DLL_API int fko_set_gpg_exe(fko_ctx_t ctx, const char * const gpg_exe);
 315 DLL_API int fko_get_gpg_exe(fko_ctx_t ctx, char **gpg_exe);
 316
 317 DLL_API int fko_set_gpg_recipient(fko_ctx_t ctx, const char * const recip);
 318 DLL_API int fko_get_gpg_recipient(fko_ctx_t ctx, char **recip);
 319 DLL_API int fko_set_gpg_signer(fko_ctx_t ctx, const char * const signer);
 320 DLL_API int fko_get_gpg_signer(fko_ctx_t ctx, char **signer);
 321 DLL_API int fko_set_gpg_home_dir(fko_ctx_t ctx, const char * const gpg_home_dir);
 322 DLL_API int fko_get_gpg_home_dir(fko_ctx_t ctx, char **gpg_home_dir);
 323
 324 DLL_API const char* fko_gpg_errstr(fko_ctx_t ctx);
 325
 326 DLL_API int fko_set_gpg_signature_verify(fko_ctx_t ctx,
 327     const unsigned char val);
 328 DLL_API int fko_get_gpg_signature_verify(fko_ctx_t ctx,
 329     unsigned char * const val);
 330 DLL_API int fko_set_gpg_ignore_verify_error(fko_ctx_t ctx,
 331     const unsigned char val);
 332 DLL_API int fko_get_gpg_ignore_verify_error(fko_ctx_t ctx,
 333     unsigned char * const val);
 334
 335 DLL_API int fko_get_gpg_signature_id(fko_ctx_t ctx, char **sig_id);
 336 DLL_API int fko_get_gpg_signature_fpr(fko_ctx_t ctx, char **sig_fpr);
 337 DLL_API int fko_get_gpg_signature_summary(fko_ctx_t ctx, int *sigsum);
 338 DLL_API int fko_get_gpg_signature_status(fko_ctx_t ctx, int *sigstat);
 339
 340 DLL_API int fko_gpg_signature_id_match(fko_ctx_t ctx, const char * const id,
 341     unsigned char * const result);
 342 DLL_API int fko_gpg_signature_fpr_match(fko_ctx_t ctx, const char * const fpr,
 343     unsigned char * const result);
 344
 345 #ifdef __cplusplus
 346 }
 347 #endif
 348
 349 #endif /* FKO_H */
 350
 351 /***EOF***/