1280297Sjkim/*- 2160814Ssimon * ModExp / RSA (with/without KM) plugin API 3160814Ssimon * 4160814Ssimon * The application will load a dynamic library which 5160814Ssimon * exports entrypoint(s) defined in this file. 6160814Ssimon * 7160814Ssimon * This set of entrypoints provides only a multithreaded, 8160814Ssimon * synchronous-within-each-thread, facility. 9160814Ssimon * 10160814Ssimon * 11160814Ssimon * This file is Copyright 1998-2000 nCipher Corporation Limited. 12160814Ssimon * 13160814Ssimon * Redistribution and use in source and binary forms, with opr without 14160814Ssimon * modification, are permitted provided that the following conditions 15160814Ssimon * are met: 16160814Ssimon * 17160814Ssimon * 1. Redistributions of source code must retain the copyright notice, 18160814Ssimon * this list of conditions, and the following disclaimer. 19160814Ssimon * 20160814Ssimon * 2. Redistributions in binary form must reproduce the above 21160814Ssimon * copyright notice, this list of conditions, and the following 22160814Ssimon * disclaimer, in the documentation and/or other materials provided 23160814Ssimon * with the distribution 24160814Ssimon * 25160814Ssimon * IN NO EVENT SHALL NCIPHER CORPORATION LIMITED (`NCIPHER') AND/OR 26160814Ssimon * ANY OTHER AUTHORS OR DISTRIBUTORS OF THIS FILE BE LIABLE for any 27160814Ssimon * damages arising directly or indirectly from this file, its use or 28160814Ssimon * this licence. Without prejudice to the generality of the 29160814Ssimon * foregoing: all liability shall be excluded for direct, indirect, 30160814Ssimon * special, incidental, consequential or other damages or any loss of 31160814Ssimon * profits, business, revenue goodwill or anticipated savings; 32160814Ssimon * liability shall be excluded even if nCipher or anyone else has been 33160814Ssimon * advised of the possibility of damage. In any event, if the 34160814Ssimon * exclusion of liability is not effective, the liability of nCipher 35160814Ssimon * or any author or distributor shall be limited to the lesser of the 36160814Ssimon * price paid and 1,000 pounds sterling. This licence only fails to 37160814Ssimon * exclude or limit liability for death or personal injury arising out 38160814Ssimon * of negligence, and only to the extent that such an exclusion or 39160814Ssimon * limitation is not effective. 40160814Ssimon * 41160814Ssimon * NCIPHER AND THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ALL 42160814Ssimon * AND ANY WARRANTIES (WHETHER EXPRESS OR IMPLIED), including, but not 43160814Ssimon * limited to, any implied warranties of merchantability, fitness for 44160814Ssimon * a particular purpose, satisfactory quality, and/or non-infringement 45160814Ssimon * of any third party rights. 46160814Ssimon * 47160814Ssimon * US Government use: This software and documentation is Commercial 48160814Ssimon * Computer Software and Computer Software Documentation, as defined in 49160814Ssimon * sub-paragraphs (a)(1) and (a)(5) of DFAR 252.227-7014, "Rights in 50160814Ssimon * Noncommercial Computer Software and Noncommercial Computer Software 51160814Ssimon * Documentation." Use, duplication or disclosure by the Government is 52160814Ssimon * subject to the terms and conditions specified here. 53160814Ssimon * 54160814Ssimon * By using or distributing this file you will be accepting these 55160814Ssimon * terms and conditions, including the limitation of liability and 56160814Ssimon * lack of warranty. If you do not wish to accept these terms and 57160814Ssimon * conditions, DO NOT USE THE FILE. 58160814Ssimon * 59160814Ssimon * 60160814Ssimon * The actual dynamically loadable plugin, and the library files for 61160814Ssimon * static linking, which are also provided in some distributions, are 62160814Ssimon * not covered by the licence described above. You should have 63160814Ssimon * received a separate licence with terms and conditions for these 64160814Ssimon * library files; if you received the library files without a licence, 65160814Ssimon * please contact nCipher. 66160814Ssimon * 67160814Ssimon * 68160814Ssimon * $Id: hwcryptohook.h,v 1.1 2002/10/11 17:10:59 levitte Exp $ 69160814Ssimon */ 70160814Ssimon 71160814Ssimon#ifndef HWCRYPTOHOOK_H 72280297Sjkim# define HWCRYPTOHOOK_H 73160814Ssimon 74280297Sjkim# include <sys/types.h> 75280297Sjkim# include <stdio.h> 76160814Ssimon 77280297Sjkim# ifndef HWCRYPTOHOOK_DECLARE_APPTYPES 78280297Sjkim# define HWCRYPTOHOOK_DECLARE_APPTYPES 1 79280297Sjkim# endif 80160814Ssimon 81280297Sjkim# define HWCRYPTOHOOK_ERROR_FAILED -1 82280297Sjkim# define HWCRYPTOHOOK_ERROR_FALLBACK -2 83280297Sjkim# define HWCRYPTOHOOK_ERROR_MPISIZE -3 84160814Ssimon 85280297Sjkim# if HWCRYPTOHOOK_DECLARE_APPTYPES 86160814Ssimon 87280297Sjkim/*- 88280297Sjkim * These structs are defined by the application and opaque to the 89160814Ssimon * crypto plugin. The application may define these as it sees fit. 90160814Ssimon * Default declarations are provided here, but the application may 91160814Ssimon * #define HWCRYPTOHOOK_DECLARE_APPTYPES 0 92160814Ssimon * to prevent these declarations, and instead provide its own 93160814Ssimon * declarations of these types. (Pointers to them must still be 94160814Ssimon * ordinary pointers to structs or unions, or the resulting combined 95160814Ssimon * program will have a type inconsistency.) 96160814Ssimon */ 97160814Ssimontypedef struct HWCryptoHook_MutexValue HWCryptoHook_Mutex; 98160814Ssimontypedef struct HWCryptoHook_CondVarValue HWCryptoHook_CondVar; 99280297Sjkimtypedef struct HWCryptoHook_PassphraseContextValue 100280297Sjkim HWCryptoHook_PassphraseContext; 101160814Ssimontypedef struct HWCryptoHook_CallerContextValue HWCryptoHook_CallerContext; 102160814Ssimon 103280297Sjkim# endif /* HWCRYPTOHOOK_DECLARE_APPTYPES */ 104160814Ssimon 105280297Sjkim/*- 106280297Sjkim * These next two structs are opaque to the application. The crypto 107160814Ssimon * plugin will return pointers to them; the caller simply manipulates 108160814Ssimon * the pointers. 109160814Ssimon */ 110160814Ssimontypedef struct HWCryptoHook_Context *HWCryptoHook_ContextHandle; 111160814Ssimontypedef struct HWCryptoHook_RSAKey *HWCryptoHook_RSAKeyHandle; 112160814Ssimon 113160814Ssimontypedef struct { 114280297Sjkim char *buf; 115280297Sjkim size_t size; 116160814Ssimon} HWCryptoHook_ErrMsgBuf; 117280297Sjkim/*- 118280297Sjkim * Used for error reporting. When a HWCryptoHook function fails it 119160814Ssimon * will return a sentinel value (0 for pointer-valued functions, or a 120160814Ssimon * negative number, usually HWCRYPTOHOOK_ERROR_FAILED, for 121160814Ssimon * integer-valued ones). It will, if an ErrMsgBuf is passed, also put 122160814Ssimon * an error message there. 123280297Sjkim * 124160814Ssimon * size is the size of the buffer, and will not be modified. If you 125160814Ssimon * pass 0 for size you must pass 0 for buf, and nothing will be 126160814Ssimon * recorded (just as if you passed 0 for the struct pointer). 127160814Ssimon * Messages written to the buffer will always be null-terminated, even 128160814Ssimon * when truncated to fit within size bytes. 129160814Ssimon * 130160814Ssimon * The contents of the buffer are not defined if there is no error. 131160814Ssimon */ 132160814Ssimon 133160814Ssimontypedef struct HWCryptoHook_MPIStruct { 134280297Sjkim unsigned char *buf; 135280297Sjkim size_t size; 136160814Ssimon} HWCryptoHook_MPI; 137280297Sjkim/*- 138280297Sjkim * When one of these is returned, a pointer is passed to the function. 139160814Ssimon * At call, size is the space available. Afterwards it is updated to 140160814Ssimon * be set to the actual length (which may be more than the space available, 141160814Ssimon * if there was not enough room and the result was truncated). 142160814Ssimon * buf (the pointer) is not updated. 143160814Ssimon * 144160814Ssimon * size is in bytes and may be zero at call or return, but must be a 145160814Ssimon * multiple of the limb size. Zero limbs at the MS end are not 146160814Ssimon * permitted. 147160814Ssimon */ 148160814Ssimon 149280297Sjkim# define HWCryptoHook_InitFlags_FallbackModExp 0x0002UL 150280297Sjkim# define HWCryptoHook_InitFlags_FallbackRSAImmed 0x0004UL 151280297Sjkim/*- 152280297Sjkim * Enable requesting fallback to software in case of problems with the 153160814Ssimon * hardware support. This indicates to the crypto provider that the 154160814Ssimon * application is prepared to fall back to software operation if the 155160814Ssimon * ModExp* or RSAImmed* functions return HWCRYPTOHOOK_ERROR_FALLBACK. 156160814Ssimon * Without this flag those calls will never return 157160814Ssimon * HWCRYPTOHOOK_ERROR_FALLBACK. The flag will also cause the crypto 158160814Ssimon * provider to avoid repeatedly attempting to contact dead hardware 159160814Ssimon * within a short interval, if appropriate. 160160814Ssimon */ 161160814Ssimon 162280297Sjkim# define HWCryptoHook_InitFlags_SimpleForkCheck 0x0010UL 163280297Sjkim/*- 164280297Sjkim * Without _SimpleForkCheck the library is allowed to assume that the 165160814Ssimon * application will not fork and call the library in the child(ren). 166160814Ssimon * 167160814Ssimon * When it is specified, this is allowed. However, after a fork 168160814Ssimon * neither parent nor child may unload any loaded keys or call 169160814Ssimon * _Finish. Instead, they should call exit (or die with a signal) 170160814Ssimon * without calling _Finish. After all the children have died the 171160814Ssimon * parent may unload keys or call _Finish. 172160814Ssimon * 173160814Ssimon * This flag only has any effect on UN*X platforms. 174160814Ssimon */ 175160814Ssimon 176160814Ssimontypedef struct { 177280297Sjkim unsigned long flags; 178280297Sjkim void *logstream; /* usually a FILE*. See below. */ 179280297Sjkim size_t limbsize; /* bignum format - size of radix type, must 180280297Sjkim * be power of 2 */ 181280297Sjkim int mslimbfirst; /* 0 or 1 */ 182280297Sjkim int msbytefirst; /* 0 or 1; -1 = native */ 183280297Sjkim /*- 184280297Sjkim * All the callback functions should return 0 on success, or a 185160814Ssimon * nonzero integer (whose value will be visible in the error message 186160814Ssimon * put in the buffer passed to the call). 187160814Ssimon * 188160814Ssimon * If a callback is not available pass a null function pointer. 189160814Ssimon * 190160814Ssimon * The callbacks may not call down again into the crypto plugin. 191160814Ssimon */ 192280297Sjkim /*- 193280297Sjkim * For thread-safety. Set everything to 0 if you promise only to be 194160814Ssimon * singlethreaded. maxsimultaneous is the number of calls to 195160814Ssimon * ModExp[Crt]/RSAImmed{Priv,Pub}/RSA. If you don't know what to 196160814Ssimon * put there then say 0 and the hook library will use a default. 197160814Ssimon * 198160814Ssimon * maxmutexes is a small limit on the number of simultaneous mutexes 199160814Ssimon * which will be requested by the library. If there is no small 200160814Ssimon * limit, set it to 0. If the crypto plugin cannot create the 201160814Ssimon * advertised number of mutexes the calls to its functions may fail. 202160814Ssimon * If a low number of mutexes is advertised the plugin will try to 203160814Ssimon * do the best it can. Making larger numbers of mutexes available 204160814Ssimon * may improve performance and parallelism by reducing contention 205160814Ssimon * over critical sections. Unavailability of any mutexes, implying 206160814Ssimon * single-threaded operation, should be indicated by the setting 207160814Ssimon * mutex_init et al to 0. 208160814Ssimon */ 209280297Sjkim int maxmutexes; 210280297Sjkim int maxsimultaneous; 211280297Sjkim size_t mutexsize; 212280297Sjkim int (*mutex_init) (HWCryptoHook_Mutex *, 213280297Sjkim HWCryptoHook_CallerContext * cactx); 214280297Sjkim int (*mutex_acquire) (HWCryptoHook_Mutex *); 215280297Sjkim void (*mutex_release) (HWCryptoHook_Mutex *); 216280297Sjkim void (*mutex_destroy) (HWCryptoHook_Mutex *); 217290207Sjkim /*- 218290207Sjkim * For greater efficiency, can use condition vars internally for 219290207Sjkim * synchronisation. In this case maxsimultaneous is ignored, but 220290207Sjkim * the other mutex stuff must be available. In singlethreaded 221290207Sjkim * programs, set everything to 0. 222290207Sjkim */ 223280297Sjkim size_t condvarsize; 224280297Sjkim int (*condvar_init) (HWCryptoHook_CondVar *, 225280297Sjkim HWCryptoHook_CallerContext * cactx); 226280297Sjkim int (*condvar_wait) (HWCryptoHook_CondVar *, HWCryptoHook_Mutex *); 227280297Sjkim void (*condvar_signal) (HWCryptoHook_CondVar *); 228280297Sjkim void (*condvar_broadcast) (HWCryptoHook_CondVar *); 229280297Sjkim void (*condvar_destroy) (HWCryptoHook_CondVar *); 230290207Sjkim /*- 231290207Sjkim * The semantics of acquiring and releasing mutexes and broadcasting 232290207Sjkim * and waiting on condition variables are expected to be those from 233290207Sjkim * POSIX threads (pthreads). The mutexes may be (in pthread-speak) 234290207Sjkim * fast mutexes, recursive mutexes, or nonrecursive ones. 235290207Sjkim * 236290207Sjkim * The _release/_signal/_broadcast and _destroy functions must 237290207Sjkim * always succeed when given a valid argument; if they are given an 238290207Sjkim * invalid argument then the program (crypto plugin + application) 239290207Sjkim * has an internal error, and they should abort the program. 240290207Sjkim */ 241280297Sjkim int (*getpassphrase) (const char *prompt_info, 242280297Sjkim int *len_io, char *buf, 243280297Sjkim HWCryptoHook_PassphraseContext * ppctx, 244280297Sjkim HWCryptoHook_CallerContext * cactx); 245290207Sjkim /*- 246290207Sjkim * Passphrases and the prompt_info, if they contain high-bit-set 247290207Sjkim * characters, are UTF-8. The prompt_info may be a null pointer if 248290207Sjkim * no prompt information is available (it should not be an empty 249290207Sjkim * string). It will not contain text like `enter passphrase'; 250290207Sjkim * instead it might say something like `Operator Card for John 251290207Sjkim * Smith' or `SmartCard in nFast Module #1, Slot #1'. 252290207Sjkim * 253290207Sjkim * buf points to a buffer in which to return the passphrase; on 254290207Sjkim * entry *len_io is the length of the buffer. It should be updated 255290207Sjkim * by the callback. The returned passphrase should not be 256290207Sjkim * null-terminated by the callback. 257290207Sjkim */ 258280297Sjkim int (*getphystoken) (const char *prompt_info, 259280297Sjkim const char *wrong_info, 260280297Sjkim HWCryptoHook_PassphraseContext * ppctx, 261280297Sjkim HWCryptoHook_CallerContext * cactx); 262290207Sjkim /*- 263290207Sjkim * Requests that the human user physically insert a different 264290207Sjkim * smartcard, DataKey, etc. The plugin should check whether the 265290207Sjkim * currently inserted token(s) are appropriate, and if they are it 266290207Sjkim * should not make this call. 267290207Sjkim * 268290207Sjkim * prompt_info is as before. wrong_info is a description of the 269290207Sjkim * currently inserted token(s) so that the user is told what 270290207Sjkim * something is. wrong_info, like prompt_info, may be null, but 271290207Sjkim * should not be an empty string. Its contents should be 272290207Sjkim * syntactically similar to that of prompt_info. 273290207Sjkim */ 274290207Sjkim /*- 275290207Sjkim * Note that a single LoadKey operation might cause several calls to 276290207Sjkim * getpassphrase and/or requestphystoken. If requestphystoken is 277290207Sjkim * not provided (ie, a null pointer is passed) then the plugin may 278290207Sjkim * not support loading keys for which authorisation by several cards 279290207Sjkim * is required. If getpassphrase is not provided then cards with 280290207Sjkim * passphrases may not be supported. 281290207Sjkim * 282290207Sjkim * getpassphrase and getphystoken do not need to check that the 283290207Sjkim * passphrase has been entered correctly or the correct token 284290207Sjkim * inserted; the crypto plugin will do that. If this is not the 285290207Sjkim * case then the crypto plugin is responsible for calling these 286290207Sjkim * routines again as appropriate until the correct token(s) and 287290207Sjkim * passphrase(s) are supplied as required, or until any retry limits 288290207Sjkim * implemented by the crypto plugin are reached. 289290207Sjkim * 290290207Sjkim * In either case, the application must allow the user to say `no' 291290207Sjkim * or `cancel' to indicate that they do not know the passphrase or 292290207Sjkim * have the appropriate token; this should cause the callback to 293290207Sjkim * return nonzero indicating error. 294290207Sjkim */ 295280297Sjkim void (*logmessage) (void *logstream, const char *message); 296290207Sjkim /*- 297290207Sjkim * A log message will be generated at least every time something goes 298290207Sjkim * wrong and an ErrMsgBuf is filled in (or would be if one was 299290207Sjkim * provided). Other diagnostic information may be written there too, 300290207Sjkim * including more detailed reasons for errors which are reported in an 301290207Sjkim * ErrMsgBuf. 302290207Sjkim * 303290207Sjkim * When a log message is generated, this callback is called. It 304290207Sjkim * should write a message to the relevant logging arrangements. 305290207Sjkim * 306290207Sjkim * The message string passed will be null-terminated and may be of arbitrary 307290207Sjkim * length. It will not be prefixed by the time and date, nor by the 308290207Sjkim * name of the library that is generating it - if this is required, 309290207Sjkim * the logmessage callback must do it. The message will not have a 310290207Sjkim * trailing newline (though it may contain internal newlines). 311290207Sjkim * 312290207Sjkim * If a null pointer is passed for logmessage a default function is 313290207Sjkim * used. The default function treats logstream as a FILE* which has 314290207Sjkim * been converted to a void*. If logstream is 0 it does nothing. 315290207Sjkim * Otherwise it prepends the date and time and library name and 316290207Sjkim * writes the message to logstream. Each line will be prefixed by a 317290207Sjkim * descriptive string containing the date, time and identity of the 318290207Sjkim * crypto plugin. Errors on the logstream are not reported 319290207Sjkim * anywhere, and the default function doesn't flush the stream, so 320290207Sjkim * the application must set the buffering how it wants it. 321290207Sjkim * 322290207Sjkim * The crypto plugin may also provide a facility to have copies of 323290207Sjkim * log messages sent elsewhere, and or for adjusting the verbosity 324290207Sjkim * of the log messages; any such facilities will be configured by 325290207Sjkim * external means. 326290207Sjkim */ 327160814Ssimon} HWCryptoHook_InitInfo; 328160814Ssimon 329160814Ssimontypedef 330280297SjkimHWCryptoHook_ContextHandle HWCryptoHook_Init_t(const HWCryptoHook_InitInfo * 331280297Sjkim initinfo, size_t initinfosize, 332280297Sjkim const HWCryptoHook_ErrMsgBuf * 333280297Sjkim errors, 334280297Sjkim HWCryptoHook_CallerContext * 335280297Sjkim cactx); 336160814Ssimonextern HWCryptoHook_Init_t HWCryptoHook_Init; 337160814Ssimon 338280297Sjkim/*- 339280297Sjkim * Caller should set initinfosize to the size of the HWCryptoHook struct, 340160814Ssimon * so it can be extended later. 341160814Ssimon * 342160814Ssimon * On success, a message for display or logging by the server, 343160814Ssimon * including the name and version number of the plugin, will be filled 344160814Ssimon * in into *errors; on failure *errors is used for error handling, as 345160814Ssimon * usual. 346160814Ssimon */ 347160814Ssimon 348280297Sjkim/*- 349280297Sjkim * All these functions return 0 on success, HWCRYPTOHOOK_ERROR_FAILED 350160814Ssimon * on most failures. HWCRYPTOHOOK_ERROR_MPISIZE means at least one of 351160814Ssimon * the output MPI buffer(s) was too small; the sizes of all have been 352160814Ssimon * set to the desired size (and for those where the buffer was large 353160814Ssimon * enough, the value may have been copied in), and no error message 354160814Ssimon * has been recorded. 355160814Ssimon * 356160814Ssimon * You may pass 0 for the errors struct. In any case, unless you set 357160814Ssimon * _NoStderr at init time then messages may be reported to stderr. 358160814Ssimon */ 359160814Ssimon 360280297Sjkim/*- 361280297Sjkim * The RSAImmed* functions (and key managed RSA) only work with 362160814Ssimon * modules which have an RSA patent licence - currently that means KM 363160814Ssimon * units; the ModExp* ones work with all modules, so you need a patent 364160814Ssimon * licence in the software in the US. They are otherwise identical. 365160814Ssimon */ 366160814Ssimon 367160814Ssimontypedef 368160814Ssimonvoid HWCryptoHook_Finish_t(HWCryptoHook_ContextHandle hwctx); 369160814Ssimonextern HWCryptoHook_Finish_t HWCryptoHook_Finish; 370160814Ssimon/* You must not have any calls going or keys loaded when you call this. */ 371160814Ssimon 372160814Ssimontypedef 373160814Ssimonint HWCryptoHook_RandomBytes_t(HWCryptoHook_ContextHandle hwctx, 374160814Ssimon unsigned char *buf, size_t len, 375280297Sjkim const HWCryptoHook_ErrMsgBuf * errors); 376160814Ssimonextern HWCryptoHook_RandomBytes_t HWCryptoHook_RandomBytes; 377160814Ssimon 378160814Ssimontypedef 379160814Ssimonint HWCryptoHook_ModExp_t(HWCryptoHook_ContextHandle hwctx, 380160814Ssimon HWCryptoHook_MPI a, 381160814Ssimon HWCryptoHook_MPI p, 382160814Ssimon HWCryptoHook_MPI n, 383280297Sjkim HWCryptoHook_MPI * r, 384280297Sjkim const HWCryptoHook_ErrMsgBuf * errors); 385160814Ssimonextern HWCryptoHook_ModExp_t HWCryptoHook_ModExp; 386160814Ssimon 387160814Ssimontypedef 388160814Ssimonint HWCryptoHook_RSAImmedPub_t(HWCryptoHook_ContextHandle hwctx, 389160814Ssimon HWCryptoHook_MPI m, 390160814Ssimon HWCryptoHook_MPI e, 391160814Ssimon HWCryptoHook_MPI n, 392280297Sjkim HWCryptoHook_MPI * r, 393280297Sjkim const HWCryptoHook_ErrMsgBuf * errors); 394160814Ssimonextern HWCryptoHook_RSAImmedPub_t HWCryptoHook_RSAImmedPub; 395160814Ssimon 396160814Ssimontypedef 397160814Ssimonint HWCryptoHook_ModExpCRT_t(HWCryptoHook_ContextHandle hwctx, 398160814Ssimon HWCryptoHook_MPI a, 399160814Ssimon HWCryptoHook_MPI p, 400160814Ssimon HWCryptoHook_MPI q, 401160814Ssimon HWCryptoHook_MPI dmp1, 402160814Ssimon HWCryptoHook_MPI dmq1, 403160814Ssimon HWCryptoHook_MPI iqmp, 404280297Sjkim HWCryptoHook_MPI * r, 405280297Sjkim const HWCryptoHook_ErrMsgBuf * errors); 406160814Ssimonextern HWCryptoHook_ModExpCRT_t HWCryptoHook_ModExpCRT; 407160814Ssimon 408160814Ssimontypedef 409160814Ssimonint HWCryptoHook_RSAImmedPriv_t(HWCryptoHook_ContextHandle hwctx, 410160814Ssimon HWCryptoHook_MPI m, 411160814Ssimon HWCryptoHook_MPI p, 412160814Ssimon HWCryptoHook_MPI q, 413160814Ssimon HWCryptoHook_MPI dmp1, 414160814Ssimon HWCryptoHook_MPI dmq1, 415160814Ssimon HWCryptoHook_MPI iqmp, 416280297Sjkim HWCryptoHook_MPI * r, 417280297Sjkim const HWCryptoHook_ErrMsgBuf * errors); 418160814Ssimonextern HWCryptoHook_RSAImmedPriv_t HWCryptoHook_RSAImmedPriv; 419160814Ssimon 420280297Sjkim/*- 421280297Sjkim * The RSAImmed* and ModExp* functions may return E_FAILED or 422160814Ssimon * E_FALLBACK for failure. 423160814Ssimon * 424160814Ssimon * E_FAILED means the failure is permanent and definite and there 425160814Ssimon * should be no attempt to fall back to software. (Eg, for some 426160814Ssimon * applications, which support only the acceleration-only 427160814Ssimon * functions, the `key material' may actually be an encoded key 428160814Ssimon * identifier, and doing the operation in software would give wrong 429160814Ssimon * answers.) 430160814Ssimon * 431160814Ssimon * E_FALLBACK means that doing the computation in software would seem 432160814Ssimon * reasonable. If an application pays attention to this and is 433160814Ssimon * able to fall back, it should also set the Fallback init flags. 434160814Ssimon */ 435160814Ssimon 436160814Ssimontypedef 437160814Ssimonint HWCryptoHook_RSALoadKey_t(HWCryptoHook_ContextHandle hwctx, 438160814Ssimon const char *key_ident, 439280297Sjkim HWCryptoHook_RSAKeyHandle * keyhandle_r, 440280297Sjkim const HWCryptoHook_ErrMsgBuf * errors, 441280297Sjkim HWCryptoHook_PassphraseContext * ppctx); 442160814Ssimonextern HWCryptoHook_RSALoadKey_t HWCryptoHook_RSALoadKey; 443280297Sjkim/*- 444280297Sjkim * The key_ident is a null-terminated string configured by the 445160814Ssimon * user via the application's usual configuration mechanisms. 446160814Ssimon * It is provided to the user by the crypto provider's key management 447160814Ssimon * system. The user must be able to enter at least any string of between 448160814Ssimon * 1 and 1023 characters inclusive, consisting of printable 7-bit 449160814Ssimon * ASCII characters. The provider should avoid using 450160814Ssimon * any characters except alphanumerics and the punctuation 451160814Ssimon * characters _ - + . / @ ~ (the user is expected to be able 452160814Ssimon * to enter these without quoting). The string may be case-sensitive. 453160814Ssimon * The application may allow the user to enter other NULL-terminated strings, 454160814Ssimon * and the provider must cope (returning an error if the string is not 455160814Ssimon * valid). 456160814Ssimon * 457160814Ssimon * If the key does not exist, no error is recorded and 0 is returned; 458160814Ssimon * keyhandle_r will be set to 0 instead of to a key handle. 459160814Ssimon */ 460160814Ssimon 461160814Ssimontypedef 462160814Ssimonint HWCryptoHook_RSAGetPublicKey_t(HWCryptoHook_RSAKeyHandle k, 463280297Sjkim HWCryptoHook_MPI * n, 464280297Sjkim HWCryptoHook_MPI * e, 465280297Sjkim const HWCryptoHook_ErrMsgBuf * errors); 466160814Ssimonextern HWCryptoHook_RSAGetPublicKey_t HWCryptoHook_RSAGetPublicKey; 467280297Sjkim/*- 468280297Sjkim * The crypto plugin will not store certificates. 469160814Ssimon * 470160814Ssimon * Although this function for acquiring the public key value is 471160814Ssimon * provided, it is not the purpose of this API to deal fully with the 472160814Ssimon * handling of the public key. 473160814Ssimon * 474160814Ssimon * It is expected that the crypto supplier's key generation program 475160814Ssimon * will provide general facilities for producing X.509 476160814Ssimon * self-certificates and certificate requests in PEM format. These 477160814Ssimon * will be given to the user so that they can configure them in the 478160814Ssimon * application, send them to CAs, or whatever. 479160814Ssimon * 480160814Ssimon * In case this kind of certificate handling is not appropriate, the 481160814Ssimon * crypto supplier's key generation program should be able to be 482160814Ssimon * configured not to generate such a self-certificate or certificate 483160814Ssimon * request. Then the application will need to do all of this, and 484160814Ssimon * will need to store and handle the public key and certificates 485160814Ssimon * itself. 486160814Ssimon */ 487160814Ssimon 488160814Ssimontypedef 489160814Ssimonint HWCryptoHook_RSAUnloadKey_t(HWCryptoHook_RSAKeyHandle k, 490280297Sjkim const HWCryptoHook_ErrMsgBuf * errors); 491160814Ssimonextern HWCryptoHook_RSAUnloadKey_t HWCryptoHook_RSAUnloadKey; 492160814Ssimon/* Might fail due to locking problems, or other serious internal problems. */ 493160814Ssimon 494160814Ssimontypedef 495160814Ssimonint HWCryptoHook_RSA_t(HWCryptoHook_MPI m, 496160814Ssimon HWCryptoHook_RSAKeyHandle k, 497280297Sjkim HWCryptoHook_MPI * r, 498280297Sjkim const HWCryptoHook_ErrMsgBuf * errors); 499160814Ssimonextern HWCryptoHook_RSA_t HWCryptoHook_RSA; 500160814Ssimon/* RSA private key operation (sign or decrypt) - raw, unpadded. */ 501160814Ssimon 502280297Sjkim#endif /* HWCRYPTOHOOK_H */ 503