1296465Sdelphij/*- 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 72296465Sdelphij# define HWCRYPTOHOOK_H 73160814Ssimon 74296465Sdelphij# include <sys/types.h> 75296465Sdelphij# include <stdio.h> 76160814Ssimon 77296465Sdelphij# ifndef HWCRYPTOHOOK_DECLARE_APPTYPES 78296465Sdelphij# define HWCRYPTOHOOK_DECLARE_APPTYPES 1 79296465Sdelphij# endif 80160814Ssimon 81296465Sdelphij# define HWCRYPTOHOOK_ERROR_FAILED -1 82296465Sdelphij# define HWCRYPTOHOOK_ERROR_FALLBACK -2 83296465Sdelphij# define HWCRYPTOHOOK_ERROR_MPISIZE -3 84160814Ssimon 85296465Sdelphij# if HWCRYPTOHOOK_DECLARE_APPTYPES 86160814Ssimon 87296465Sdelphij/*- 88296465Sdelphij * 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; 99296465Sdelphijtypedef struct HWCryptoHook_PassphraseContextValue 100296465Sdelphij HWCryptoHook_PassphraseContext; 101160814Ssimontypedef struct HWCryptoHook_CallerContextValue HWCryptoHook_CallerContext; 102160814Ssimon 103296465Sdelphij# endif /* HWCRYPTOHOOK_DECLARE_APPTYPES */ 104160814Ssimon 105296465Sdelphij/*- 106296465Sdelphij * 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 { 114296465Sdelphij char *buf; 115296465Sdelphij size_t size; 116160814Ssimon} HWCryptoHook_ErrMsgBuf; 117296465Sdelphij/*- 118296465Sdelphij * 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. 123296465Sdelphij * 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 { 134296465Sdelphij unsigned char *buf; 135296465Sdelphij size_t size; 136160814Ssimon} HWCryptoHook_MPI; 137296465Sdelphij/*- 138296465Sdelphij * 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 149296465Sdelphij# define HWCryptoHook_InitFlags_FallbackModExp 0x0002UL 150296465Sdelphij# define HWCryptoHook_InitFlags_FallbackRSAImmed 0x0004UL 151296465Sdelphij/*- 152296465Sdelphij * 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 162296465Sdelphij# define HWCryptoHook_InitFlags_SimpleForkCheck 0x0010UL 163296465Sdelphij/*- 164296465Sdelphij * 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 { 177296465Sdelphij unsigned long flags; 178296465Sdelphij void *logstream; /* usually a FILE*. See below. */ 179296465Sdelphij size_t limbsize; /* bignum format - size of radix type, must 180296465Sdelphij * be power of 2 */ 181296465Sdelphij int mslimbfirst; /* 0 or 1 */ 182296465Sdelphij int msbytefirst; /* 0 or 1; -1 = native */ 183296465Sdelphij /*- 184296465Sdelphij * All the callback functions should return 0 on success, or a 185296465Sdelphij * nonzero integer (whose value will be visible in the error message 186296465Sdelphij * put in the buffer passed to the call). 187296465Sdelphij * 188296465Sdelphij * If a callback is not available pass a null function pointer. 189296465Sdelphij * 190296465Sdelphij * The callbacks may not call down again into the crypto plugin. 191296465Sdelphij */ 192296465Sdelphij /*- 193296465Sdelphij * For thread-safety. Set everything to 0 if you promise only to be 194296465Sdelphij * singlethreaded. maxsimultaneous is the number of calls to 195296465Sdelphij * ModExp[Crt]/RSAImmed{Priv,Pub}/RSA. If you don't know what to 196296465Sdelphij * put there then say 0 and the hook library will use a default. 197296465Sdelphij * 198296465Sdelphij * maxmutexes is a small limit on the number of simultaneous mutexes 199296465Sdelphij * which will be requested by the library. If there is no small 200296465Sdelphij * limit, set it to 0. If the crypto plugin cannot create the 201296465Sdelphij * advertised number of mutexes the calls to its functions may fail. 202296465Sdelphij * If a low number of mutexes is advertised the plugin will try to 203296465Sdelphij * do the best it can. Making larger numbers of mutexes available 204296465Sdelphij * may improve performance and parallelism by reducing contention 205296465Sdelphij * over critical sections. Unavailability of any mutexes, implying 206296465Sdelphij * single-threaded operation, should be indicated by the setting 207296465Sdelphij * mutex_init et al to 0. 208296465Sdelphij */ 209296465Sdelphij int maxmutexes; 210296465Sdelphij int maxsimultaneous; 211296465Sdelphij size_t mutexsize; 212296465Sdelphij int (*mutex_init) (HWCryptoHook_Mutex *, 213296465Sdelphij HWCryptoHook_CallerContext * cactx); 214296465Sdelphij int (*mutex_acquire) (HWCryptoHook_Mutex *); 215296465Sdelphij void (*mutex_release) (HWCryptoHook_Mutex *); 216296465Sdelphij void (*mutex_destroy) (HWCryptoHook_Mutex *); 217296465Sdelphij /*- 218296465Sdelphij * For greater efficiency, can use condition vars internally for 219296465Sdelphij * synchronisation. In this case maxsimultaneous is ignored, but 220296465Sdelphij * the other mutex stuff must be available. In singlethreaded 221296465Sdelphij * programs, set everything to 0. 222296465Sdelphij */ 223296465Sdelphij size_t condvarsize; 224296465Sdelphij int (*condvar_init) (HWCryptoHook_CondVar *, 225296465Sdelphij HWCryptoHook_CallerContext * cactx); 226296465Sdelphij int (*condvar_wait) (HWCryptoHook_CondVar *, HWCryptoHook_Mutex *); 227296465Sdelphij void (*condvar_signal) (HWCryptoHook_CondVar *); 228296465Sdelphij void (*condvar_broadcast) (HWCryptoHook_CondVar *); 229296465Sdelphij void (*condvar_destroy) (HWCryptoHook_CondVar *); 230296465Sdelphij /*- 231296465Sdelphij * The semantics of acquiring and releasing mutexes and broadcasting 232296465Sdelphij * and waiting on condition variables are expected to be those from 233296465Sdelphij * POSIX threads (pthreads). The mutexes may be (in pthread-speak) 234296465Sdelphij * fast mutexes, recursive mutexes, or nonrecursive ones. 235296465Sdelphij * 236296465Sdelphij * The _release/_signal/_broadcast and _destroy functions must 237296465Sdelphij * always succeed when given a valid argument; if they are given an 238296465Sdelphij * invalid argument then the program (crypto plugin + application) 239296465Sdelphij * has an internal error, and they should abort the program. 240296465Sdelphij */ 241296465Sdelphij int (*getpassphrase) (const char *prompt_info, 242296465Sdelphij int *len_io, char *buf, 243296465Sdelphij HWCryptoHook_PassphraseContext * ppctx, 244296465Sdelphij HWCryptoHook_CallerContext * cactx); 245296465Sdelphij /*- 246296465Sdelphij * Passphrases and the prompt_info, if they contain high-bit-set 247296465Sdelphij * characters, are UTF-8. The prompt_info may be a null pointer if 248296465Sdelphij * no prompt information is available (it should not be an empty 249296465Sdelphij * string). It will not contain text like `enter passphrase'; 250296465Sdelphij * instead it might say something like `Operator Card for John 251296465Sdelphij * Smith' or `SmartCard in nFast Module #1, Slot #1'. 252296465Sdelphij * 253296465Sdelphij * buf points to a buffer in which to return the passphrase; on 254296465Sdelphij * entry *len_io is the length of the buffer. It should be updated 255296465Sdelphij * by the callback. The returned passphrase should not be 256296465Sdelphij * null-terminated by the callback. 257296465Sdelphij */ 258296465Sdelphij int (*getphystoken) (const char *prompt_info, 259296465Sdelphij const char *wrong_info, 260296465Sdelphij HWCryptoHook_PassphraseContext * ppctx, 261296465Sdelphij HWCryptoHook_CallerContext * cactx); 262296465Sdelphij /*- 263296465Sdelphij * Requests that the human user physically insert a different 264296465Sdelphij * smartcard, DataKey, etc. The plugin should check whether the 265296465Sdelphij * currently inserted token(s) are appropriate, and if they are it 266296465Sdelphij * should not make this call. 267296465Sdelphij * 268296465Sdelphij * prompt_info is as before. wrong_info is a description of the 269296465Sdelphij * currently inserted token(s) so that the user is told what 270296465Sdelphij * something is. wrong_info, like prompt_info, may be null, but 271296465Sdelphij * should not be an empty string. Its contents should be 272296465Sdelphij * syntactically similar to that of prompt_info. 273296465Sdelphij */ 274296465Sdelphij /*- 275296465Sdelphij * Note that a single LoadKey operation might cause several calls to 276296465Sdelphij * getpassphrase and/or requestphystoken. If requestphystoken is 277296465Sdelphij * not provided (ie, a null pointer is passed) then the plugin may 278296465Sdelphij * not support loading keys for which authorisation by several cards 279296465Sdelphij * is required. If getpassphrase is not provided then cards with 280296465Sdelphij * passphrases may not be supported. 281296465Sdelphij * 282296465Sdelphij * getpassphrase and getphystoken do not need to check that the 283296465Sdelphij * passphrase has been entered correctly or the correct token 284296465Sdelphij * inserted; the crypto plugin will do that. If this is not the 285296465Sdelphij * case then the crypto plugin is responsible for calling these 286296465Sdelphij * routines again as appropriate until the correct token(s) and 287296465Sdelphij * passphrase(s) are supplied as required, or until any retry limits 288296465Sdelphij * implemented by the crypto plugin are reached. 289296465Sdelphij * 290296465Sdelphij * In either case, the application must allow the user to say `no' 291296465Sdelphij * or `cancel' to indicate that they do not know the passphrase or 292296465Sdelphij * have the appropriate token; this should cause the callback to 293296465Sdelphij * return nonzero indicating error. 294296465Sdelphij */ 295296465Sdelphij void (*logmessage) (void *logstream, const char *message); 296296465Sdelphij /*- 297296465Sdelphij * A log message will be generated at least every time something goes 298296465Sdelphij * wrong and an ErrMsgBuf is filled in (or would be if one was 299296465Sdelphij * provided). Other diagnostic information may be written there too, 300296465Sdelphij * including more detailed reasons for errors which are reported in an 301296465Sdelphij * ErrMsgBuf. 302296465Sdelphij * 303296465Sdelphij * When a log message is generated, this callback is called. It 304296465Sdelphij * should write a message to the relevant logging arrangements. 305296465Sdelphij * 306296465Sdelphij * The message string passed will be null-terminated and may be of arbitrary 307296465Sdelphij * length. It will not be prefixed by the time and date, nor by the 308296465Sdelphij * name of the library that is generating it - if this is required, 309296465Sdelphij * the logmessage callback must do it. The message will not have a 310296465Sdelphij * trailing newline (though it may contain internal newlines). 311296465Sdelphij * 312296465Sdelphij * If a null pointer is passed for logmessage a default function is 313296465Sdelphij * used. The default function treats logstream as a FILE* which has 314296465Sdelphij * been converted to a void*. If logstream is 0 it does nothing. 315296465Sdelphij * Otherwise it prepends the date and time and library name and 316296465Sdelphij * writes the message to logstream. Each line will be prefixed by a 317296465Sdelphij * descriptive string containing the date, time and identity of the 318296465Sdelphij * crypto plugin. Errors on the logstream are not reported 319296465Sdelphij * anywhere, and the default function doesn't flush the stream, so 320296465Sdelphij * the application must set the buffering how it wants it. 321296465Sdelphij * 322296465Sdelphij * The crypto plugin may also provide a facility to have copies of 323296465Sdelphij * log messages sent elsewhere, and or for adjusting the verbosity 324296465Sdelphij * of the log messages; any such facilities will be configured by 325296465Sdelphij * external means. 326296465Sdelphij */ 327160814Ssimon} HWCryptoHook_InitInfo; 328160814Ssimon 329160814Ssimontypedef 330296465SdelphijHWCryptoHook_ContextHandle HWCryptoHook_Init_t(const HWCryptoHook_InitInfo * 331296465Sdelphij initinfo, size_t initinfosize, 332296465Sdelphij const HWCryptoHook_ErrMsgBuf * 333296465Sdelphij errors, 334296465Sdelphij HWCryptoHook_CallerContext * 335296465Sdelphij cactx); 336160814Ssimonextern HWCryptoHook_Init_t HWCryptoHook_Init; 337160814Ssimon 338296465Sdelphij/*- 339296465Sdelphij * 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 348296465Sdelphij/*- 349296465Sdelphij * 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 360296465Sdelphij/*- 361296465Sdelphij * 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, 375296465Sdelphij 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, 383296465Sdelphij HWCryptoHook_MPI * r, 384296465Sdelphij 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, 392296465Sdelphij HWCryptoHook_MPI * r, 393296465Sdelphij 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, 404296465Sdelphij HWCryptoHook_MPI * r, 405296465Sdelphij 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, 416296465Sdelphij HWCryptoHook_MPI * r, 417296465Sdelphij const HWCryptoHook_ErrMsgBuf * errors); 418160814Ssimonextern HWCryptoHook_RSAImmedPriv_t HWCryptoHook_RSAImmedPriv; 419160814Ssimon 420296465Sdelphij/*- 421296465Sdelphij * 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, 439296465Sdelphij HWCryptoHook_RSAKeyHandle * keyhandle_r, 440296465Sdelphij const HWCryptoHook_ErrMsgBuf * errors, 441296465Sdelphij HWCryptoHook_PassphraseContext * ppctx); 442160814Ssimonextern HWCryptoHook_RSALoadKey_t HWCryptoHook_RSALoadKey; 443296465Sdelphij/*- 444296465Sdelphij * 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, 463296465Sdelphij HWCryptoHook_MPI * n, 464296465Sdelphij HWCryptoHook_MPI * e, 465296465Sdelphij const HWCryptoHook_ErrMsgBuf * errors); 466160814Ssimonextern HWCryptoHook_RSAGetPublicKey_t HWCryptoHook_RSAGetPublicKey; 467296465Sdelphij/*- 468296465Sdelphij * 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, 490296465Sdelphij 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, 497296465Sdelphij HWCryptoHook_MPI * r, 498296465Sdelphij const HWCryptoHook_ErrMsgBuf * errors); 499160814Ssimonextern HWCryptoHook_RSA_t HWCryptoHook_RSA; 500160814Ssimon/* RSA private key operation (sign or decrypt) - raw, unpadded. */ 501160814Ssimon 502296465Sdelphij#endif /* HWCRYPTOHOOK_H */ 503