diff options
Diffstat (limited to 'openssl/engines/vendor_defns/hwcryptohook.h')
| -rw-r--r-- | openssl/engines/vendor_defns/hwcryptohook.h | 382 |
1 files changed, 199 insertions, 183 deletions
diff --git a/openssl/engines/vendor_defns/hwcryptohook.h b/openssl/engines/vendor_defns/hwcryptohook.h index 482f1f2d1..9fc7b89ac 100644 --- a/openssl/engines/vendor_defns/hwcryptohook.h +++ b/openssl/engines/vendor_defns/hwcryptohook.h @@ -1,4 +1,4 @@ -/* +/*- * ModExp / RSA (with/without KM) plugin API * * The application will load a dynamic library which @@ -69,22 +69,23 @@ */ #ifndef HWCRYPTOHOOK_H -#define HWCRYPTOHOOK_H +# define HWCRYPTOHOOK_H -#include <sys/types.h> -#include <stdio.h> +# include <sys/types.h> +# include <stdio.h> -#ifndef HWCRYPTOHOOK_DECLARE_APPTYPES -#define HWCRYPTOHOOK_DECLARE_APPTYPES 1 -#endif +# ifndef HWCRYPTOHOOK_DECLARE_APPTYPES +# define HWCRYPTOHOOK_DECLARE_APPTYPES 1 +# endif -#define HWCRYPTOHOOK_ERROR_FAILED -1 -#define HWCRYPTOHOOK_ERROR_FALLBACK -2 -#define HWCRYPTOHOOK_ERROR_MPISIZE -3 +# define HWCRYPTOHOOK_ERROR_FAILED -1 +# define HWCRYPTOHOOK_ERROR_FALLBACK -2 +# define HWCRYPTOHOOK_ERROR_MPISIZE -3 -#if HWCRYPTOHOOK_DECLARE_APPTYPES +# if HWCRYPTOHOOK_DECLARE_APPTYPES -/* These structs are defined by the application and opaque to the +/*- + * These structs are defined by the application and opaque to the * crypto plugin. The application may define these as it sees fit. * Default declarations are provided here, but the application may * #define HWCRYPTOHOOK_DECLARE_APPTYPES 0 @@ -95,12 +96,14 @@ */ typedef struct HWCryptoHook_MutexValue HWCryptoHook_Mutex; typedef struct HWCryptoHook_CondVarValue HWCryptoHook_CondVar; -typedef struct HWCryptoHook_PassphraseContextValue HWCryptoHook_PassphraseContext; +typedef struct HWCryptoHook_PassphraseContextValue + HWCryptoHook_PassphraseContext; typedef struct HWCryptoHook_CallerContextValue HWCryptoHook_CallerContext; -#endif /* HWCRYPTOHOOK_DECLARE_APPTYPES */ +# endif /* HWCRYPTOHOOK_DECLARE_APPTYPES */ -/* These next two structs are opaque to the application. The crypto +/*- + * These next two structs are opaque to the application. The crypto * plugin will return pointers to them; the caller simply manipulates * the pointers. */ @@ -108,15 +111,16 @@ typedef struct HWCryptoHook_Context *HWCryptoHook_ContextHandle; typedef struct HWCryptoHook_RSAKey *HWCryptoHook_RSAKeyHandle; typedef struct { - char *buf; - size_t size; + char *buf; + size_t size; } HWCryptoHook_ErrMsgBuf; -/* Used for error reporting. When a HWCryptoHook function fails it +/*- + * Used for error reporting. When a HWCryptoHook function fails it * will return a sentinel value (0 for pointer-valued functions, or a * negative number, usually HWCRYPTOHOOK_ERROR_FAILED, for * integer-valued ones). It will, if an ErrMsgBuf is passed, also put * an error message there. - * + * * size is the size of the buffer, and will not be modified. If you * pass 0 for size you must pass 0 for buf, and nothing will be * recorded (just as if you passed 0 for the struct pointer). @@ -127,10 +131,11 @@ typedef struct { */ typedef struct HWCryptoHook_MPIStruct { - unsigned char *buf; - size_t size; + unsigned char *buf; + size_t size; } HWCryptoHook_MPI; -/* When one of these is returned, a pointer is passed to the function. +/*- + * When one of these is returned, a pointer is passed to the function. * At call, size is the space available. Afterwards it is updated to * be set to the actual length (which may be more than the space available, * if there was not enough room and the result was truncated). @@ -141,9 +146,10 @@ typedef struct HWCryptoHook_MPIStruct { * permitted. */ -#define HWCryptoHook_InitFlags_FallbackModExp 0x0002UL -#define HWCryptoHook_InitFlags_FallbackRSAImmed 0x0004UL -/* Enable requesting fallback to software in case of problems with the +# define HWCryptoHook_InitFlags_FallbackModExp 0x0002UL +# define HWCryptoHook_InitFlags_FallbackRSAImmed 0x0004UL +/*- + * Enable requesting fallback to software in case of problems with the * hardware support. This indicates to the crypto provider that the * application is prepared to fall back to software operation if the * ModExp* or RSAImmed* functions return HWCRYPTOHOOK_ERROR_FALLBACK. @@ -153,8 +159,9 @@ typedef struct HWCryptoHook_MPIStruct { * within a short interval, if appropriate. */ -#define HWCryptoHook_InitFlags_SimpleForkCheck 0x0010UL -/* Without _SimpleForkCheck the library is allowed to assume that the +# define HWCryptoHook_InitFlags_SimpleForkCheck 0x0010UL +/*- + * Without _SimpleForkCheck the library is allowed to assume that the * application will not fork and call the library in the child(ren). * * When it is specified, this is allowed. However, after a fork @@ -167,14 +174,14 @@ typedef struct HWCryptoHook_MPIStruct { */ typedef struct { - unsigned long flags; - void *logstream; /* usually a FILE*. See below. */ - - size_t limbsize; /* bignum format - size of radix type, must be power of 2 */ - int mslimbfirst; /* 0 or 1 */ - int msbytefirst; /* 0 or 1; -1 = native */ - - /* All the callback functions should return 0 on success, or a + unsigned long flags; + void *logstream; /* usually a FILE*. See below. */ + size_t limbsize; /* bignum format - size of radix type, must + * be power of 2 */ + int mslimbfirst; /* 0 or 1 */ + int msbytefirst; /* 0 or 1; -1 = native */ + /*- + * All the callback functions should return 0 on success, or a * nonzero integer (whose value will be visible in the error message * put in the buffer passed to the call). * @@ -182,8 +189,8 @@ typedef struct { * * The callbacks may not call down again into the crypto plugin. */ - - /* For thread-safety. Set everything to 0 if you promise only to be + /*- + * For thread-safety. Set everything to 0 if you promise only to be * singlethreaded. maxsimultaneous is the number of calls to * ModExp[Crt]/RSAImmed{Priv,Pub}/RSA. If you don't know what to * put there then say 0 and the hook library will use a default. @@ -199,133 +206,137 @@ typedef struct { * single-threaded operation, should be indicated by the setting * mutex_init et al to 0. */ - int maxmutexes; - int maxsimultaneous; - size_t mutexsize; - int (*mutex_init)(HWCryptoHook_Mutex*, HWCryptoHook_CallerContext *cactx); - int (*mutex_acquire)(HWCryptoHook_Mutex*); - void (*mutex_release)(HWCryptoHook_Mutex*); - void (*mutex_destroy)(HWCryptoHook_Mutex*); - - /* For greater efficiency, can use condition vars internally for - * synchronisation. In this case maxsimultaneous is ignored, but - * the other mutex stuff must be available. In singlethreaded - * programs, set everything to 0. - */ - size_t condvarsize; - int (*condvar_init)(HWCryptoHook_CondVar*, HWCryptoHook_CallerContext *cactx); - int (*condvar_wait)(HWCryptoHook_CondVar*, HWCryptoHook_Mutex*); - void (*condvar_signal)(HWCryptoHook_CondVar*); - void (*condvar_broadcast)(HWCryptoHook_CondVar*); - void (*condvar_destroy)(HWCryptoHook_CondVar*); - - /* The semantics of acquiring and releasing mutexes and broadcasting - * and waiting on condition variables are expected to be those from - * POSIX threads (pthreads). The mutexes may be (in pthread-speak) - * fast mutexes, recursive mutexes, or nonrecursive ones. - * - * The _release/_signal/_broadcast and _destroy functions must - * always succeed when given a valid argument; if they are given an - * invalid argument then the program (crypto plugin + application) - * has an internal error, and they should abort the program. - */ - - int (*getpassphrase)(const char *prompt_info, - int *len_io, char *buf, - HWCryptoHook_PassphraseContext *ppctx, - HWCryptoHook_CallerContext *cactx); - /* Passphrases and the prompt_info, if they contain high-bit-set - * characters, are UTF-8. The prompt_info may be a null pointer if - * no prompt information is available (it should not be an empty - * string). It will not contain text like `enter passphrase'; - * instead it might say something like `Operator Card for John - * Smith' or `SmartCard in nFast Module #1, Slot #1'. - * - * buf points to a buffer in which to return the passphrase; on - * entry *len_io is the length of the buffer. It should be updated - * by the callback. The returned passphrase should not be - * null-terminated by the callback. - */ - - int (*getphystoken)(const char *prompt_info, - const char *wrong_info, - HWCryptoHook_PassphraseContext *ppctx, - HWCryptoHook_CallerContext *cactx); - /* Requests that the human user physically insert a different - * smartcard, DataKey, etc. The plugin should check whether the - * currently inserted token(s) are appropriate, and if they are it - * should not make this call. - * - * prompt_info is as before. wrong_info is a description of the - * currently inserted token(s) so that the user is told what - * something is. wrong_info, like prompt_info, may be null, but - * should not be an empty string. Its contents should be - * syntactically similar to that of prompt_info. - */ - - /* Note that a single LoadKey operation might cause several calls to - * getpassphrase and/or requestphystoken. If requestphystoken is - * not provided (ie, a null pointer is passed) then the plugin may - * not support loading keys for which authorisation by several cards - * is required. If getpassphrase is not provided then cards with - * passphrases may not be supported. - * - * getpassphrase and getphystoken do not need to check that the - * passphrase has been entered correctly or the correct token - * inserted; the crypto plugin will do that. If this is not the - * case then the crypto plugin is responsible for calling these - * routines again as appropriate until the correct token(s) and - * passphrase(s) are supplied as required, or until any retry limits - * implemented by the crypto plugin are reached. - * - * In either case, the application must allow the user to say `no' - * or `cancel' to indicate that they do not know the passphrase or - * have the appropriate token; this should cause the callback to - * return nonzero indicating error. - */ - - void (*logmessage)(void *logstream, const char *message); - /* A log message will be generated at least every time something goes - * wrong and an ErrMsgBuf is filled in (or would be if one was - * provided). Other diagnostic information may be written there too, - * including more detailed reasons for errors which are reported in an - * ErrMsgBuf. - * - * When a log message is generated, this callback is called. It - * should write a message to the relevant logging arrangements. - * - * The message string passed will be null-terminated and may be of arbitrary - * length. It will not be prefixed by the time and date, nor by the - * name of the library that is generating it - if this is required, - * the logmessage callback must do it. The message will not have a - * trailing newline (though it may contain internal newlines). - * - * If a null pointer is passed for logmessage a default function is - * used. The default function treats logstream as a FILE* which has - * been converted to a void*. If logstream is 0 it does nothing. - * Otherwise it prepends the date and time and library name and - * writes the message to logstream. Each line will be prefixed by a - * descriptive string containing the date, time and identity of the - * crypto plugin. Errors on the logstream are not reported - * anywhere, and the default function doesn't flush the stream, so - * the application must set the buffering how it wants it. - * - * The crypto plugin may also provide a facility to have copies of - * log messages sent elsewhere, and or for adjusting the verbosity - * of the log messages; any such facilities will be configured by - * external means. - */ - + int maxmutexes; + int maxsimultaneous; + size_t mutexsize; + int (*mutex_init) (HWCryptoHook_Mutex *, + HWCryptoHook_CallerContext * cactx); + int (*mutex_acquire) (HWCryptoHook_Mutex *); + void (*mutex_release) (HWCryptoHook_Mutex *); + void (*mutex_destroy) (HWCryptoHook_Mutex *); + /*- + * For greater efficiency, can use condition vars internally for + * synchronisation. In this case maxsimultaneous is ignored, but + * the other mutex stuff must be available. In singlethreaded + * programs, set everything to 0. + */ + size_t condvarsize; + int (*condvar_init) (HWCryptoHook_CondVar *, + HWCryptoHook_CallerContext * cactx); + int (*condvar_wait) (HWCryptoHook_CondVar *, HWCryptoHook_Mutex *); + void (*condvar_signal) (HWCryptoHook_CondVar *); + void (*condvar_broadcast) (HWCryptoHook_CondVar *); + void (*condvar_destroy) (HWCryptoHook_CondVar *); + /*- + * The semantics of acquiring and releasing mutexes and broadcasting + * and waiting on condition variables are expected to be those from + * POSIX threads (pthreads). The mutexes may be (in pthread-speak) + * fast mutexes, recursive mutexes, or nonrecursive ones. + * + * The _release/_signal/_broadcast and _destroy functions must + * always succeed when given a valid argument; if they are given an + * invalid argument then the program (crypto plugin + application) + * has an internal error, and they should abort the program. + */ + int (*getpassphrase) (const char *prompt_info, + int *len_io, char *buf, + HWCryptoHook_PassphraseContext * ppctx, + HWCryptoHook_CallerContext * cactx); + /*- + * Passphrases and the prompt_info, if they contain high-bit-set + * characters, are UTF-8. The prompt_info may be a null pointer if + * no prompt information is available (it should not be an empty + * string). It will not contain text like `enter passphrase'; + * instead it might say something like `Operator Card for John + * Smith' or `SmartCard in nFast Module #1, Slot #1'. + * + * buf points to a buffer in which to return the passphrase; on + * entry *len_io is the length of the buffer. It should be updated + * by the callback. The returned passphrase should not be + * null-terminated by the callback. + */ + int (*getphystoken) (const char *prompt_info, + const char *wrong_info, + HWCryptoHook_PassphraseContext * ppctx, + HWCryptoHook_CallerContext * cactx); + /*- + * Requests that the human user physically insert a different + * smartcard, DataKey, etc. The plugin should check whether the + * currently inserted token(s) are appropriate, and if they are it + * should not make this call. + * + * prompt_info is as before. wrong_info is a description of the + * currently inserted token(s) so that the user is told what + * something is. wrong_info, like prompt_info, may be null, but + * should not be an empty string. Its contents should be + * syntactically similar to that of prompt_info. + */ + /*- + * Note that a single LoadKey operation might cause several calls to + * getpassphrase and/or requestphystoken. If requestphystoken is + * not provided (ie, a null pointer is passed) then the plugin may + * not support loading keys for which authorisation by several cards + * is required. If getpassphrase is not provided then cards with + * passphrases may not be supported. + * + * getpassphrase and getphystoken do not need to check that the + * passphrase has been entered correctly or the correct token + * inserted; the crypto plugin will do that. If this is not the + * case then the crypto plugin is responsible for calling these + * routines again as appropriate until the correct token(s) and + * passphrase(s) are supplied as required, or until any retry limits + * implemented by the crypto plugin are reached. + * + * In either case, the application must allow the user to say `no' + * or `cancel' to indicate that they do not know the passphrase or + * have the appropriate token; this should cause the callback to + * return nonzero indicating error. + */ + void (*logmessage) (void *logstream, const char *message); + /*- + * A log message will be generated at least every time something goes + * wrong and an ErrMsgBuf is filled in (or would be if one was + * provided). Other diagnostic information may be written there too, + * including more detailed reasons for errors which are reported in an + * ErrMsgBuf. + * + * When a log message is generated, this callback is called. It + * should write a message to the relevant logging arrangements. + * + * The message string passed will be null-terminated and may be of arbitrary + * length. It will not be prefixed by the time and date, nor by the + * name of the library that is generating it - if this is required, + * the logmessage callback must do it. The message will not have a + * trailing newline (though it may contain internal newlines). + * + * If a null pointer is passed for logmessage a default function is + * used. The default function treats logstream as a FILE* which has + * been converted to a void*. If logstream is 0 it does nothing. + * Otherwise it prepends the date and time and library name and + * writes the message to logstream. Each line will be prefixed by a + * descriptive string containing the date, time and identity of the + * crypto plugin. Errors on the logstream are not reported + * anywhere, and the default function doesn't flush the stream, so + * the application must set the buffering how it wants it. + * + * The crypto plugin may also provide a facility to have copies of + * log messages sent elsewhere, and or for adjusting the verbosity + * of the log messages; any such facilities will be configured by + * external means. + */ } HWCryptoHook_InitInfo; typedef -HWCryptoHook_ContextHandle HWCryptoHook_Init_t(const HWCryptoHook_InitInfo *initinfo, - size_t initinfosize, - const HWCryptoHook_ErrMsgBuf *errors, - HWCryptoHook_CallerContext *cactx); +HWCryptoHook_ContextHandle HWCryptoHook_Init_t(const HWCryptoHook_InitInfo * + initinfo, size_t initinfosize, + const HWCryptoHook_ErrMsgBuf * + errors, + HWCryptoHook_CallerContext * + cactx); extern HWCryptoHook_Init_t HWCryptoHook_Init; -/* Caller should set initinfosize to the size of the HWCryptoHook struct, +/*- + * Caller should set initinfosize to the size of the HWCryptoHook struct, * so it can be extended later. * * On success, a message for display or logging by the server, @@ -334,7 +345,8 @@ extern HWCryptoHook_Init_t HWCryptoHook_Init; * usual. */ -/* All these functions return 0 on success, HWCRYPTOHOOK_ERROR_FAILED +/*- + * All these functions return 0 on success, HWCRYPTOHOOK_ERROR_FAILED * on most failures. HWCRYPTOHOOK_ERROR_MPISIZE means at least one of * the output MPI buffer(s) was too small; the sizes of all have been * set to the desired size (and for those where the buffer was large @@ -345,7 +357,8 @@ extern HWCryptoHook_Init_t HWCryptoHook_Init; * _NoStderr at init time then messages may be reported to stderr. */ -/* The RSAImmed* functions (and key managed RSA) only work with +/*- + * The RSAImmed* functions (and key managed RSA) only work with * modules which have an RSA patent licence - currently that means KM * units; the ModExp* ones work with all modules, so you need a patent * licence in the software in the US. They are otherwise identical. @@ -359,7 +372,7 @@ extern HWCryptoHook_Finish_t HWCryptoHook_Finish; typedef int HWCryptoHook_RandomBytes_t(HWCryptoHook_ContextHandle hwctx, unsigned char *buf, size_t len, - const HWCryptoHook_ErrMsgBuf *errors); + const HWCryptoHook_ErrMsgBuf * errors); extern HWCryptoHook_RandomBytes_t HWCryptoHook_RandomBytes; typedef @@ -367,8 +380,8 @@ int HWCryptoHook_ModExp_t(HWCryptoHook_ContextHandle hwctx, HWCryptoHook_MPI a, HWCryptoHook_MPI p, HWCryptoHook_MPI n, - HWCryptoHook_MPI *r, - const HWCryptoHook_ErrMsgBuf *errors); + HWCryptoHook_MPI * r, + const HWCryptoHook_ErrMsgBuf * errors); extern HWCryptoHook_ModExp_t HWCryptoHook_ModExp; typedef @@ -376,8 +389,8 @@ int HWCryptoHook_RSAImmedPub_t(HWCryptoHook_ContextHandle hwctx, HWCryptoHook_MPI m, HWCryptoHook_MPI e, HWCryptoHook_MPI n, - HWCryptoHook_MPI *r, - const HWCryptoHook_ErrMsgBuf *errors); + HWCryptoHook_MPI * r, + const HWCryptoHook_ErrMsgBuf * errors); extern HWCryptoHook_RSAImmedPub_t HWCryptoHook_RSAImmedPub; typedef @@ -388,8 +401,8 @@ int HWCryptoHook_ModExpCRT_t(HWCryptoHook_ContextHandle hwctx, HWCryptoHook_MPI dmp1, HWCryptoHook_MPI dmq1, HWCryptoHook_MPI iqmp, - HWCryptoHook_MPI *r, - const HWCryptoHook_ErrMsgBuf *errors); + HWCryptoHook_MPI * r, + const HWCryptoHook_ErrMsgBuf * errors); extern HWCryptoHook_ModExpCRT_t HWCryptoHook_ModExpCRT; typedef @@ -400,11 +413,12 @@ int HWCryptoHook_RSAImmedPriv_t(HWCryptoHook_ContextHandle hwctx, HWCryptoHook_MPI dmp1, HWCryptoHook_MPI dmq1, HWCryptoHook_MPI iqmp, - HWCryptoHook_MPI *r, - const HWCryptoHook_ErrMsgBuf *errors); + HWCryptoHook_MPI * r, + const HWCryptoHook_ErrMsgBuf * errors); extern HWCryptoHook_RSAImmedPriv_t HWCryptoHook_RSAImmedPriv; -/* The RSAImmed* and ModExp* functions may return E_FAILED or +/*- + * The RSAImmed* and ModExp* functions may return E_FAILED or * E_FALLBACK for failure. * * E_FAILED means the failure is permanent and definite and there @@ -422,11 +436,12 @@ extern HWCryptoHook_RSAImmedPriv_t HWCryptoHook_RSAImmedPriv; typedef int HWCryptoHook_RSALoadKey_t(HWCryptoHook_ContextHandle hwctx, const char *key_ident, - HWCryptoHook_RSAKeyHandle *keyhandle_r, - const HWCryptoHook_ErrMsgBuf *errors, - HWCryptoHook_PassphraseContext *ppctx); + HWCryptoHook_RSAKeyHandle * keyhandle_r, + const HWCryptoHook_ErrMsgBuf * errors, + HWCryptoHook_PassphraseContext * ppctx); extern HWCryptoHook_RSALoadKey_t HWCryptoHook_RSALoadKey; -/* The key_ident is a null-terminated string configured by the +/*- + * The key_ident is a null-terminated string configured by the * user via the application's usual configuration mechanisms. * It is provided to the user by the crypto provider's key management * system. The user must be able to enter at least any string of between @@ -445,11 +460,12 @@ extern HWCryptoHook_RSALoadKey_t HWCryptoHook_RSALoadKey; typedef int HWCryptoHook_RSAGetPublicKey_t(HWCryptoHook_RSAKeyHandle k, - HWCryptoHook_MPI *n, - HWCryptoHook_MPI *e, - const HWCryptoHook_ErrMsgBuf *errors); + HWCryptoHook_MPI * n, + HWCryptoHook_MPI * e, + const HWCryptoHook_ErrMsgBuf * errors); extern HWCryptoHook_RSAGetPublicKey_t HWCryptoHook_RSAGetPublicKey; -/* The crypto plugin will not store certificates. +/*- + * The crypto plugin will not store certificates. * * Although this function for acquiring the public key value is * provided, it is not the purpose of this API to deal fully with the @@ -471,16 +487,16 @@ extern HWCryptoHook_RSAGetPublicKey_t HWCryptoHook_RSAGetPublicKey; typedef int HWCryptoHook_RSAUnloadKey_t(HWCryptoHook_RSAKeyHandle k, - const HWCryptoHook_ErrMsgBuf *errors); + const HWCryptoHook_ErrMsgBuf * errors); extern HWCryptoHook_RSAUnloadKey_t HWCryptoHook_RSAUnloadKey; /* Might fail due to locking problems, or other serious internal problems. */ typedef int HWCryptoHook_RSA_t(HWCryptoHook_MPI m, HWCryptoHook_RSAKeyHandle k, - HWCryptoHook_MPI *r, - const HWCryptoHook_ErrMsgBuf *errors); + HWCryptoHook_MPI * r, + const HWCryptoHook_ErrMsgBuf * errors); extern HWCryptoHook_RSA_t HWCryptoHook_RSA; /* RSA private key operation (sign or decrypt) - raw, unpadded. */ -#endif /*HWCRYPTOHOOK_H*/ +#endif /* HWCRYPTOHOOK_H */ |