2
* ModExp / RSA (with/without KM) plugin API
4
* The application will load a dynamic library which
5
* exports entrypoint(s) defined in this file.
7
* This set of entrypoints provides only a multithreaded,
8
* synchronous-within-each-thread, facility.
11
* This file is Copyright 1998-2000 nCipher Corporation Limited.
13
* Redistribution and use in source and binary forms, with opr without
14
* modification, are permitted provided that the following conditions
17
* 1. Redistributions of source code must retain the copyright notice,
18
* this list of conditions, and the following disclaimer.
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
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.
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.
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.
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.
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.
68
* $Id: hwcryptohook.h,v 1.3 2001/07/04 12:26:39 ben Exp $
71
#ifndef HWCRYPTOHOOK_H
72
#define HWCRYPTOHOOK_H
74
#include <sys/types.h>
77
#ifndef HWCRYPTOHOOK_DECLARE_APPTYPES
78
#define HWCRYPTOHOOK_DECLARE_APPTYPES 1
81
#define HWCRYPTOHOOK_ERROR_FAILED -1
82
#define HWCRYPTOHOOK_ERROR_FALLBACK -2
83
#define HWCRYPTOHOOK_ERROR_MPISIZE -3
85
#if HWCRYPTOHOOK_DECLARE_APPTYPES
87
/* These structs are defined by the application and opaque to the
88
* crypto plugin. The application may define these as it sees fit.
89
* Default declarations are provided here, but the application may
90
* #define HWCRYPTOHOOK_DECLARE_APPTYPES 0
91
* to prevent these declarations, and instead provide its own
92
* declarations of these types. (Pointers to them must still be
93
* ordinary pointers to structs or unions, or the resulting combined
94
* program will have a type inconsistency.)
96
typedef struct HWCryptoHook_MutexValue HWCryptoHook_Mutex;
97
typedef struct HWCryptoHook_CondVarValue HWCryptoHook_CondVar;
98
typedef struct HWCryptoHook_PassphraseContextValue HWCryptoHook_PassphraseContext;
99
typedef struct HWCryptoHook_CallerContextValue HWCryptoHook_CallerContext;
101
#endif /* HWCRYPTOHOOK_DECLARE_APPTYPES */
103
/* These next two structs are opaque to the application. The crypto
104
* plugin will return pointers to them; the caller simply manipulates
107
typedef struct HWCryptoHook_Context *HWCryptoHook_ContextHandle;
108
typedef struct HWCryptoHook_RSAKey *HWCryptoHook_RSAKeyHandle;
113
} HWCryptoHook_ErrMsgBuf;
114
/* Used for error reporting. When a HWCryptoHook function fails it
115
* will return a sentinel value (0 for pointer-valued functions, or a
116
* negative number, usually HWCRYPTOHOOK_ERROR_FAILED, for
117
* integer-valued ones). It will, if an ErrMsgBuf is passed, also put
118
* an error message there.
120
* size is the size of the buffer, and will not be modified. If you
121
* pass 0 for size you must pass 0 for buf, and nothing will be
122
* recorded (just as if you passed 0 for the struct pointer).
123
* Messages written to the buffer will always be null-terminated, even
124
* when truncated to fit within size bytes.
126
* The contents of the buffer are not defined if there is no error.
129
typedef struct HWCryptoHook_MPIStruct {
133
/* When one of these is returned, a pointer is passed to the function.
134
* At call, size is the space available. Afterwards it is updated to
135
* be set to the actual length (which may be more than the space available,
136
* if there was not enough room and the result was truncated).
137
* buf (the pointer) is not updated.
139
* size is in bytes and may be zero at call or return, but must be a
140
* multiple of the limb size. Zero limbs at the MS end are not
144
#define HWCryptoHook_InitFlags_FallbackModExp 0x0002UL
145
#define HWCryptoHook_InitFlags_FallbackRSAImmed 0x0004UL
146
/* Enable requesting fallback to software in case of problems with the
147
* hardware support. This indicates to the crypto provider that the
148
* application is prepared to fall back to software operation if the
149
* ModExp* or RSAImmed* functions return HWCRYPTOHOOK_ERROR_FALLBACK.
150
* Without this flag those calls will never return
151
* HWCRYPTOHOOK_ERROR_FALLBACK. The flag will also cause the crypto
152
* provider to avoid repeatedly attempting to contact dead hardware
153
* within a short interval, if appropriate.
156
#define HWCryptoHook_InitFlags_SimpleForkCheck 0x0010UL
157
/* Without _SimpleForkCheck the library is allowed to assume that the
158
* application will not fork and call the library in the child(ren).
160
* When it is specified, this is allowed. However, after a fork
161
* neither parent nor child may unload any loaded keys or call
162
* _Finish. Instead, they should call exit (or die with a signal)
163
* without calling _Finish. After all the children have died the
164
* parent may unload keys or call _Finish.
166
* This flag only has any effect on UN*X platforms.
171
void *logstream; /* usually a FILE*. See below. */
173
size_t limbsize; /* bignum format - size of radix type, must be power of 2 */
174
int mslimbfirst; /* 0 or 1 */
175
int msbytefirst; /* 0 or 1; -1 = native */
177
/* All the callback functions should return 0 on success, or a
178
* nonzero integer (whose value will be visible in the error message
179
* put in the buffer passed to the call).
181
* If a callback is not available pass a null function pointer.
183
* The callbacks may not call down again into the crypto plugin.
186
/* For thread-safety. Set everything to 0 if you promise only to be
187
* singlethreaded. maxsimultaneous is the number of calls to
188
* ModExp[Crt]/RSAImmed{Priv,Pub}/RSA. If you don't know what to
189
* put there then say 0 and the hook library will use a default.
191
* maxmutexes is a small limit on the number of simultaneous mutexes
192
* which will be requested by the library. If there is no small
193
* limit, set it to 0. If the crypto plugin cannot create the
194
* advertised number of mutexes the calls to its functions may fail.
195
* If a low number of mutexes is advertised the plugin will try to
196
* do the best it can. Making larger numbers of mutexes available
197
* may improve performance and parallelism by reducing contention
198
* over critical sections. Unavailability of any mutexes, implying
199
* single-threaded operation, should be indicated by the setting
200
* mutex_init et al to 0.
205
int (*mutex_init)(HWCryptoHook_Mutex*, HWCryptoHook_CallerContext *cactx);
206
int (*mutex_acquire)(HWCryptoHook_Mutex*);
207
void (*mutex_release)(HWCryptoHook_Mutex*);
208
void (*mutex_destroy)(HWCryptoHook_Mutex*);
210
/* For greater efficiency, can use condition vars internally for
211
* synchronisation. In this case maxsimultaneous is ignored, but
212
* the other mutex stuff must be available. In singlethreaded
213
* programs, set everything to 0.
216
int (*condvar_init)(HWCryptoHook_CondVar*, HWCryptoHook_CallerContext *cactx);
217
int (*condvar_wait)(HWCryptoHook_CondVar*, HWCryptoHook_Mutex*);
218
void (*condvar_signal)(HWCryptoHook_CondVar*);
219
void (*condvar_broadcast)(HWCryptoHook_CondVar*);
220
void (*condvar_destroy)(HWCryptoHook_CondVar*);
222
/* The semantics of acquiring and releasing mutexes and broadcasting
223
* and waiting on condition variables are expected to be those from
224
* POSIX threads (pthreads). The mutexes may be (in pthread-speak)
225
* fast mutexes, recursive mutexes, or nonrecursive ones.
227
* The _release/_signal/_broadcast and _destroy functions must
228
* always succeed when given a valid argument; if they are given an
229
* invalid argument then the program (crypto plugin + application)
230
* has an internal error, and they should abort the program.
233
int (*getpassphrase)(const char *prompt_info,
234
int *len_io, char *buf,
235
HWCryptoHook_PassphraseContext *ppctx,
236
HWCryptoHook_CallerContext *cactx);
237
/* Passphrases and the prompt_info, if they contain high-bit-set
238
* characters, are UTF-8. The prompt_info may be a null pointer if
239
* no prompt information is available (it should not be an empty
240
* string). It will not contain text like `enter passphrase';
241
* instead it might say something like `Operator Card for John
242
* Smith' or `SmartCard in nFast Module #1, Slot #1'.
244
* buf points to a buffer in which to return the passphrase; on
245
* entry *len_io is the length of the buffer. It should be updated
246
* by the callback. The returned passphrase should not be
247
* null-terminated by the callback.
250
int (*getphystoken)(const char *prompt_info,
251
const char *wrong_info,
252
HWCryptoHook_PassphraseContext *ppctx,
253
HWCryptoHook_CallerContext *cactx);
254
/* Requests that the human user physically insert a different
255
* smartcard, DataKey, etc. The plugin should check whether the
256
* currently inserted token(s) are appropriate, and if they are it
257
* should not make this call.
259
* prompt_info is as before. wrong_info is a description of the
260
* currently inserted token(s) so that the user is told what
261
* something is. wrong_info, like prompt_info, may be null, but
262
* should not be an empty string. Its contents should be
263
* syntactically similar to that of prompt_info.
266
/* Note that a single LoadKey operation might cause several calls to
267
* getpassphrase and/or requestphystoken. If requestphystoken is
268
* not provided (ie, a null pointer is passed) then the plugin may
269
* not support loading keys for which authorisation by several cards
270
* is required. If getpassphrase is not provided then cards with
271
* passphrases may not be supported.
273
* getpassphrase and getphystoken do not need to check that the
274
* passphrase has been entered correctly or the correct token
275
* inserted; the crypto plugin will do that. If this is not the
276
* case then the crypto plugin is responsible for calling these
277
* routines again as appropriate until the correct token(s) and
278
* passphrase(s) are supplied as required, or until any retry limits
279
* implemented by the crypto plugin are reached.
281
* In either case, the application must allow the user to say `no'
282
* or `cancel' to indicate that they do not know the passphrase or
283
* have the appropriate token; this should cause the callback to
284
* return nonzero indicating error.
287
void (*logmessage)(void *logstream, const char *message);
288
/* A log message will be generated at least every time something goes
289
* wrong and an ErrMsgBuf is filled in (or would be if one was
290
* provided). Other diagnostic information may be written there too,
291
* including more detailed reasons for errors which are reported in an
294
* When a log message is generated, this callback is called. It
295
* should write a message to the relevant logging arrangements.
297
* The message string passed will be null-terminated and may be of arbitrary
298
* length. It will not be prefixed by the time and date, nor by the
299
* name of the library that is generating it - if this is required,
300
* the logmessage callback must do it. The message will not have a
301
* trailing newline (though it may contain internal newlines).
303
* If a null pointer is passed for logmessage a default function is
304
* used. The default function treats logstream as a FILE* which has
305
* been converted to a void*. If logstream is 0 it does nothing.
306
* Otherwise it prepends the date and time and library name and
307
* writes the message to logstream. Each line will be prefixed by a
308
* descriptive string containing the date, time and identity of the
309
* crypto plugin. Errors on the logstream are not reported
310
* anywhere, and the default function doesn't flush the stream, so
311
* the application must set the buffering how it wants it.
313
* The crypto plugin may also provide a facility to have copies of
314
* log messages sent elsewhere, and or for adjusting the verbosity
315
* of the log messages; any such facilities will be configured by
319
} HWCryptoHook_InitInfo;
322
HWCryptoHook_ContextHandle HWCryptoHook_Init_t(const HWCryptoHook_InitInfo *initinfo,
324
const HWCryptoHook_ErrMsgBuf *errors,
325
HWCryptoHook_CallerContext *cactx);
326
extern HWCryptoHook_Init_t HWCryptoHook_Init;
328
/* Caller should set initinfosize to the size of the HWCryptoHook struct,
329
* so it can be extended later.
331
* On success, a message for display or logging by the server,
332
* including the name and version number of the plugin, will be filled
333
* in into *errors; on failure *errors is used for error handling, as
337
/* All these functions return 0 on success, HWCRYPTOHOOK_ERROR_FAILED
338
* on most failures. HWCRYPTOHOOK_ERROR_MPISIZE means at least one of
339
* the output MPI buffer(s) was too small; the sizes of all have been
340
* set to the desired size (and for those where the buffer was large
341
* enough, the value may have been copied in), and no error message
344
* You may pass 0 for the errors struct. In any case, unless you set
345
* _NoStderr at init time then messages may be reported to stderr.
348
/* The RSAImmed* functions (and key managed RSA) only work with
349
* modules which have an RSA patent licence - currently that means KM
350
* units; the ModExp* ones work with all modules, so you need a patent
351
* licence in the software in the US. They are otherwise identical.
355
void HWCryptoHook_Finish_t(HWCryptoHook_ContextHandle hwctx);
356
extern HWCryptoHook_Finish_t HWCryptoHook_Finish;
357
/* You must not have any calls going or keys loaded when you call this. */
360
int HWCryptoHook_RandomBytes_t(HWCryptoHook_ContextHandle hwctx,
361
unsigned char *buf, size_t len,
362
const HWCryptoHook_ErrMsgBuf *errors);
363
extern HWCryptoHook_RandomBytes_t HWCryptoHook_RandomBytes;
366
int HWCryptoHook_ModExp_t(HWCryptoHook_ContextHandle hwctx,
371
const HWCryptoHook_ErrMsgBuf *errors);
372
extern HWCryptoHook_ModExp_t HWCryptoHook_ModExp;
375
int HWCryptoHook_RSAImmedPub_t(HWCryptoHook_ContextHandle hwctx,
380
const HWCryptoHook_ErrMsgBuf *errors);
381
extern HWCryptoHook_RSAImmedPub_t HWCryptoHook_RSAImmedPub;
384
int HWCryptoHook_ModExpCRT_t(HWCryptoHook_ContextHandle hwctx,
388
HWCryptoHook_MPI dmp1,
389
HWCryptoHook_MPI dmq1,
390
HWCryptoHook_MPI iqmp,
392
const HWCryptoHook_ErrMsgBuf *errors);
393
extern HWCryptoHook_ModExpCRT_t HWCryptoHook_ModExpCRT;
396
int HWCryptoHook_RSAImmedPriv_t(HWCryptoHook_ContextHandle hwctx,
400
HWCryptoHook_MPI dmp1,
401
HWCryptoHook_MPI dmq1,
402
HWCryptoHook_MPI iqmp,
404
const HWCryptoHook_ErrMsgBuf *errors);
405
extern HWCryptoHook_RSAImmedPriv_t HWCryptoHook_RSAImmedPriv;
407
/* The RSAImmed* and ModExp* functions may return E_FAILED or
408
* E_FALLBACK for failure.
410
* E_FAILED means the failure is permanent and definite and there
411
* should be no attempt to fall back to software. (Eg, for some
412
* applications, which support only the acceleration-only
413
* functions, the `key material' may actually be an encoded key
414
* identifier, and doing the operation in software would give wrong
417
* E_FALLBACK means that doing the computation in software would seem
418
* reasonable. If an application pays attention to this and is
419
* able to fall back, it should also set the Fallback init flags.
423
int HWCryptoHook_RSALoadKey_t(HWCryptoHook_ContextHandle hwctx,
424
const char *key_ident,
425
HWCryptoHook_RSAKeyHandle *keyhandle_r,
426
const HWCryptoHook_ErrMsgBuf *errors,
427
HWCryptoHook_PassphraseContext *ppctx);
428
extern HWCryptoHook_RSALoadKey_t HWCryptoHook_RSALoadKey;
429
/* The key_ident is a null-terminated string configured by the
430
* user via the application's usual configuration mechanisms.
431
* It is provided to the user by the crypto provider's key management
432
* system. The user must be able to enter at least any string of between
433
* 1 and 1023 characters inclusive, consisting of printable 7-bit
434
* ASCII characters. The provider should avoid using
435
* any characters except alphanumerics and the punctuation
436
* characters _ - + . / @ ~ (the user is expected to be able
437
* to enter these without quoting). The string may be case-sensitive.
438
* The application may allow the user to enter other NULL-terminated strings,
439
* and the provider must cope (returning an error if the string is not
442
* If the key does not exist, no error is recorded and 0 is returned;
443
* keyhandle_r will be set to 0 instead of to a key handle.
447
int HWCryptoHook_RSAGetPublicKey_t(HWCryptoHook_RSAKeyHandle k,
450
const HWCryptoHook_ErrMsgBuf *errors);
451
extern HWCryptoHook_RSAGetPublicKey_t HWCryptoHook_RSAGetPublicKey;
452
/* The crypto plugin will not store certificates.
454
* Although this function for acquiring the public key value is
455
* provided, it is not the purpose of this API to deal fully with the
456
* handling of the public key.
458
* It is expected that the crypto supplier's key generation program
459
* will provide general facilities for producing X.509
460
* self-certificates and certificate requests in PEM format. These
461
* will be given to the user so that they can configure them in the
462
* application, send them to CAs, or whatever.
464
* In case this kind of certificate handling is not appropriate, the
465
* crypto supplier's key generation program should be able to be
466
* configured not to generate such a self-certificate or certificate
467
* request. Then the application will need to do all of this, and
468
* will need to store and handle the public key and certificates
473
int HWCryptoHook_RSAUnloadKey_t(HWCryptoHook_RSAKeyHandle k,
474
const HWCryptoHook_ErrMsgBuf *errors);
475
extern HWCryptoHook_RSAUnloadKey_t HWCryptoHook_RSAUnloadKey;
476
/* Might fail due to locking problems, or other serious internal problems. */
479
int HWCryptoHook_RSA_t(HWCryptoHook_MPI m,
480
HWCryptoHook_RSAKeyHandle k,
482
const HWCryptoHook_ErrMsgBuf *errors);
483
extern HWCryptoHook_RSA_t HWCryptoHook_RSA;
484
/* RSA private key operation (sign or decrypt) - raw, unpadded. */
486
#endif /*HWCRYPTOHOOK_H*/
added
removed
crypto/engine/vendor_defns/hwcryptohook.h
