hwcryptohook.h revision 296465
1/*- 2 * ModExp / RSA (with/without KM) plugin API 3 * 4 * The application will load a dynamic library which 5 * exports entrypoint(s) defined in this file. 6 * 7 * This set of entrypoints provides only a multithreaded, 8 * synchronous-within-each-thread, facility. 9 * 10 * 11 * This file is Copyright 1998-2000 nCipher Corporation Limited. 12 * 13 * Redistribution and use in source and binary forms, with opr without 14 * modification, are permitted provided that the following conditions 15 * are met: 16 * 17 * 1. Redistributions of source code must retain the copyright notice, 18 * this list of conditions, and the following disclaimer. 19 * 20 * 2. Redistributions in binary form must reproduce the above 21 * copyright notice, this list of conditions, and the following 22 * disclaimer, in the documentation and/or other materials provided 23 * with the distribution 24 * 25 * IN NO EVENT SHALL NCIPHER CORPORATION LIMITED (`NCIPHER') AND/OR 26 * ANY OTHER AUTHORS OR DISTRIBUTORS OF THIS FILE BE LIABLE for any 27 * damages arising directly or indirectly from this file, its use or 28 * this licence. Without prejudice to the generality of the 29 * foregoing: all liability shall be excluded for direct, indirect, 30 * special, incidental, consequential or other damages or any loss of 31 * profits, business, revenue goodwill or anticipated savings; 32 * liability shall be excluded even if nCipher or anyone else has been 33 * advised of the possibility of damage. In any event, if the 34 * exclusion of liability is not effective, the liability of nCipher 35 * or any author or distributor shall be limited to the lesser of the 36 * price paid and 1,000 pounds sterling. This licence only fails to 37 * exclude or limit liability for death or personal injury arising out 38 * of negligence, and only to the extent that such an exclusion or 39 * limitation is not effective. 40 * 41 * NCIPHER AND THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ALL 42 * AND ANY WARRANTIES (WHETHER EXPRESS OR IMPLIED), including, but not 43 * limited to, any implied warranties of merchantability, fitness for 44 * a particular purpose, satisfactory quality, and/or non-infringement 45 * of any third party rights. 46 * 47 * US Government use: This software and documentation is Commercial 48 * Computer Software and Computer Software Documentation, as defined in 49 * sub-paragraphs (a)(1) and (a)(5) of DFAR 252.227-7014, "Rights in 50 * Noncommercial Computer Software and Noncommercial Computer Software 51 * Documentation." Use, duplication or disclosure by the Government is 52 * subject to the terms and conditions specified here. 53 * 54 * By using or distributing this file you will be accepting these 55 * terms and conditions, including the limitation of liability and 56 * lack of warranty. If you do not wish to accept these terms and 57 * conditions, DO NOT USE THE FILE. 58 * 59 * 60 * The actual dynamically loadable plugin, and the library files for 61 * static linking, which are also provided in some distributions, are 62 * not covered by the licence described above. You should have 63 * received a separate licence with terms and conditions for these 64 * library files; if you received the library files without a licence, 65 * please contact nCipher. 66 * 67 * 68 * $Id: hwcryptohook.h,v 1.1 2002/10/11 17:10:59 levitte Exp $ 69 */ 70 71#ifndef HWCRYPTOHOOK_H 72# define HWCRYPTOHOOK_H 73 74# include <sys/types.h> 75# include <stdio.h> 76 77# ifndef HWCRYPTOHOOK_DECLARE_APPTYPES 78# define HWCRYPTOHOOK_DECLARE_APPTYPES 1 79# endif 80 81# define HWCRYPTOHOOK_ERROR_FAILED -1 82# define HWCRYPTOHOOK_ERROR_FALLBACK -2 83# define HWCRYPTOHOOK_ERROR_MPISIZE -3 84 85# if HWCRYPTOHOOK_DECLARE_APPTYPES 86 87/*- 88 * These structs are defined by the application and opaque to the 89 * crypto plugin. The application may define these as it sees fit. 90 * Default declarations are provided here, but the application may 91 * #define HWCRYPTOHOOK_DECLARE_APPTYPES 0 92 * to prevent these declarations, and instead provide its own 93 * declarations of these types. (Pointers to them must still be 94 * ordinary pointers to structs or unions, or the resulting combined 95 * program will have a type inconsistency.) 96 */ 97typedef struct HWCryptoHook_MutexValue HWCryptoHook_Mutex; 98typedef struct HWCryptoHook_CondVarValue HWCryptoHook_CondVar; 99typedef struct HWCryptoHook_PassphraseContextValue 100 HWCryptoHook_PassphraseContext; 101typedef struct HWCryptoHook_CallerContextValue HWCryptoHook_CallerContext; 102 103# endif /* HWCRYPTOHOOK_DECLARE_APPTYPES */ 104 105/*- 106 * These next two structs are opaque to the application. The crypto 107 * plugin will return pointers to them; the caller simply manipulates 108 * the pointers. 109 */ 110typedef struct HWCryptoHook_Context *HWCryptoHook_ContextHandle; 111typedef struct HWCryptoHook_RSAKey *HWCryptoHook_RSAKeyHandle; 112 113typedef struct { 114 char *buf; 115 size_t size; 116} HWCryptoHook_ErrMsgBuf; 117/*- 118 * Used for error reporting. When a HWCryptoHook function fails it 119 * will return a sentinel value (0 for pointer-valued functions, or a 120 * negative number, usually HWCRYPTOHOOK_ERROR_FAILED, for 121 * integer-valued ones). It will, if an ErrMsgBuf is passed, also put 122 * an error message there. 123 * 124 * size is the size of the buffer, and will not be modified. If you 125 * pass 0 for size you must pass 0 for buf, and nothing will be 126 * recorded (just as if you passed 0 for the struct pointer). 127 * Messages written to the buffer will always be null-terminated, even 128 * when truncated to fit within size bytes. 129 * 130 * The contents of the buffer are not defined if there is no error. 131 */ 132 133typedef struct HWCryptoHook_MPIStruct { 134 unsigned char *buf; 135 size_t size; 136} HWCryptoHook_MPI; 137/*- 138 * When one of these is returned, a pointer is passed to the function. 139 * At call, size is the space available. Afterwards it is updated to 140 * be set to the actual length (which may be more than the space available, 141 * if there was not enough room and the result was truncated). 142 * buf (the pointer) is not updated. 143 * 144 * size is in bytes and may be zero at call or return, but must be a 145 * multiple of the limb size. Zero limbs at the MS end are not 146 * permitted. 147 */ 148 149# define HWCryptoHook_InitFlags_FallbackModExp 0x0002UL 150# define HWCryptoHook_InitFlags_FallbackRSAImmed 0x0004UL 151/*- 152 * Enable requesting fallback to software in case of problems with the 153 * hardware support. This indicates to the crypto provider that the 154 * application is prepared to fall back to software operation if the 155 * ModExp* or RSAImmed* functions return HWCRYPTOHOOK_ERROR_FALLBACK. 156 * Without this flag those calls will never return 157 * HWCRYPTOHOOK_ERROR_FALLBACK. The flag will also cause the crypto 158 * provider to avoid repeatedly attempting to contact dead hardware 159 * within a short interval, if appropriate. 160 */ 161 162# define HWCryptoHook_InitFlags_SimpleForkCheck 0x0010UL 163/*- 164 * Without _SimpleForkCheck the library is allowed to assume that the 165 * application will not fork and call the library in the child(ren). 166 * 167 * When it is specified, this is allowed. However, after a fork 168 * neither parent nor child may unload any loaded keys or call 169 * _Finish. Instead, they should call exit (or die with a signal) 170 * without calling _Finish. After all the children have died the 171 * parent may unload keys or call _Finish. 172 * 173 * This flag only has any effect on UN*X platforms. 174 */ 175 176typedef struct { 177 unsigned long flags; 178 void *logstream; /* usually a FILE*. See below. */ 179 size_t limbsize; /* bignum format - size of radix type, must 180 * be power of 2 */ 181 int mslimbfirst; /* 0 or 1 */ 182 int msbytefirst; /* 0 or 1; -1 = native */ 183 /*- 184 * All the callback functions should return 0 on success, or a 185 * nonzero integer (whose value will be visible in the error message 186 * put in the buffer passed to the call). 187 * 188 * If a callback is not available pass a null function pointer. 189 * 190 * The callbacks may not call down again into the crypto plugin. 191 */ 192 /*- 193 * For thread-safety. Set everything to 0 if you promise only to be 194 * singlethreaded. maxsimultaneous is the number of calls to 195 * ModExp[Crt]/RSAImmed{Priv,Pub}/RSA. If you don't know what to 196 * put there then say 0 and the hook library will use a default. 197 * 198 * maxmutexes is a small limit on the number of simultaneous mutexes 199 * which will be requested by the library. If there is no small 200 * limit, set it to 0. If the crypto plugin cannot create the 201 * advertised number of mutexes the calls to its functions may fail. 202 * If a low number of mutexes is advertised the plugin will try to 203 * do the best it can. Making larger numbers of mutexes available 204 * may improve performance and parallelism by reducing contention 205 * over critical sections. Unavailability of any mutexes, implying 206 * single-threaded operation, should be indicated by the setting 207 * mutex_init et al to 0. 208 */ 209 int maxmutexes; 210 int maxsimultaneous; 211 size_t mutexsize; 212 int (*mutex_init) (HWCryptoHook_Mutex *, 213 HWCryptoHook_CallerContext * cactx); 214 int (*mutex_acquire) (HWCryptoHook_Mutex *); 215 void (*mutex_release) (HWCryptoHook_Mutex *); 216 void (*mutex_destroy) (HWCryptoHook_Mutex *); 217 /*- 218 * For greater efficiency, can use condition vars internally for 219 * synchronisation. In this case maxsimultaneous is ignored, but 220 * the other mutex stuff must be available. In singlethreaded 221 * programs, set everything to 0. 222 */ 223 size_t condvarsize; 224 int (*condvar_init) (HWCryptoHook_CondVar *, 225 HWCryptoHook_CallerContext * cactx); 226 int (*condvar_wait) (HWCryptoHook_CondVar *, HWCryptoHook_Mutex *); 227 void (*condvar_signal) (HWCryptoHook_CondVar *); 228 void (*condvar_broadcast) (HWCryptoHook_CondVar *); 229 void (*condvar_destroy) (HWCryptoHook_CondVar *); 230 /*- 231 * The semantics of acquiring and releasing mutexes and broadcasting 232 * and waiting on condition variables are expected to be those from 233 * POSIX threads (pthreads). The mutexes may be (in pthread-speak) 234 * fast mutexes, recursive mutexes, or nonrecursive ones. 235 * 236 * The _release/_signal/_broadcast and _destroy functions must 237 * always succeed when given a valid argument; if they are given an 238 * invalid argument then the program (crypto plugin + application) 239 * has an internal error, and they should abort the program. 240 */ 241 int (*getpassphrase) (const char *prompt_info, 242 int *len_io, char *buf, 243 HWCryptoHook_PassphraseContext * ppctx, 244 HWCryptoHook_CallerContext * cactx); 245 /*- 246 * Passphrases and the prompt_info, if they contain high-bit-set 247 * characters, are UTF-8. The prompt_info may be a null pointer if 248 * no prompt information is available (it should not be an empty 249 * string). It will not contain text like `enter passphrase'; 250 * instead it might say something like `Operator Card for John 251 * Smith' or `SmartCard in nFast Module #1, Slot #1'. 252 * 253 * buf points to a buffer in which to return the passphrase; on 254 * entry *len_io is the length of the buffer. It should be updated 255 * by the callback. The returned passphrase should not be 256 * null-terminated by the callback. 257 */ 258 int (*getphystoken) (const char *prompt_info, 259 const char *wrong_info, 260 HWCryptoHook_PassphraseContext * ppctx, 261 HWCryptoHook_CallerContext * cactx); 262 /*- 263 * Requests that the human user physically insert a different 264 * smartcard, DataKey, etc. The plugin should check whether the 265 * currently inserted token(s) are appropriate, and if they are it 266 * should not make this call. 267 * 268 * prompt_info is as before. wrong_info is a description of the 269 * currently inserted token(s) so that the user is told what 270 * something is. wrong_info, like prompt_info, may be null, but 271 * should not be an empty string. Its contents should be 272 * syntactically similar to that of prompt_info. 273 */ 274 /*- 275 * Note that a single LoadKey operation might cause several calls to 276 * getpassphrase and/or requestphystoken. If requestphystoken is 277 * not provided (ie, a null pointer is passed) then the plugin may 278 * not support loading keys for which authorisation by several cards 279 * is required. If getpassphrase is not provided then cards with 280 * passphrases may not be supported. 281 * 282 * getpassphrase and getphystoken do not need to check that the 283 * passphrase has been entered correctly or the correct token 284 * inserted; the crypto plugin will do that. If this is not the 285 * case then the crypto plugin is responsible for calling these 286 * routines again as appropriate until the correct token(s) and 287 * passphrase(s) are supplied as required, or until any retry limits 288 * implemented by the crypto plugin are reached. 289 * 290 * In either case, the application must allow the user to say `no' 291 * or `cancel' to indicate that they do not know the passphrase or 292 * have the appropriate token; this should cause the callback to 293 * return nonzero indicating error. 294 */ 295 void (*logmessage) (void *logstream, const char *message); 296 /*- 297 * A log message will be generated at least every time something goes 298 * wrong and an ErrMsgBuf is filled in (or would be if one was 299 * provided). Other diagnostic information may be written there too, 300 * including more detailed reasons for errors which are reported in an 301 * ErrMsgBuf. 302 * 303 * When a log message is generated, this callback is called. It 304 * should write a message to the relevant logging arrangements. 305 * 306 * The message string passed will be null-terminated and may be of arbitrary 307 * length. It will not be prefixed by the time and date, nor by the 308 * name of the library that is generating it - if this is required, 309 * the logmessage callback must do it. The message will not have a 310 * trailing newline (though it may contain internal newlines). 311 * 312 * If a null pointer is passed for logmessage a default function is 313 * used. The default function treats logstream as a FILE* which has 314 * been converted to a void*. If logstream is 0 it does nothing. 315 * Otherwise it prepends the date and time and library name and 316 * writes the message to logstream. Each line will be prefixed by a 317 * descriptive string containing the date, time and identity of the 318 * crypto plugin. Errors on the logstream are not reported 319 * anywhere, and the default function doesn't flush the stream, so 320 * the application must set the buffering how it wants it. 321 * 322 * The crypto plugin may also provide a facility to have copies of 323 * log messages sent elsewhere, and or for adjusting the verbosity 324 * of the log messages; any such facilities will be configured by 325 * external means. 326 */ 327} HWCryptoHook_InitInfo; 328 329typedef 330HWCryptoHook_ContextHandle HWCryptoHook_Init_t(const HWCryptoHook_InitInfo * 331 initinfo, size_t initinfosize, 332 const HWCryptoHook_ErrMsgBuf * 333 errors, 334 HWCryptoHook_CallerContext * 335 cactx); 336extern HWCryptoHook_Init_t HWCryptoHook_Init; 337 338/*- 339 * Caller should set initinfosize to the size of the HWCryptoHook struct, 340 * so it can be extended later. 341 * 342 * On success, a message for display or logging by the server, 343 * including the name and version number of the plugin, will be filled 344 * in into *errors; on failure *errors is used for error handling, as 345 * usual. 346 */ 347 348/*- 349 * All these functions return 0 on success, HWCRYPTOHOOK_ERROR_FAILED 350 * on most failures. HWCRYPTOHOOK_ERROR_MPISIZE means at least one of 351 * the output MPI buffer(s) was too small; the sizes of all have been 352 * set to the desired size (and for those where the buffer was large 353 * enough, the value may have been copied in), and no error message 354 * has been recorded. 355 * 356 * You may pass 0 for the errors struct. In any case, unless you set 357 * _NoStderr at init time then messages may be reported to stderr. 358 */ 359 360/*- 361 * The RSAImmed* functions (and key managed RSA) only work with 362 * modules which have an RSA patent licence - currently that means KM 363 * units; the ModExp* ones work with all modules, so you need a patent 364 * licence in the software in the US. They are otherwise identical. 365 */ 366 367typedef 368void HWCryptoHook_Finish_t(HWCryptoHook_ContextHandle hwctx); 369extern HWCryptoHook_Finish_t HWCryptoHook_Finish; 370/* You must not have any calls going or keys loaded when you call this. */ 371 372typedef 373int HWCryptoHook_RandomBytes_t(HWCryptoHook_ContextHandle hwctx, 374 unsigned char *buf, size_t len, 375 const HWCryptoHook_ErrMsgBuf * errors); 376extern HWCryptoHook_RandomBytes_t HWCryptoHook_RandomBytes; 377 378typedef 379int HWCryptoHook_ModExp_t(HWCryptoHook_ContextHandle hwctx, 380 HWCryptoHook_MPI a, 381 HWCryptoHook_MPI p, 382 HWCryptoHook_MPI n, 383 HWCryptoHook_MPI * r, 384 const HWCryptoHook_ErrMsgBuf * errors); 385extern HWCryptoHook_ModExp_t HWCryptoHook_ModExp; 386 387typedef 388int HWCryptoHook_RSAImmedPub_t(HWCryptoHook_ContextHandle hwctx, 389 HWCryptoHook_MPI m, 390 HWCryptoHook_MPI e, 391 HWCryptoHook_MPI n, 392 HWCryptoHook_MPI * r, 393 const HWCryptoHook_ErrMsgBuf * errors); 394extern HWCryptoHook_RSAImmedPub_t HWCryptoHook_RSAImmedPub; 395 396typedef 397int HWCryptoHook_ModExpCRT_t(HWCryptoHook_ContextHandle hwctx, 398 HWCryptoHook_MPI a, 399 HWCryptoHook_MPI p, 400 HWCryptoHook_MPI q, 401 HWCryptoHook_MPI dmp1, 402 HWCryptoHook_MPI dmq1, 403 HWCryptoHook_MPI iqmp, 404 HWCryptoHook_MPI * r, 405 const HWCryptoHook_ErrMsgBuf * errors); 406extern HWCryptoHook_ModExpCRT_t HWCryptoHook_ModExpCRT; 407 408typedef 409int HWCryptoHook_RSAImmedPriv_t(HWCryptoHook_ContextHandle hwctx, 410 HWCryptoHook_MPI m, 411 HWCryptoHook_MPI p, 412 HWCryptoHook_MPI q, 413 HWCryptoHook_MPI dmp1, 414 HWCryptoHook_MPI dmq1, 415 HWCryptoHook_MPI iqmp, 416 HWCryptoHook_MPI * r, 417 const HWCryptoHook_ErrMsgBuf * errors); 418extern HWCryptoHook_RSAImmedPriv_t HWCryptoHook_RSAImmedPriv; 419 420/*- 421 * The RSAImmed* and ModExp* functions may return E_FAILED or 422 * E_FALLBACK for failure. 423 * 424 * E_FAILED means the failure is permanent and definite and there 425 * should be no attempt to fall back to software. (Eg, for some 426 * applications, which support only the acceleration-only 427 * functions, the `key material' may actually be an encoded key 428 * identifier, and doing the operation in software would give wrong 429 * answers.) 430 * 431 * E_FALLBACK means that doing the computation in software would seem 432 * reasonable. If an application pays attention to this and is 433 * able to fall back, it should also set the Fallback init flags. 434 */ 435 436typedef 437int HWCryptoHook_RSALoadKey_t(HWCryptoHook_ContextHandle hwctx, 438 const char *key_ident, 439 HWCryptoHook_RSAKeyHandle * keyhandle_r, 440 const HWCryptoHook_ErrMsgBuf * errors, 441 HWCryptoHook_PassphraseContext * ppctx); 442extern HWCryptoHook_RSALoadKey_t HWCryptoHook_RSALoadKey; 443/*- 444 * The key_ident is a null-terminated string configured by the 445 * user via the application's usual configuration mechanisms. 446 * It is provided to the user by the crypto provider's key management 447 * system. The user must be able to enter at least any string of between 448 * 1 and 1023 characters inclusive, consisting of printable 7-bit 449 * ASCII characters. The provider should avoid using 450 * any characters except alphanumerics and the punctuation 451 * characters _ - + . / @ ~ (the user is expected to be able 452 * to enter these without quoting). The string may be case-sensitive. 453 * The application may allow the user to enter other NULL-terminated strings, 454 * and the provider must cope (returning an error if the string is not 455 * valid). 456 * 457 * If the key does not exist, no error is recorded and 0 is returned; 458 * keyhandle_r will be set to 0 instead of to a key handle. 459 */ 460 461typedef 462int HWCryptoHook_RSAGetPublicKey_t(HWCryptoHook_RSAKeyHandle k, 463 HWCryptoHook_MPI * n, 464 HWCryptoHook_MPI * e, 465 const HWCryptoHook_ErrMsgBuf * errors); 466extern HWCryptoHook_RSAGetPublicKey_t HWCryptoHook_RSAGetPublicKey; 467/*- 468 * The crypto plugin will not store certificates. 469 * 470 * Although this function for acquiring the public key value is 471 * provided, it is not the purpose of this API to deal fully with the 472 * handling of the public key. 473 * 474 * It is expected that the crypto supplier's key generation program 475 * will provide general facilities for producing X.509 476 * self-certificates and certificate requests in PEM format. These 477 * will be given to the user so that they can configure them in the 478 * application, send them to CAs, or whatever. 479 * 480 * In case this kind of certificate handling is not appropriate, the 481 * crypto supplier's key generation program should be able to be 482 * configured not to generate such a self-certificate or certificate 483 * request. Then the application will need to do all of this, and 484 * will need to store and handle the public key and certificates 485 * itself. 486 */ 487 488typedef 489int HWCryptoHook_RSAUnloadKey_t(HWCryptoHook_RSAKeyHandle k, 490 const HWCryptoHook_ErrMsgBuf * errors); 491extern HWCryptoHook_RSAUnloadKey_t HWCryptoHook_RSAUnloadKey; 492/* Might fail due to locking problems, or other serious internal problems. */ 493 494typedef 495int HWCryptoHook_RSA_t(HWCryptoHook_MPI m, 496 HWCryptoHook_RSAKeyHandle k, 497 HWCryptoHook_MPI * r, 498 const HWCryptoHook_ErrMsgBuf * errors); 499extern HWCryptoHook_RSA_t HWCryptoHook_RSA; 500/* RSA private key operation (sign or decrypt) - raw, unpadded. */ 501 502#endif /* HWCRYPTOHOOK_H */ 503