hwcryptohook.h revision 296465
121308Sache/*- 221308Sache * ModExp / RSA (with/without KM) plugin API 321308Sache * 421308Sache * The application will load a dynamic library which 521308Sache * exports entrypoint(s) defined in this file. 621308Sache * 721308Sache * This set of entrypoints provides only a multithreaded, 821308Sache * synchronous-within-each-thread, facility. 921308Sache * 1058310Sache * 1121308Sache * This file is Copyright 1998-2000 nCipher Corporation Limited. 1221308Sache * 1321308Sache * Redistribution and use in source and binary forms, with opr without 1421308Sache * modification, are permitted provided that the following conditions 1521308Sache * are met: 1621308Sache * 1721308Sache * 1. Redistributions of source code must retain the copyright notice, 1821308Sache * this list of conditions, and the following disclaimer. 1921308Sache * 2021308Sache * 2. Redistributions in binary form must reproduce the above 2158310Sache * copyright notice, this list of conditions, and the following 2221308Sache * disclaimer, in the documentation and/or other materials provided 2321308Sache * with the distribution 2421308Sache * 2521308Sache * IN NO EVENT SHALL NCIPHER CORPORATION LIMITED (`NCIPHER') AND/OR 2621308Sache * ANY OTHER AUTHORS OR DISTRIBUTORS OF THIS FILE BE LIABLE for any 2721308Sache * damages arising directly or indirectly from this file, its use or 2821308Sache * this licence. Without prejudice to the generality of the 2921308Sache * foregoing: all liability shall be excluded for direct, indirect, 3021308Sache * special, incidental, consequential or other damages or any loss of 3121308Sache * profits, business, revenue goodwill or anticipated savings; 3221308Sache * liability shall be excluded even if nCipher or anyone else has been 3321308Sache * advised of the possibility of damage. In any event, if the 3421308Sache * exclusion of liability is not effective, the liability of nCipher 3521308Sache * or any author or distributor shall be limited to the lesser of the 3621308Sache * price paid and 1,000 pounds sterling. This licence only fails to 3721308Sache * exclude or limit liability for death or personal injury arising out 3821308Sache * of negligence, and only to the extent that such an exclusion or 3921308Sache * limitation is not effective. 4021308Sache * 4121308Sache * NCIPHER AND THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ALL 4221308Sache * AND ANY WARRANTIES (WHETHER EXPRESS OR IMPLIED), including, but not 4321308Sache * limited to, any implied warranties of merchantability, fitness for 4421308Sache * a particular purpose, satisfactory quality, and/or non-infringement 4521308Sache * of any third party rights. 4621308Sache * 4721308Sache * US Government use: This software and documentation is Commercial 4821308Sache * Computer Software and Computer Software Documentation, as defined in 4958310Sache * sub-paragraphs (a)(1) and (a)(5) of DFAR 252.227-7014, "Rights in 5058310Sache * Noncommercial Computer Software and Noncommercial Computer Software 5121308Sache * Documentation." Use, duplication or disclosure by the Government is 5221308Sache * subject to the terms and conditions specified here. 5321308Sache * 5421308Sache * By using or distributing this file you will be accepting these 5521308Sache * terms and conditions, including the limitation of liability and 5621308Sache * lack of warranty. If you do not wish to accept these terms and 5721308Sache * conditions, DO NOT USE THE FILE. 5821308Sache * 5921308Sache * 6021308Sache * The actual dynamically loadable plugin, and the library files for 6121308Sache * static linking, which are also provided in some distributions, are 6221308Sache * not covered by the licence described above. You should have 6321308Sache * received a separate licence with terms and conditions for these 6421308Sache * library files; if you received the library files without a licence, 6521308Sache * please contact nCipher. 6621308Sache * 6721308Sache * 6821308Sache * $Id: hwcryptohook.h,v 1.1 2002/10/11 17:10:59 levitte Exp $ 6921308Sache */ 7021308Sache 7121308Sache#ifndef HWCRYPTOHOOK_H 7221308Sache# define HWCRYPTOHOOK_H 73119610Sache 74119610Sache# include <sys/types.h> 75119610Sache# include <stdio.h> 76119610Sache 77119610Sache# ifndef HWCRYPTOHOOK_DECLARE_APPTYPES 7821308Sache# define HWCRYPTOHOOK_DECLARE_APPTYPES 1 7921308Sache# endif 8021308Sache 8121308Sache# define HWCRYPTOHOOK_ERROR_FAILED -1 8221308Sache# define HWCRYPTOHOOK_ERROR_FALLBACK -2 8321308Sache# define HWCRYPTOHOOK_ERROR_MPISIZE -3 8421308Sache 8521308Sache# if HWCRYPTOHOOK_DECLARE_APPTYPES 8621308Sache 8721308Sache/*- 8821308Sache * These structs are defined by the application and opaque to the 8921308Sache * crypto plugin. The application may define these as it sees fit. 9021308Sache * Default declarations are provided here, but the application may 9121308Sache * #define HWCRYPTOHOOK_DECLARE_APPTYPES 0 9221308Sache * to prevent these declarations, and instead provide its own 9321308Sache * declarations of these types. (Pointers to them must still be 9421308Sache * ordinary pointers to structs or unions, or the resulting combined 9521308Sache * program will have a type inconsistency.) 9621308Sache */ 9721308Sachetypedef struct HWCryptoHook_MutexValue HWCryptoHook_Mutex; 9821308Sachetypedef struct HWCryptoHook_CondVarValue HWCryptoHook_CondVar; 9921308Sachetypedef struct HWCryptoHook_PassphraseContextValue 10021308Sache HWCryptoHook_PassphraseContext; 10121308Sachetypedef struct HWCryptoHook_CallerContextValue HWCryptoHook_CallerContext; 10221308Sache 10321308Sache# endif /* HWCRYPTOHOOK_DECLARE_APPTYPES */ 10421308Sache 10521308Sache/*- 10621308Sache * These next two structs are opaque to the application. The crypto 10721308Sache * plugin will return pointers to them; the caller simply manipulates 10821308Sache * the pointers. 10921308Sache */ 11021308Sachetypedef struct HWCryptoHook_Context *HWCryptoHook_ContextHandle; 11121308Sachetypedef struct HWCryptoHook_RSAKey *HWCryptoHook_RSAKeyHandle; 11221308Sache 11321308Sachetypedef struct { 11421308Sache char *buf; 11521308Sache size_t size; 11621308Sache} HWCryptoHook_ErrMsgBuf; 11721308Sache/*- 11821308Sache * Used for error reporting. When a HWCryptoHook function fails it 11921308Sache * will return a sentinel value (0 for pointer-valued functions, or a 12021308Sache * negative number, usually HWCRYPTOHOOK_ERROR_FAILED, for 12121308Sache * integer-valued ones). It will, if an ErrMsgBuf is passed, also put 12221308Sache * an error message there. 12321308Sache * 12421308Sache * size is the size of the buffer, and will not be modified. If you 12521308Sache * pass 0 for size you must pass 0 for buf, and nothing will be 12621308Sache * recorded (just as if you passed 0 for the struct pointer). 12721308Sache * Messages written to the buffer will always be null-terminated, even 12821308Sache * when truncated to fit within size bytes. 12921308Sache * 13021308Sache * The contents of the buffer are not defined if there is no error. 13121308Sache */ 13221308Sache 13321308Sachetypedef struct HWCryptoHook_MPIStruct { 13421308Sache unsigned char *buf; 13521308Sache size_t size; 13621308Sache} HWCryptoHook_MPI; 137119610Sache/*- 13821308Sache * When one of these is returned, a pointer is passed to the function. 13921308Sache * At call, size is the space available. Afterwards it is updated to 14021308Sache * be set to the actual length (which may be more than the space available, 14121308Sache * if there was not enough room and the result was truncated). 14221308Sache * buf (the pointer) is not updated. 14321308Sache * 14421308Sache * size is in bytes and may be zero at call or return, but must be a 14521308Sache * multiple of the limb size. Zero limbs at the MS end are not 14621308Sache * permitted. 14721308Sache */ 14821308Sache 14921308Sache# define HWCryptoHook_InitFlags_FallbackModExp 0x0002UL 15021308Sache# define HWCryptoHook_InitFlags_FallbackRSAImmed 0x0004UL 15121308Sache/*- 15221308Sache * Enable requesting fallback to software in case of problems with the 15321308Sache * hardware support. This indicates to the crypto provider that the 15421308Sache * application is prepared to fall back to software operation if the 15521308Sache * ModExp* or RSAImmed* functions return HWCRYPTOHOOK_ERROR_FALLBACK. 15621308Sache * Without this flag those calls will never return 15721308Sache * HWCRYPTOHOOK_ERROR_FALLBACK. The flag will also cause the crypto 15821308Sache * provider to avoid repeatedly attempting to contact dead hardware 15921308Sache * within a short interval, if appropriate. 16021308Sache */ 16121308Sache 16221308Sache# define HWCryptoHook_InitFlags_SimpleForkCheck 0x0010UL 16321308Sache/*- 16421308Sache * Without _SimpleForkCheck the library is allowed to assume that the 16521308Sache * application will not fork and call the library in the child(ren). 16621308Sache * 16721308Sache * When it is specified, this is allowed. However, after a fork 16821308Sache * neither parent nor child may unload any loaded keys or call 16921308Sache * _Finish. Instead, they should call exit (or die with a signal) 17021308Sache * without calling _Finish. After all the children have died the 17121308Sache * parent may unload keys or call _Finish. 17221308Sache * 17321308Sache * This flag only has any effect on UN*X platforms. 17421308Sache */ 17521308Sache 17621308Sachetypedef struct { 17721308Sache unsigned long flags; 17821308Sache void *logstream; /* usually a FILE*. See below. */ 17921308Sache size_t limbsize; /* bignum format - size of radix type, must 18021308Sache * be power of 2 */ 18121308Sache int mslimbfirst; /* 0 or 1 */ 18221308Sache int msbytefirst; /* 0 or 1; -1 = native */ 18321308Sache /*- 18421308Sache * All the callback functions should return 0 on success, or a 18521308Sache * nonzero integer (whose value will be visible in the error message 18621308Sache * put in the buffer passed to the call). 18721308Sache * 18821308Sache * If a callback is not available pass a null function pointer. 18921308Sache * 19021308Sache * The callbacks may not call down again into the crypto plugin. 19121308Sache */ 19221308Sache /*- 19321308Sache * For thread-safety. Set everything to 0 if you promise only to be 19421308Sache * singlethreaded. maxsimultaneous is the number of calls to 19521308Sache * ModExp[Crt]/RSAImmed{Priv,Pub}/RSA. If you don't know what to 19621308Sache * put there then say 0 and the hook library will use a default. 19721308Sache * 19821308Sache * maxmutexes is a small limit on the number of simultaneous mutexes 19921308Sache * which will be requested by the library. If there is no small 20021308Sache * limit, set it to 0. If the crypto plugin cannot create the 20121308Sache * advertised number of mutexes the calls to its functions may fail. 20221308Sache * If a low number of mutexes is advertised the plugin will try to 20321308Sache * do the best it can. Making larger numbers of mutexes available 204119610Sache * may improve performance and parallelism by reducing contention 20521308Sache * over critical sections. Unavailability of any mutexes, implying 20621308Sache * single-threaded operation, should be indicated by the setting 20721308Sache * mutex_init et al to 0. 20821308Sache */ 20921308Sache int maxmutexes; 210119610Sache int maxsimultaneous; 21121308Sache size_t mutexsize; 21221308Sache int (*mutex_init) (HWCryptoHook_Mutex *, 21321308Sache HWCryptoHook_CallerContext * cactx); 21421308Sache int (*mutex_acquire) (HWCryptoHook_Mutex *); 21521308Sache void (*mutex_release) (HWCryptoHook_Mutex *); 21621308Sache void (*mutex_destroy) (HWCryptoHook_Mutex *); 217119610Sache /*- 218119610Sache * For greater efficiency, can use condition vars internally for 21921308Sache * synchronisation. In this case maxsimultaneous is ignored, but 22021308Sache * the other mutex stuff must be available. In singlethreaded 22121308Sache * programs, set everything to 0. 22221308Sache */ 22321308Sache size_t condvarsize; 22421308Sache int (*condvar_init) (HWCryptoHook_CondVar *, 22521308Sache HWCryptoHook_CallerContext * cactx); 22621308Sache int (*condvar_wait) (HWCryptoHook_CondVar *, HWCryptoHook_Mutex *); 22721308Sache void (*condvar_signal) (HWCryptoHook_CondVar *); 228119610Sache void (*condvar_broadcast) (HWCryptoHook_CondVar *); 22921308Sache void (*condvar_destroy) (HWCryptoHook_CondVar *); 23021308Sache /*- 23121308Sache * The semantics of acquiring and releasing mutexes and broadcasting 23221308Sache * and waiting on condition variables are expected to be those from 23321308Sache * POSIX threads (pthreads). The mutexes may be (in pthread-speak) 234119610Sache * fast mutexes, recursive mutexes, or nonrecursive ones. 23521308Sache * 23621308Sache * The _release/_signal/_broadcast and _destroy functions must 23721308Sache * always succeed when given a valid argument; if they are given an 23821308Sache * invalid argument then the program (crypto plugin + application) 239119610Sache * has an internal error, and they should abort the program. 240119610Sache */ 241119610Sache int (*getpassphrase) (const char *prompt_info, 24221308Sache int *len_io, char *buf, 24321308Sache HWCryptoHook_PassphraseContext * ppctx, 24421308Sache HWCryptoHook_CallerContext * cactx); 24521308Sache /*- 24621308Sache * Passphrases and the prompt_info, if they contain high-bit-set 24721308Sache * characters, are UTF-8. The prompt_info may be a null pointer if 24821308Sache * no prompt information is available (it should not be an empty 24921308Sache * string). It will not contain text like `enter passphrase'; 25021308Sache * instead it might say something like `Operator Card for John 25121308Sache * Smith' or `SmartCard in nFast Module #1, Slot #1'. 252119610Sache * 25321308Sache * buf points to a buffer in which to return the passphrase; on 25421308Sache * entry *len_io is the length of the buffer. It should be updated 25521308Sache * by the callback. The returned passphrase should not be 25621308Sache * null-terminated by the callback. 25721308Sache */ 258119610Sache int (*getphystoken) (const char *prompt_info, 25921308Sache const char *wrong_info, 26021308Sache HWCryptoHook_PassphraseContext * ppctx, 26121308Sache HWCryptoHook_CallerContext * cactx); 26221308Sache /*- 263119610Sache * Requests that the human user physically insert a different 264119610Sache * smartcard, DataKey, etc. The plugin should check whether the 26521308Sache * currently inserted token(s) are appropriate, and if they are it 26621308Sache * should not make this call. 26721308Sache * 26821308Sache * prompt_info is as before. wrong_info is a description of the 26921308Sache * currently inserted token(s) so that the user is told what 27021308Sache * something is. wrong_info, like prompt_info, may be null, but 27121308Sache * should not be an empty string. Its contents should be 27221308Sache * syntactically similar to that of prompt_info. 27321308Sache */ 27421308Sache /*- 275119610Sache * Note that a single LoadKey operation might cause several calls to 27621308Sache * getpassphrase and/or requestphystoken. If requestphystoken is 27721308Sache * not provided (ie, a null pointer is passed) then the plugin may 27821308Sache * not support loading keys for which authorisation by several cards 27921308Sache * is required. If getpassphrase is not provided then cards with 28021308Sache * passphrases may not be supported. 28121308Sache * 28275406Sache * getpassphrase and getphystoken do not need to check that the 28321308Sache * passphrase has been entered correctly or the correct token 28421308Sache * inserted; the crypto plugin will do that. If this is not the 285119610Sache * case then the crypto plugin is responsible for calling these 28621308Sache * routines again as appropriate until the correct token(s) and 287119610Sache * passphrase(s) are supplied as required, or until any retry limits 288119610Sache * implemented by the crypto plugin are reached. 289119610Sache * 290119610Sache * In either case, the application must allow the user to say `no' 29121308Sache * or `cancel' to indicate that they do not know the passphrase or 29221308Sache * have the appropriate token; this should cause the callback to 29321308Sache * return nonzero indicating error. 29421308Sache */ 29521308Sache void (*logmessage) (void *logstream, const char *message); 29621308Sache /*- 29721308Sache * A log message will be generated at least every time something goes 29821308Sache * wrong and an ErrMsgBuf is filled in (or would be if one was 29921308Sache * provided). Other diagnostic information may be written there too, 30021308Sache * including more detailed reasons for errors which are reported in an 30121308Sache * ErrMsgBuf. 30221308Sache * 30321308Sache * When a log message is generated, this callback is called. It 304119610Sache * should write a message to the relevant logging arrangements. 30521308Sache * 30621308Sache * The message string passed will be null-terminated and may be of arbitrary 30721308Sache * length. It will not be prefixed by the time and date, nor by the 30821308Sache * name of the library that is generating it - if this is required, 30921308Sache * the logmessage callback must do it. The message will not have a 31021308Sache * trailing newline (though it may contain internal newlines). 31121308Sache * 31221308Sache * If a null pointer is passed for logmessage a default function is 31321308Sache * used. The default function treats logstream as a FILE* which has 31421308Sache * been converted to a void*. If logstream is 0 it does nothing. 31521308Sache * Otherwise it prepends the date and time and library name and 31621308Sache * writes the message to logstream. Each line will be prefixed by a 31721308Sache * descriptive string containing the date, time and identity of the 31821308Sache * crypto plugin. Errors on the logstream are not reported 31921308Sache * anywhere, and the default function doesn't flush the stream, so 32021308Sache * the application must set the buffering how it wants it. 32121308Sache * 32275406Sache * The crypto plugin may also provide a facility to have copies of 32321308Sache * log messages sent elsewhere, and or for adjusting the verbosity 32421308Sache * of the log messages; any such facilities will be configured by 32521308Sache * external means. 32621308Sache */ 32721308Sache} HWCryptoHook_InitInfo; 32821308Sache 32921308Sachetypedef 33021308SacheHWCryptoHook_ContextHandle HWCryptoHook_Init_t(const HWCryptoHook_InitInfo * 33121308Sache initinfo, size_t initinfosize, 33221308Sache const HWCryptoHook_ErrMsgBuf * 33321308Sache errors, 33421308Sache HWCryptoHook_CallerContext * 33521308Sache cactx); 33621308Sacheextern HWCryptoHook_Init_t HWCryptoHook_Init; 33721308Sache 33821308Sache/*- 339119610Sache * Caller should set initinfosize to the size of the HWCryptoHook struct, 340119610Sache * so it can be extended later. 34121308Sache * 342136644Sache * On success, a message for display or logging by the server, 34321308Sache * including the name and version number of the plugin, will be filled 34421308Sache * in into *errors; on failure *errors is used for error handling, as 34521308Sache * usual. 346136644Sache */ 347136644Sache 348136644Sache/*- 349136644Sache * All these functions return 0 on success, HWCRYPTOHOOK_ERROR_FAILED 350136644Sache * on most failures. HWCRYPTOHOOK_ERROR_MPISIZE means at least one of 351136644Sache * the output MPI buffer(s) was too small; the sizes of all have been 352136644Sache * set to the desired size (and for those where the buffer was large 353136644Sache * enough, the value may have been copied in), and no error message 354136644Sache * has been recorded. 355136644Sache * 356136644Sache * You may pass 0 for the errors struct. In any case, unless you set 357136644Sache * _NoStderr at init time then messages may be reported to stderr. 358136644Sache */ 359136644Sache 360136644Sache/*- 361136644Sache * The RSAImmed* functions (and key managed RSA) only work with 362136644Sache * modules which have an RSA patent licence - currently that means KM 363136644Sache * units; the ModExp* ones work with all modules, so you need a patent 364136644Sache * licence in the software in the US. They are otherwise identical. 365136644Sache */ 366136644Sache 367136644Sachetypedef 368136644Sachevoid HWCryptoHook_Finish_t(HWCryptoHook_ContextHandle hwctx); 369136644Sacheextern HWCryptoHook_Finish_t HWCryptoHook_Finish; 370136644Sache/* You must not have any calls going or keys loaded when you call this. */ 371136644Sache 372136644Sachetypedef 373136644Sacheint HWCryptoHook_RandomBytes_t(HWCryptoHook_ContextHandle hwctx, 374136644Sache unsigned char *buf, size_t len, 375136644Sache const HWCryptoHook_ErrMsgBuf * errors); 376136644Sacheextern HWCryptoHook_RandomBytes_t HWCryptoHook_RandomBytes; 377136644Sache 378136644Sachetypedef 379136644Sacheint HWCryptoHook_ModExp_t(HWCryptoHook_ContextHandle hwctx, 380136644Sache HWCryptoHook_MPI a, 381136644Sache HWCryptoHook_MPI p, 382136644Sache HWCryptoHook_MPI n, 383136644Sache HWCryptoHook_MPI * r, 384136644Sache const HWCryptoHook_ErrMsgBuf * errors); 385136644Sacheextern HWCryptoHook_ModExp_t HWCryptoHook_ModExp; 38621308Sache 38721308Sachetypedef 38821308Sacheint HWCryptoHook_RSAImmedPub_t(HWCryptoHook_ContextHandle hwctx, 38921308Sache HWCryptoHook_MPI m, 39021308Sache HWCryptoHook_MPI e, 39121308Sache HWCryptoHook_MPI n, 39221308Sache HWCryptoHook_MPI * r, 39321308Sache const HWCryptoHook_ErrMsgBuf * errors); 39421308Sacheextern HWCryptoHook_RSAImmedPub_t HWCryptoHook_RSAImmedPub; 39521308Sache 39621308Sachetypedef 39775406Sacheint HWCryptoHook_ModExpCRT_t(HWCryptoHook_ContextHandle hwctx, 39821308Sache HWCryptoHook_MPI a, 39921308Sache HWCryptoHook_MPI p, 40021308Sache HWCryptoHook_MPI q, 40121308Sache HWCryptoHook_MPI dmp1, 402119610Sache HWCryptoHook_MPI dmq1, 403119610Sache HWCryptoHook_MPI iqmp, 40421308Sache HWCryptoHook_MPI * r, 40521308Sache const HWCryptoHook_ErrMsgBuf * errors); 40621308Sacheextern HWCryptoHook_ModExpCRT_t HWCryptoHook_ModExpCRT; 40721308Sache 40821308Sachetypedef 40921308Sacheint HWCryptoHook_RSAImmedPriv_t(HWCryptoHook_ContextHandle hwctx, 41021308Sache HWCryptoHook_MPI m, 41121308Sache HWCryptoHook_MPI p, 41221308Sache HWCryptoHook_MPI q, 41321308Sache HWCryptoHook_MPI dmp1, 41421308Sache HWCryptoHook_MPI dmq1, 41521308Sache HWCryptoHook_MPI iqmp, 416119610Sache HWCryptoHook_MPI * r, 41721308Sache const HWCryptoHook_ErrMsgBuf * errors); 418119610Sacheextern HWCryptoHook_RSAImmedPriv_t HWCryptoHook_RSAImmedPriv; 419119610Sache 420119610Sache/*- 421119610Sache * The RSAImmed* and ModExp* functions may return E_FAILED or 42221308Sache * E_FALLBACK for failure. 42321308Sache * 42421308Sache * E_FAILED means the failure is permanent and definite and there 42521308Sache * should be no attempt to fall back to software. (Eg, for some 42621308Sache * applications, which support only the acceleration-only 42721308Sache * functions, the `key material' may actually be an encoded key 42821308Sache * identifier, and doing the operation in software would give wrong 42921308Sache * answers.) 43021308Sache * 43121308Sache * E_FALLBACK means that doing the computation in software would seem 43221308Sache * reasonable. If an application pays attention to this and is 43321308Sache * able to fall back, it should also set the Fallback init flags. 43421308Sache */ 43521308Sache 43621308Sachetypedef 43721308Sacheint HWCryptoHook_RSALoadKey_t(HWCryptoHook_ContextHandle hwctx, 43821308Sache const char *key_ident, 43921308Sache HWCryptoHook_RSAKeyHandle * keyhandle_r, 44021308Sache const HWCryptoHook_ErrMsgBuf * errors, 44158310Sache HWCryptoHook_PassphraseContext * ppctx); 44226497Sacheextern HWCryptoHook_RSALoadKey_t HWCryptoHook_RSALoadKey; 44358310Sache/*- 44426497Sache * The key_ident is a null-terminated string configured by the 44526497Sache * user via the application's usual configuration mechanisms. 44658310Sache * It is provided to the user by the crypto provider's key management 44726497Sache * system. The user must be able to enter at least any string of between 44821308Sache * 1 and 1023 characters inclusive, consisting of printable 7-bit 44921308Sache * ASCII characters. The provider should avoid using 45021308Sache * any characters except alphanumerics and the punctuation 45121308Sache * characters _ - + . / @ ~ (the user is expected to be able 45221308Sache * to enter these without quoting). The string may be case-sensitive. 45321308Sache * The application may allow the user to enter other NULL-terminated strings, 45421308Sache * and the provider must cope (returning an error if the string is not 45521308Sache * valid). 45621308Sache * 45721308Sache * If the key does not exist, no error is recorded and 0 is returned; 45821308Sache * keyhandle_r will be set to 0 instead of to a key handle. 45921308Sache */ 46021308Sache 46121308Sachetypedef 46221308Sacheint HWCryptoHook_RSAGetPublicKey_t(HWCryptoHook_RSAKeyHandle k, 46321308Sache HWCryptoHook_MPI * n, 46421308Sache HWCryptoHook_MPI * e, 46521308Sache const HWCryptoHook_ErrMsgBuf * errors); 46621308Sacheextern HWCryptoHook_RSAGetPublicKey_t HWCryptoHook_RSAGetPublicKey; 46721308Sache/*- 46821308Sache * The crypto plugin will not store certificates. 46921308Sache * 47021308Sache * Although this function for acquiring the public key value is 47121308Sache * provided, it is not the purpose of this API to deal fully with the 47221308Sache * handling of the public key. 47321308Sache * 47421308Sache * It is expected that the crypto supplier's key generation program 47521308Sache * will provide general facilities for producing X.509 47621308Sache * self-certificates and certificate requests in PEM format. These 47721308Sache * will be given to the user so that they can configure them in the 47821308Sache * application, send them to CAs, or whatever. 47921308Sache * 48021308Sache * In case this kind of certificate handling is not appropriate, the 48121308Sache * crypto supplier's key generation program should be able to be 48221308Sache * configured not to generate such a self-certificate or certificate 48321308Sache * request. Then the application will need to do all of this, and 48421308Sache * will need to store and handle the public key and certificates 48521308Sache * itself. 48621308Sache */ 48721308Sache 48821308Sachetypedef 48921308Sacheint HWCryptoHook_RSAUnloadKey_t(HWCryptoHook_RSAKeyHandle k, 49021308Sache const HWCryptoHook_ErrMsgBuf * errors); 49121308Sacheextern HWCryptoHook_RSAUnloadKey_t HWCryptoHook_RSAUnloadKey; 49221308Sache/* Might fail due to locking problems, or other serious internal problems. */ 49321308Sache 49421308Sachetypedef 49521308Sacheint HWCryptoHook_RSA_t(HWCryptoHook_MPI m, 49621308Sache HWCryptoHook_RSAKeyHandle k, 49721308Sache HWCryptoHook_MPI * r, 49821308Sache const HWCryptoHook_ErrMsgBuf * errors); 49921308Sacheextern HWCryptoHook_RSA_t HWCryptoHook_RSA; 50021308Sache/* RSA private key operation (sign or decrypt) - raw, unpadded. */ 50121308Sache 50221308Sache#endif /* HWCRYPTOHOOK_H */ 50321308Sache