secmod.h (9710B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 #ifndef _SECMOD_H_ 5 #define _SECMOD_H_ 6 #include "seccomon.h" 7 #include "secmodt.h" 8 #include "prinrval.h" 9 #include "pkcs11.h" 10 11 /* These mechanisms flags are visible to all other libraries. */ 12 /* They must be converted to internal SECMOD_*_FLAG */ 13 /* if used inside the functions of the security library */ 14 #define PUBLIC_MECH_RSA_FLAG 0x00000001ul 15 #define PUBLIC_MECH_DSA_FLAG 0x00000002ul 16 #define PUBLIC_MECH_RC2_FLAG 0x00000004ul 17 #define PUBLIC_MECH_RC4_FLAG 0x00000008ul 18 #define PUBLIC_MECH_DES_FLAG 0x00000010ul 19 #define PUBLIC_MECH_DH_FLAG 0x00000020ul 20 #define PUBLIC_MECH_FORTEZZA_FLAG 0x00000040ul 21 #define PUBLIC_MECH_RC5_FLAG 0x00000080ul 22 #define PUBLIC_MECH_SHA1_FLAG 0x00000100ul 23 #define PUBLIC_MECH_MD5_FLAG 0x00000200ul 24 #define PUBLIC_MECH_MD2_FLAG 0x00000400ul 25 #define PUBLIC_MECH_SSL_FLAG 0x00000800ul 26 #define PUBLIC_MECH_TLS_FLAG 0x00001000ul 27 #define PUBLIC_MECH_AES_FLAG 0x00002000ul 28 #define PUBLIC_MECH_SHA256_FLAG 0x00004000ul 29 #define PUBLIC_MECH_SHA512_FLAG 0x00008000ul 30 #define PUBLIC_MECH_CAMELLIA_FLAG 0x00010000ul 31 #define PUBLIC_MECH_SEED_FLAG 0x00020000ul 32 #define PUBLIC_MECH_ECC_FLAG 0x00040000ul 33 34 #define PUBLIC_MECH_RANDOM_FLAG 0x08000000ul 35 #define PUBLIC_MECH_FRIENDLY_FLAG 0x10000000ul 36 #define PUBLIC_OWN_PW_DEFAULTS 0X20000000ul 37 #define PUBLIC_DISABLE_FLAG 0x40000000ul 38 39 /* warning: reserved means reserved */ 40 #define PUBLIC_MECH_RESERVED_FLAGS 0x87FF0000ul 41 42 /* These cipher flags are visible to all other libraries, */ 43 /* But they must be converted before used in functions */ 44 /* withing the security module */ 45 #define PUBLIC_CIPHER_FORTEZZA_FLAG 0x00000001ul 46 47 /* warning: reserved means reserved */ 48 #define PUBLIC_CIPHER_RESERVED_FLAGS 0xFFFFFFFEul 49 50 SEC_BEGIN_PROTOS 51 52 /* 53 * the following functions are going to be deprecated in NSS 4.0 in 54 * favor of the new stan functions. 55 */ 56 57 /* Initialization */ 58 extern SECMODModule *SECMOD_LoadModule(char *moduleSpec, SECMODModule *parent, 59 PRBool recurse); 60 61 extern SECMODModule *SECMOD_LoadUserModule(char *moduleSpec, SECMODModule *parent, 62 PRBool recurse); 63 64 extern SECMODModule *SECMOD_LoadUserModuleWithFunction(const char *moduleName, 65 CK_C_GetFunctionList fentry); 66 67 SECStatus SECMOD_UnloadUserModule(SECMODModule *mod); 68 69 SECMODModule *SECMOD_CreateModule(const char *lib, const char *name, 70 const char *param, const char *nss); 71 SECMODModule *SECMOD_CreateModuleEx(const char *lib, const char *name, 72 const char *param, const char *nss, 73 const char *config); 74 /* 75 * After a fork(), PKCS #11 says we need to call C_Initialize again in 76 * the child before we can use the module. This function causes this 77 * reinitialization. 78 * NOTE: Any outstanding handles will become invalid, which means your 79 * keys and contexts will fail, but new ones can be created. 80 * 81 * Setting 'force' to true means to do the reinitialization even if the 82 * PKCS #11 module does not seem to need it. This allows software modules 83 * which ignore fork to preserve their keys across the fork(). 84 */ 85 SECStatus SECMOD_RestartModules(PRBool force); 86 87 /* Module Management */ 88 char **SECMOD_GetModuleSpecList(SECMODModule *module); 89 SECStatus SECMOD_FreeModuleSpecList(SECMODModule *module, char **moduleSpecList); 90 91 /* protoypes */ 92 /* Get a list of active PKCS #11 modules */ 93 extern SECMODModuleList *SECMOD_GetDefaultModuleList(void); 94 /* Get a list of defined but not loaded PKCS #11 modules */ 95 extern SECMODModuleList *SECMOD_GetDeadModuleList(void); 96 /* Get a list of Modules which define PKCS #11 modules to load */ 97 extern SECMODModuleList *SECMOD_GetDBModuleList(void); 98 99 /* lock to protect all three module lists above */ 100 extern SECMODListLock *SECMOD_GetDefaultModuleListLock(void); 101 102 extern SECStatus SECMOD_UpdateModule(SECMODModule *module); 103 104 /* lock management */ 105 extern void SECMOD_GetReadLock(SECMODListLock *); 106 extern void SECMOD_ReleaseReadLock(SECMODListLock *); 107 108 /* Operate on modules by name */ 109 extern SECMODModule *SECMOD_FindModule(const char *name); 110 extern SECStatus SECMOD_DeleteModule(const char *name, int *type); 111 extern SECStatus SECMOD_DeleteModuleEx(const char *name, 112 SECMODModule *mod, 113 int *type, 114 PRBool permdb); 115 extern SECStatus SECMOD_DeleteInternalModule(const char *name); 116 extern PRBool SECMOD_CanDeleteInternalModule(void); 117 extern SECStatus SECMOD_AddNewModule(const char *moduleName, 118 const char *dllPath, 119 unsigned long defaultMechanismFlags, 120 unsigned long cipherEnableFlags); 121 extern SECStatus SECMOD_AddNewModuleEx(const char *moduleName, 122 const char *dllPath, 123 unsigned long defaultMechanismFlags, 124 unsigned long cipherEnableFlags, 125 char *modparms, 126 char *nssparms); 127 128 /* database/memory management */ 129 extern SECMODModule *SECMOD_GetInternalModule(void); 130 extern SECMODModule *SECMOD_ReferenceModule(SECMODModule *module); 131 extern void SECMOD_DestroyModule(SECMODModule *module); 132 extern PK11SlotInfo *SECMOD_LookupSlot(SECMODModuleID module, 133 unsigned long slotID); 134 extern PK11SlotInfo *SECMOD_FindSlot(SECMODModule *module, const char *name); 135 136 /* Funtion reports true if at least one of the modules */ 137 /* of modType has been installed */ 138 PRBool SECMOD_IsModulePresent(unsigned long int pubCipherEnableFlags); 139 140 /* accessors */ 141 PRBool SECMOD_GetSkipFirstFlag(SECMODModule *mod); 142 PRBool SECMOD_GetDefaultModDBFlag(SECMODModule *mod); 143 144 /* Functions used to convert between internal & public representation 145 * of Mechanism Flags and Cipher Enable Flags */ 146 extern unsigned long SECMOD_PubMechFlagstoInternal(unsigned long publicFlags); 147 extern unsigned long SECMOD_InternaltoPubMechFlags(unsigned long internalFlags); 148 extern unsigned long SECMOD_PubCipherFlagstoInternal(unsigned long publicFlags); 149 150 /* 151 * Check to see if the module has removable slots that we may need to 152 * watch for. 153 * 154 * NB: This function acquires the module list lock in order to access 155 * mod->slotCount and mod->slots. Deadlock can occur if the caller holds the 156 * module list lock. Callers that already hold the module list lock must use 157 * SECMOD_LockedModuleHasRemovableSlots instead. 158 */ 159 PRBool SECMOD_HasRemovableSlots(SECMODModule *mod); 160 161 /* 162 * Like SECMOD_HasRemovableSlots but this function does not acquire the module 163 * list lock. 164 */ 165 PRBool SECMOD_LockedModuleHasRemovableSlots(SECMODModule *mod); 166 167 /* 168 * this function waits for a token event on any slot of a given module 169 * This function should not be called from more than one thread of the 170 * same process (though other threads can make other library calls 171 * on this module while this call is blocked). 172 * 173 * Caller must not hold a module list read lock. 174 */ 175 PK11SlotInfo *SECMOD_WaitForAnyTokenEvent(SECMODModule *mod, 176 unsigned long flags, PRIntervalTime latency); 177 /* 178 * Warning: the SECMOD_CancelWait function is highly destructive, potentially 179 * finalizing the module 'mod' (causing inprogress operations to fail, 180 * and session key material to disappear). It should only be called when 181 * shutting down the module. 182 */ 183 SECStatus SECMOD_CancelWait(SECMODModule *mod); 184 185 /* 186 * check to see if the module has added new slots. PKCS 11 v2.20 allows for 187 * modules to add new slots, but never remove them. Slots not be added between 188 * a call to C_GetSlotLlist(Flag, NULL, &count) and the corresponding 189 * C_GetSlotList(flag, &data, &count) so that the array doesn't accidently 190 * grow on the caller. It is permissible for the slots to increase between 191 * corresponding calls with NULL to get the size. 192 * 193 * Caller must not hold a module list read lock. 194 */ 195 SECStatus SECMOD_UpdateSlotList(SECMODModule *mod); 196 197 /* 198 * Utilities to expose policy strings to applications: 199 * 200 * Policy strings are used by system configuration to specify what algorithms 201 * are included by policy. Each algorithm as a bitmask of operations allowed 202 * for that policy (Sign, SSL_KX, etc). Algorithm policies are tied to a oid, 203 * usually the primary oid used for that algorithm in X.509. 204 * In addition to policy oids, NSS has options, which are selected by a 205 * PRUint32. Options return an integer value, usually a limit (max key size, 206 * min key size, etc). 207 */ 208 /* Fetch the oid for a particular policy based on the string used to configure 209 * that policy. Policy are organized into logical list (ECC, HASH, MAC, 210 * CIPHER, SSL-KX, etc.). The search is restricted to a partular list unless 211 * ANY is specified). policy and list are case insensitive */ 212 SECOidTag SECMOD_PolicyStringToOid(const char *policy, const char *list); 213 /* fetch the Option integer based on the option string */ 214 PRUint32 SECMOD_PolicyStringToOpt(const char *optionString); 215 /* fetch a string descript of a particular bit value. The first match that has 216 * any of the requested bits is returns unless exact is specified, in which 217 * case the string must map to all existing bits. If no match is found, NULL 218 * is returned */ 219 const char *SECMOD_FlagsToPolicyString(PRUint32 val, PRBool exact); 220 221 SEC_END_PROTOS 222 223 #endif