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
10/* These mechanisms flags are visible to all other libraries. */
11/* They must be converted to internal SECMOD_*_FLAG */
12/* if used inside the functions of the security library */
13#define PUBLIC_MECH_RSA_FLAG 0x00000001ul
14#define PUBLIC_MECH_DSA_FLAG 0x00000002ul
15#define PUBLIC_MECH_RC2_FLAG 0x00000004ul
16#define PUBLIC_MECH_RC4_FLAG 0x00000008ul
17#define PUBLIC_MECH_DES_FLAG 0x00000010ul
18#define PUBLIC_MECH_DH_FLAG 0x00000020ul
19#define PUBLIC_MECH_FORTEZZA_FLAG 0x00000040ul
20#define PUBLIC_MECH_RC5_FLAG 0x00000080ul
21#define PUBLIC_MECH_SHA1_FLAG 0x00000100ul
22#define PUBLIC_MECH_MD5_FLAG 0x00000200ul
23#define PUBLIC_MECH_MD2_FLAG 0x00000400ul
24#define PUBLIC_MECH_SSL_FLAG 0x00000800ul
25#define PUBLIC_MECH_TLS_FLAG 0x00001000ul
26#define PUBLIC_MECH_AES_FLAG 0x00002000ul
27#define PUBLIC_MECH_SHA256_FLAG 0x00004000ul
28#define PUBLIC_MECH_SHA512_FLAG 0x00008000ul
29#define PUBLIC_MECH_CAMELLIA_FLAG 0x00010000ul
30#define PUBLIC_MECH_SEED_FLAG 0x00020000ul
31#define PUBLIC_MECH_ECC_FLAG 0x00040000ul
32
33#define PUBLIC_MECH_RANDOM_FLAG 0x08000000ul
34#define PUBLIC_MECH_FRIENDLY_FLAG 0x10000000ul
35#define PUBLIC_OWN_PW_DEFAULTS 0X20000000ul
36#define PUBLIC_DISABLE_FLAG 0x40000000ul
37
38/* warning: reserved means reserved */
39#define PUBLIC_MECH_RESERVED_FLAGS 0x87FF0000ul
40
41/* These cipher flags are visible to all other libraries, */
42/* But they must be converted before used in functions */
43/* withing the security module */
44#define PUBLIC_CIPHER_FORTEZZA_FLAG 0x00000001ul
45
46/* warning: reserved means reserved */
47#define PUBLIC_CIPHER_RESERVED_FLAGS 0xFFFFFFFEul
48
49SEC_BEGIN_PROTOS
50
51/*
52 * the following functions are going to be deprecated in NSS 4.0 in
53 * favor of the new stan functions.
54 */
55
56/* Initialization */
57extern SECMODModule *SECMOD_LoadModule(char *moduleSpec, SECMODModule *parent,
58 PRBool recurse);
59
60extern SECMODModule *SECMOD_LoadUserModule(char *moduleSpec, SECMODModule *parent,
61 PRBool recurse);
62
63SECStatus SECMOD_UnloadUserModule(SECMODModule *mod);
64
65SECMODModule *SECMOD_CreateModule(const char *lib, const char *name,
66 const char *param, const char *nss);
67SECMODModule *SECMOD_CreateModuleEx(const char *lib, const char *name,
68 const char *param, const char *nss,
69 const char *config);
70/*
71 * After a fork(), PKCS #11 says we need to call C_Initialize again in
72 * the child before we can use the module. This function causes this
73 * reinitialization.
74 * NOTE: Any outstanding handles will become invalid, which means your
75 * keys and contexts will fail, but new ones can be created.
76 *
77 * Setting 'force' to true means to do the reinitialization even if the
78 * PKCS #11 module does not seem to need it. This allows software modules
79 * which ignore fork to preserve their keys across the fork().
80 */
81SECStatus SECMOD_RestartModules(PRBool force);
82
83/* Module Management */
84char **SECMOD_GetModuleSpecList(SECMODModule *module);
85SECStatus SECMOD_FreeModuleSpecList(SECMODModule *module, char **moduleSpecList);
86
87/* protoypes */
88/* Get a list of active PKCS #11 modules */
89extern SECMODModuleList *SECMOD_GetDefaultModuleList(void);
90/* Get a list of defined but not loaded PKCS #11 modules */
91extern SECMODModuleList *SECMOD_GetDeadModuleList(void);
92/* Get a list of Modules which define PKCS #11 modules to load */
93extern SECMODModuleList *SECMOD_GetDBModuleList(void);
94
95/* lock to protect all three module lists above */
96extern SECMODListLock *SECMOD_GetDefaultModuleListLock(void);
97
98extern SECStatus SECMOD_UpdateModule(SECMODModule *module);
99
100/* lock management */
101extern void SECMOD_GetReadLock(SECMODListLock *);
102extern void SECMOD_ReleaseReadLock(SECMODListLock *);
103
104/* Operate on modules by name */
105extern SECMODModule *SECMOD_FindModule(const char *name);
106extern SECStatus SECMOD_DeleteModule(const char *name, int *type);
107extern SECStatus SECMOD_DeleteModuleEx(const char *name,
108 SECMODModule *mod,
109 int *type,
110 PRBool permdb);
111extern SECStatus SECMOD_DeleteInternalModule(const char *name);
112extern PRBool SECMOD_CanDeleteInternalModule(void);
113extern SECStatus SECMOD_AddNewModule(const char *moduleName,
114 const char *dllPath,
115 unsigned long defaultMechanismFlags,
116 unsigned long cipherEnableFlags);
117extern SECStatus SECMOD_AddNewModuleEx(const char *moduleName,
118 const char *dllPath,
119 unsigned long defaultMechanismFlags,
120 unsigned long cipherEnableFlags,
121 char *modparms,
122 char *nssparms);
123
124/* database/memory management */
125extern SECMODModule *SECMOD_GetInternalModule(void);
126extern SECMODModule *SECMOD_ReferenceModule(SECMODModule *module);
127extern void SECMOD_DestroyModule(SECMODModule *module);
128extern PK11SlotInfo *SECMOD_LookupSlot(SECMODModuleID module,
129 unsigned long slotID);
130extern PK11SlotInfo *SECMOD_FindSlot(SECMODModule *module, const char *name);
131
132/* Funtion reports true if at least one of the modules */
133/* of modType has been installed */
134PRBool SECMOD_IsModulePresent(unsigned long int pubCipherEnableFlags);
135
136/* accessors */
137PRBool SECMOD_GetSkipFirstFlag(SECMODModule *mod);
138PRBool SECMOD_GetDefaultModDBFlag(SECMODModule *mod);
139
140/* Functions used to convert between internal & public representation
141 * of Mechanism Flags and Cipher Enable Flags */
142extern unsigned long SECMOD_PubMechFlagstoInternal(unsigned long publicFlags);
143extern unsigned long SECMOD_InternaltoPubMechFlags(unsigned long internalFlags);
144extern unsigned long SECMOD_PubCipherFlagstoInternal(unsigned long publicFlags);
145
146/*
147 * Check to see if the module has removable slots that we may need to
148 * watch for.
149 *
150 * NB: This function acquires the module list lock in order to access
151 * mod->slotCount and mod->slots. Deadlock can occur if the caller holds the
152 * module list lock. Callers that already hold the module list lock must use
153 * SECMOD_LockedModuleHasRemovableSlots instead.
154 */
155PRBool SECMOD_HasRemovableSlots(SECMODModule *mod);
156
157/*
158 * Like SECMOD_HasRemovableSlots but this function does not acquire the module
159 * list lock.
160 */
161PRBool SECMOD_LockedModuleHasRemovableSlots(SECMODModule *mod);
162
163/*
164 * this function waits for a token event on any slot of a given module
165 * This function should not be called from more than one thread of the
166 * same process (though other threads can make other library calls
167 * on this module while this call is blocked).
168 *
169 * Caller must not hold a module list read lock.
170 */
171PK11SlotInfo *SECMOD_WaitForAnyTokenEvent(SECMODModule *mod,
172 unsigned long flags, PRIntervalTime latency);
173/*
174 * Warning: the SECMOD_CancelWait function is highly destructive, potentially
175 * finalizing the module 'mod' (causing inprogress operations to fail,
176 * and session key material to disappear). It should only be called when
177 * shutting down the module.
178 */
179SECStatus SECMOD_CancelWait(SECMODModule *mod);
180
181/*
182 * check to see if the module has added new slots. PKCS 11 v2.20 allows for
183 * modules to add new slots, but never remove them. Slots not be added between
184 * a call to C_GetSlotLlist(Flag, NULL, &count) and the corresponding
185 * C_GetSlotList(flag, &data, &count) so that the array doesn't accidently
186 * grow on the caller. It is permissible for the slots to increase between
187 * corresponding calls with NULL to get the size.
188 *
189 * Caller must not hold a module list read lock.
190 */
191SECStatus SECMOD_UpdateSlotList(SECMODModule *mod);
192SEC_END_PROTOS
193
194#endif
195

source code of include/nss/secmod.h