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 _PK11PUB_H_
5#define _PK11PUB_H_
6#include "plarena.h"
7#include "seccomon.h"
8#include "secoidt.h"
9#include "secdert.h"
10#include "keythi.h"
11#include "certt.h"
12#include "pk11hpke.h"
13#include "pkcs11t.h"
14#include "secmodt.h"
15#include "seccomon.h"
16#include "pkcs7t.h"
17#include "cmsreclist.h"
18
19/*
20 * Exported PK11 wrap functions.
21 */
22
23SEC_BEGIN_PROTOS
24
25/************************************************************
26 * Generic Slot Lists Management
27 ************************************************************/
28void PK11_FreeSlotList(PK11SlotList *list);
29SECStatus PK11_FreeSlotListElement(PK11SlotList *list, PK11SlotListElement *le);
30PK11SlotListElement *PK11_GetFirstSafe(PK11SlotList *list);
31PK11SlotListElement *PK11_GetNextSafe(PK11SlotList *list,
32 PK11SlotListElement *le, PRBool restart);
33
34/************************************************************
35 * Generic Slot Management
36 ************************************************************/
37PK11SlotInfo *PK11_ReferenceSlot(PK11SlotInfo *slot);
38void PK11_FreeSlot(PK11SlotInfo *slot);
39SECStatus PK11_DestroyObject(PK11SlotInfo *slot, CK_OBJECT_HANDLE object);
40SECStatus PK11_DestroyTokenObject(PK11SlotInfo *slot, CK_OBJECT_HANDLE object);
41PK11SlotInfo *PK11_GetInternalKeySlot(void);
42PK11SlotInfo *PK11_GetInternalSlot(void);
43SECStatus PK11_Logout(PK11SlotInfo *slot);
44void PK11_LogoutAll(void);
45
46/************************************************************
47 * Slot Password Management
48 ************************************************************/
49void PK11_SetSlotPWValues(PK11SlotInfo *slot, int askpw, int timeout);
50void PK11_GetSlotPWValues(PK11SlotInfo *slot, int *askpw, int *timeout);
51SECStatus PK11_CheckSSOPassword(PK11SlotInfo *slot, char *ssopw);
52SECStatus PK11_CheckUserPassword(PK11SlotInfo *slot, const char *pw);
53PRBool PK11_IsLoggedIn(PK11SlotInfo *slot, void *wincx);
54SECStatus PK11_InitPin(PK11SlotInfo *slot, const char *ssopw,
55 const char *pk11_userpwd);
56SECStatus PK11_ChangePW(PK11SlotInfo *slot, const char *oldpw,
57 const char *newpw);
58void PK11_SetPasswordFunc(PK11PasswordFunc func);
59int PK11_GetMinimumPwdLength(PK11SlotInfo *slot);
60SECStatus PK11_ResetToken(PK11SlotInfo *slot, char *sso_pwd);
61SECStatus PK11_Authenticate(PK11SlotInfo *slot, PRBool loadCerts, void *wincx);
62SECStatus PK11_TokenRefresh(PK11SlotInfo *slot);
63
64/******************************************************************
65 * Slot info functions
66 ******************************************************************/
67PK11SlotInfo *PK11_FindSlotByName(const char *name);
68/******************************************************************
69 * PK11_FindSlotsByNames searches for a PK11SlotInfo using one or
70 * more criteria : dllName, slotName and tokenName . In addition, if
71 * presentOnly is set , only slots with a token inserted will be
72 * returned.
73 ******************************************************************/
74PK11SlotList *PK11_FindSlotsByNames(const char *dllName,
75 const char *slotName, const char *tokenName, PRBool presentOnly);
76PRBool PK11_IsReadOnly(PK11SlotInfo *slot);
77PRBool PK11_IsInternal(PK11SlotInfo *slot);
78PRBool PK11_IsInternalKeySlot(PK11SlotInfo *slot);
79char *PK11_GetTokenName(PK11SlotInfo *slot);
80char *PK11_GetTokenURI(PK11SlotInfo *slot);
81char *PK11_GetSlotName(PK11SlotInfo *slot);
82PRBool PK11_NeedLogin(PK11SlotInfo *slot);
83PRBool PK11_IsFriendly(PK11SlotInfo *slot);
84PRBool PK11_IsHW(PK11SlotInfo *slot);
85PRBool PK11_IsRemovable(PK11SlotInfo *slot);
86PRBool PK11_NeedUserInit(PK11SlotInfo *slot);
87PRBool PK11_ProtectedAuthenticationPath(PK11SlotInfo *slot);
88int PK11_GetSlotSeries(PK11SlotInfo *slot);
89int PK11_GetCurrentWrapIndex(PK11SlotInfo *slot);
90unsigned long PK11_GetDefaultFlags(PK11SlotInfo *slot);
91CK_SLOT_ID PK11_GetSlotID(PK11SlotInfo *slot);
92SECMODModuleID PK11_GetModuleID(PK11SlotInfo *slot);
93SECStatus PK11_GetSlotInfo(PK11SlotInfo *slot, CK_SLOT_INFO *info);
94SECStatus PK11_GetTokenInfo(PK11SlotInfo *slot, CK_TOKEN_INFO *info);
95PRBool PK11_IsDisabled(PK11SlotInfo *slot);
96PRBool PK11_HasRootCerts(PK11SlotInfo *slot);
97PK11DisableReasons PK11_GetDisabledReason(PK11SlotInfo *slot);
98/* Prevents the slot from being used, and set disable reason to user-disable */
99/* NOTE: Mechanisms that were ON continue to stay ON */
100/* Therefore, when the slot is enabled, it will remember */
101/* what mechanisms needs to be turned on */
102PRBool PK11_UserDisableSlot(PK11SlotInfo *slot);
103/* Allow all mechanisms that are ON before UserDisableSlot() */
104/* was called to be available again */
105PRBool PK11_UserEnableSlot(PK11SlotInfo *slot);
106/*
107 * wait for a specific slot event.
108 * event is a specific event to wait for. Currently only
109 * PK11TokenChangeOrRemovalEvent and PK11TokenPresentEvents are defined.
110 * timeout can be an interval time to wait, PR_INTERVAL_NO_WAIT (meaning only
111 * poll once), or PR_INTERVAL_NO_TIMEOUT (meaning block until a change).
112 * pollInterval is a suggested pulling interval value. '0' means use the
113 * default. Future implementations that don't poll may ignore this value.
114 * series is the current series for the last slot. This should be the series
115 * value for the slot the last time you read persistant information from the
116 * slot. For instance, if you publish a cert from the slot, you should obtain
117 * the slot series at that time. Then PK11_WaitForTokenEvent can detect a
118 * a change in the slot between the time you publish and the time
119 * PK11_WaitForTokenEvent is called, elliminating potential race conditions.
120 *
121 * The current status that is returned is:
122 * PK11TokenNotRemovable - always returned for any non-removable token.
123 * PK11TokenPresent - returned when the token is present and we are waiting
124 * on a PK11TokenPresentEvent. Then next event to look for is a
125 * PK11TokenChangeOrRemovalEvent.
126 * PK11TokenChanged - returned when the old token has been removed and a new
127 * token ad been inserted, and we are waiting for a
128 * PK11TokenChangeOrRemovalEvent. The next event to look for is another
129 * PK11TokenChangeOrRemovalEvent.
130 * PK11TokenRemoved - returned when the token is not present and we are
131 * waiting for a PK11TokenChangeOrRemovalEvent. The next event to look for
132 * is a PK11TokenPresentEvent.
133 */
134PK11TokenStatus PK11_WaitForTokenEvent(PK11SlotInfo *slot, PK11TokenEvent event,
135 PRIntervalTime timeout, PRIntervalTime pollInterval, int series);
136
137PRBool PK11_NeedPWInit(void);
138PRBool PK11_TokenExists(CK_MECHANISM_TYPE);
139SECStatus PK11_GetModInfo(SECMODModule *mod, CK_INFO *info);
140char *PK11_GetModuleURI(SECMODModule *mod);
141PRBool PK11_IsFIPS(void);
142SECMODModule *PK11_GetModule(PK11SlotInfo *slot);
143
144/*********************************************************************
145 * Slot mapping utility functions.
146 *********************************************************************/
147PRBool PK11_IsPresent(PK11SlotInfo *slot);
148PRBool PK11_DoesMechanism(PK11SlotInfo *slot, CK_MECHANISM_TYPE type);
149PK11SlotList *PK11_GetAllTokens(CK_MECHANISM_TYPE type, PRBool needRW,
150 PRBool loadCerts, void *wincx);
151PK11SlotInfo *PK11_GetBestSlotMultipleWithAttributes(CK_MECHANISM_TYPE *type,
152 CK_FLAGS *mechFlag, unsigned int *keySize,
153 unsigned int count, void *wincx);
154PK11SlotInfo *PK11_GetBestSlotMultiple(CK_MECHANISM_TYPE *type,
155 unsigned int count, void *wincx);
156PK11SlotInfo *PK11_GetBestSlot(CK_MECHANISM_TYPE type, void *wincx);
157PK11SlotInfo *PK11_GetBestSlotWithAttributes(CK_MECHANISM_TYPE type,
158 CK_FLAGS mechFlag, unsigned int keySize, void *wincx);
159CK_MECHANISM_TYPE PK11_GetBestWrapMechanism(PK11SlotInfo *slot);
160int PK11_GetBestKeyLength(PK11SlotInfo *slot, CK_MECHANISM_TYPE type);
161
162/*
163 * Open a new database using the softoken. The caller is responsible for making
164 * sure the module spec is correct and usable. The caller should ask for one
165 * new database per call if the caller wants to get meaningful information
166 * about the new database.
167 *
168 * moduleSpec is the same data that you would pass to softoken at
169 * initialization time under the 'tokens' options. For example, if you were
170 * to specify tokens=<0x4=[configdir='./mybackup' tokenDescription='Backup']>
171 * You would specify "configdir='./mybackup' tokenDescription='Backup'" as your
172 * module spec here. The slot ID will be calculated for you by
173 * SECMOD_OpenUserDB().
174 *
175 * Typical parameters here are configdir, tokenDescription and flags.
176 *
177 * a Full list is below:
178 *
179 *
180 * configDir - The location of the databases for this token. If configDir is
181 * not specified, and noCertDB and noKeyDB is not specified, the load
182 * will fail.
183 * certPrefix - Cert prefix for this token.
184 * keyPrefix - Prefix for the key database for this token. (if not specified,
185 * certPrefix will be used).
186 * tokenDescription - The label value for this token returned in the
187 * CK_TOKEN_INFO structure with an internationalize string (UTF8).
188 * This value will be truncated at 32 bytes (no NULL, partial UTF8
189 * characters dropped). You should specify a user friendly name here
190 * as this is the value the token will be referred to in most
191 * application UI's. You should make sure tokenDescription is unique.
192 * slotDescription - The slotDescription value for this token returned
193 * in the CK_SLOT_INFO structure with an internationalize string
194 * (UTF8). This value will be truncated at 64 bytes (no NULL, partial
195 * UTF8 characters dropped). This name will not change after the
196 * database is closed. It should have some number to make this unique.
197 * minPWLen - minimum password length for this token.
198 * flags - comma separated list of flag values, parsed case-insensitive.
199 * Valid flags are:
200 * readOnly - Databases should be opened read only.
201 * noCertDB - Don't try to open a certificate database.
202 * noKeyDB - Don't try to open a key database.
203 * forceOpen - Don't fail to initialize the token if the
204 * databases could not be opened.
205 * passwordRequired - zero length passwords are not acceptable
206 * (valid only if there is a keyDB).
207 * optimizeSpace - allocate smaller hash tables and lock tables.
208 * When this flag is not specified, Softoken will allocate
209 * large tables to prevent lock contention.
210 */
211PK11SlotInfo *SECMOD_OpenUserDB(const char *moduleSpec);
212SECStatus SECMOD_CloseUserDB(PK11SlotInfo *slot);
213
214/*
215 * This is exactly the same as OpenUserDB except it can be called on any
216 * module that understands softoken style new slot entries. The resulting
217 * slot can be closed using SECMOD_CloseUserDB above. Value of moduleSpec
218 * is token specific.
219 */
220PK11SlotInfo *SECMOD_OpenNewSlot(SECMODModule *mod, const char *moduleSpec);
221
222/*
223 * merge the permanent objects from on token to another
224 */
225SECStatus PK11_MergeTokens(PK11SlotInfo *targetSlot, PK11SlotInfo *sourceSlot,
226 PK11MergeLog *log, void *targetPwArg, void *sourcePwArg);
227
228/*
229 * create and destroy merge logs needed by PK11_MergeTokens
230 */
231PK11MergeLog *PK11_CreateMergeLog(void);
232void PK11_DestroyMergeLog(PK11MergeLog *log);
233
234/*********************************************************************
235 * Mechanism Mapping functions
236 *********************************************************************/
237CK_KEY_TYPE PK11_GetKeyType(CK_MECHANISM_TYPE type, unsigned long len);
238CK_MECHANISM_TYPE PK11_GetKeyGen(CK_MECHANISM_TYPE type);
239int PK11_GetBlockSize(CK_MECHANISM_TYPE type, SECItem *params);
240int PK11_GetIVLength(CK_MECHANISM_TYPE type);
241SECItem *PK11_ParamFromIV(CK_MECHANISM_TYPE type, SECItem *iv);
242unsigned char *PK11_IVFromParam(CK_MECHANISM_TYPE type, SECItem *param, int *len);
243SECItem *PK11_BlockData(SECItem *data, unsigned long size);
244
245/* PKCS #11 to DER mapping functions */
246SECItem *PK11_ParamFromAlgid(SECAlgorithmID *algid);
247SECItem *PK11_GenerateNewParam(CK_MECHANISM_TYPE, PK11SymKey *);
248CK_MECHANISM_TYPE PK11_AlgtagToMechanism(SECOidTag algTag);
249SECOidTag PK11_MechanismToAlgtag(CK_MECHANISM_TYPE type);
250SECOidTag PK11_FortezzaMapSig(SECOidTag algTag);
251SECStatus PK11_ParamToAlgid(SECOidTag algtag, SECItem *param,
252 PLArenaPool *arena, SECAlgorithmID *algid);
253SECStatus PK11_SeedRandom(PK11SlotInfo *, unsigned char *data, int len);
254SECStatus PK11_GenerateRandomOnSlot(PK11SlotInfo *, unsigned char *data, int len);
255SECStatus PK11_RandomUpdate(void *data, size_t bytes);
256SECStatus PK11_GenerateRandom(unsigned char *data, int len);
257
258/* warning: cannot work with pkcs 5 v2
259 * use algorithm ID s instead of pkcs #11 mechanism pointers */
260CK_RV PK11_MapPBEMechanismToCryptoMechanism(CK_MECHANISM_PTR pPBEMechanism,
261 CK_MECHANISM_PTR pCryptoMechanism,
262 SECItem *pbe_pwd, PRBool bad3DES);
263CK_MECHANISM_TYPE PK11_GetPadMechanism(CK_MECHANISM_TYPE);
264CK_MECHANISM_TYPE PK11_MapSignKeyType(KeyType keyType);
265
266/**********************************************************************
267 * Symmetric, Public, and Private Keys
268 **********************************************************************/
269void PK11_FreeSymKey(PK11SymKey *key);
270PK11SymKey *PK11_ReferenceSymKey(PK11SymKey *symKey);
271PK11SymKey *PK11_ImportDataKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE type, PK11Origin origin,
272 CK_ATTRIBUTE_TYPE operation, SECItem *key, void *wincx);
273PK11SymKey *PK11_ImportSymKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE type,
274 PK11Origin origin, CK_ATTRIBUTE_TYPE operation, SECItem *key, void *wincx);
275PK11SymKey *PK11_ImportSymKeyWithFlags(PK11SlotInfo *slot,
276 CK_MECHANISM_TYPE type, PK11Origin origin, CK_ATTRIBUTE_TYPE operation,
277 SECItem *key, CK_FLAGS flags, PRBool isPerm, void *wincx);
278PK11SymKey *PK11_SymKeyFromHandle(PK11SlotInfo *slot, PK11SymKey *parent,
279 PK11Origin origin, CK_MECHANISM_TYPE type, CK_OBJECT_HANDLE keyID,
280 PRBool owner, void *wincx);
281/* PK11_GetWrapKey and PK11_SetWrapKey are not thread safe. */
282PK11SymKey *PK11_GetWrapKey(PK11SlotInfo *slot, int wrap,
283 CK_MECHANISM_TYPE type, int series, void *wincx);
284void PK11_SetWrapKey(PK11SlotInfo *slot, int wrap, PK11SymKey *wrapKey);
285CK_MECHANISM_TYPE PK11_GetMechanism(PK11SymKey *symKey);
286/*
287 * import a public key into the desired slot
288 *
289 * This function takes a public key structure and creates a public key in a
290 * given slot. If isToken is set, then a persistant public key is created.
291 *
292 * Note: it is possible for this function to return a handle for a key which
293 * is persistant, even if isToken is not set.
294 */
295CK_OBJECT_HANDLE PK11_ImportPublicKey(PK11SlotInfo *slot,
296 SECKEYPublicKey *pubKey, PRBool isToken);
297PK11SymKey *PK11_KeyGen(PK11SlotInfo *slot, CK_MECHANISM_TYPE type,
298 SECItem *param, int keySize, void *wincx);
299PK11SymKey *PK11_TokenKeyGen(PK11SlotInfo *slot, CK_MECHANISM_TYPE type,
300 SECItem *param, int keySize, SECItem *keyid,
301 PRBool isToken, void *wincx);
302PK11SymKey *PK11_TokenKeyGenWithFlags(PK11SlotInfo *slot,
303 CK_MECHANISM_TYPE type, SECItem *param,
304 int keySize, SECItem *keyid, CK_FLAGS opFlags,
305 PK11AttrFlags attrFlags, void *wincx);
306/* Generates a key using the exact template supplied by the caller. The other
307 * PK11_[Token]KeyGen mechanisms should be used instead of this one whenever
308 * they work because they include/exclude the CKA_VALUE_LEN template value
309 * based on the mechanism type as required by many tokens.
310 *
311 * keyGenType should be PK11_GetKeyGenWithSize(type, <key size>) or it should
312 * be equal to type if PK11_GetKeyGenWithSize cannot be used (e.g. because
313 * pk11wrap does not know about the mechanisms).
314 */
315PK11SymKey *PK11_KeyGenWithTemplate(PK11SlotInfo *slot, CK_MECHANISM_TYPE type,
316 CK_MECHANISM_TYPE keyGenType,
317 SECItem *param, CK_ATTRIBUTE *attrs,
318 unsigned int attrsCount, void *wincx);
319PK11SymKey *PK11_ListFixedKeysInSlot(PK11SlotInfo *slot, char *nickname,
320 void *wincx);
321PK11SymKey *PK11_GetNextSymKey(PK11SymKey *symKey);
322CK_KEY_TYPE PK11_GetSymKeyType(PK11SymKey *key);
323CK_OBJECT_HANDLE PK11_GetSymKeyHandle(PK11SymKey *symKey);
324
325/*
326 * PK11_SetSymKeyUserData
327 * sets generic user data on keys (usually a pointer to a data structure)
328 * that can later be retrieved by PK11_GetSymKeyUserData().
329 * symKey - key where data will be set.
330 * data - data to be set.
331 * freefunc - function used to free the data.
332 * Setting user data on symKeys with existing user data already set will cause
333 * the existing user data to be freed before the new user data is set.
334 * Freeing user data is done by calling the user specified freefunc.
335 * If freefunc is NULL, the user data is assumed to be global or static an
336 * not freed. Passing NULL for user data to PK11_SetSymKeyUserData has the
337 * effect of freeing any existing user data, and clearing the user data
338 * pointer. If user data exists when the symKey is finally freed, that
339 * data will be freed with freefunc.
340 *
341 * Applications should only use this function on keys which the application
342 * has created directly, as there is only one user data value per key.
343 */
344void PK11_SetSymKeyUserData(PK11SymKey *symKey, void *data,
345 PK11FreeDataFunc freefunc);
346/* PK11_GetSymKeyUserData
347 * retrieves generic user data which was set on a key by
348 * PK11_SetSymKeyUserData.
349 * symKey - key with data to be fetched
350 *
351 * If no data exists, or the data has been cleared, PK11_GetSymKeyUserData
352 * will return NULL. Returned data is still owned and managed by the SymKey,
353 * the caller should not free the data.
354 *
355 */
356void *PK11_GetSymKeyUserData(PK11SymKey *symKey);
357
358SECStatus PK11_PubWrapSymKey(CK_MECHANISM_TYPE type, SECKEYPublicKey *pubKey,
359 PK11SymKey *symKey, SECItem *wrappedKey);
360SECStatus PK11_PubWrapSymKeyWithMechanism(SECKEYPublicKey *pubKey,
361 CK_MECHANISM_TYPE mechType,
362 SECItem *param,
363 PK11SymKey *symKey,
364 SECItem *wrappedKey);
365SECStatus PK11_WrapSymKey(CK_MECHANISM_TYPE type, SECItem *params,
366 PK11SymKey *wrappingKey, PK11SymKey *symKey, SECItem *wrappedKey);
367/* move a key to 'slot' optionally set the key attributes according to either
368 * operation or the flags and making the key permanent at the same time.
369 * If the key is moved to the same slot, operation and flags values are
370 * currently ignored */
371PK11SymKey *PK11_MoveSymKey(PK11SlotInfo *slot, CK_ATTRIBUTE_TYPE operation,
372 CK_FLAGS flags, PRBool perm, PK11SymKey *symKey);
373/*
374 * To do joint operations, we often need two keys in the same slot.
375 * Usually the PKCS #11 wrappers handle this correctly (like for PK11_WrapKey),
376 * but sometimes the wrappers don't know about mechanism specific keys in
377 * the Mechanism params. This function makes sure the two keys are in the
378 * same slot by copying one or both of the keys into a common slot. This
379 * functions makes sure the slot can handle the target mechanism. If the copy
380 * is warranted, this function will prefer to move the movingKey first, then
381 * the preferedKey. If the keys are moved, the new keys are returned in
382 * newMovingKey and/or newPreferedKey. The application is responsible
383 * for freeing those keys one the operation is complete.
384 */
385SECStatus PK11_SymKeysToSameSlot(CK_MECHANISM_TYPE mech,
386 CK_ATTRIBUTE_TYPE preferedOperation,
387 CK_ATTRIBUTE_TYPE movingOperation,
388 PK11SymKey *preferedKey, PK11SymKey *movingKey,
389 PK11SymKey **newPreferedKey,
390 PK11SymKey **newMovingKey);
391
392/*
393 * derive a new key from the base key.
394 * PK11_Derive returns a key which can do exactly one operation, and is
395 * ephemeral (session key).
396 * PK11_DeriveWithFlags is the same as PK11_Derive, except you can use
397 * CKF_ flags to enable more than one operation.
398 * PK11_DeriveWithFlagsPerm is the same as PK11_DeriveWithFlags except you can
399 * (optionally) make the key permanent (token key).
400 */
401PK11SymKey *PK11_Derive(PK11SymKey *baseKey, CK_MECHANISM_TYPE mechanism,
402 SECItem *param, CK_MECHANISM_TYPE target,
403 CK_ATTRIBUTE_TYPE operation, int keySize);
404PK11SymKey *PK11_DeriveWithFlags(PK11SymKey *baseKey,
405 CK_MECHANISM_TYPE derive, SECItem *param, CK_MECHANISM_TYPE target,
406 CK_ATTRIBUTE_TYPE operation, int keySize, CK_FLAGS flags);
407PK11SymKey *PK11_DeriveWithFlagsPerm(PK11SymKey *baseKey,
408 CK_MECHANISM_TYPE derive,
409 SECItem *param, CK_MECHANISM_TYPE target, CK_ATTRIBUTE_TYPE operation,
410 int keySize, CK_FLAGS flags, PRBool isPerm);
411PK11SymKey *
412PK11_DeriveWithTemplate(PK11SymKey *baseKey, CK_MECHANISM_TYPE derive,
413 SECItem *param, CK_MECHANISM_TYPE target, CK_ATTRIBUTE_TYPE operation,
414 int keySize, CK_ATTRIBUTE *userAttr, unsigned int numAttrs,
415 PRBool isPerm);
416
417PK11SymKey *PK11_PubDerive(SECKEYPrivateKey *privKey,
418 SECKEYPublicKey *pubKey, PRBool isSender, SECItem *randomA, SECItem *randomB,
419 CK_MECHANISM_TYPE derive, CK_MECHANISM_TYPE target,
420 CK_ATTRIBUTE_TYPE operation, int keySize, void *wincx);
421PK11SymKey *PK11_PubDeriveWithKDF(SECKEYPrivateKey *privKey,
422 SECKEYPublicKey *pubKey, PRBool isSender, SECItem *randomA, SECItem *randomB,
423 CK_MECHANISM_TYPE derive, CK_MECHANISM_TYPE target,
424 CK_ATTRIBUTE_TYPE operation, int keySize,
425 CK_ULONG kdf, SECItem *sharedData, void *wincx);
426
427/*
428 * Concatenate a pair of symmetric keys.
429 */
430PK11SymKey *PK11_ConcatSymKeys(PK11SymKey *left, PK11SymKey *right, CK_MECHANISM_TYPE target, CK_ATTRIBUTE_TYPE operation);
431
432/*
433 * unwrap a new key with a symetric key.
434 * PK11_Unwrap returns a key which can do exactly one operation, and is
435 * ephemeral (session key).
436 * PK11_UnwrapWithFlags is the same as PK11_Unwrap, except you can use
437 * CKF_ flags to enable more than one operation.
438 * PK11_UnwrapWithFlagsPerm is the same as PK11_UnwrapWithFlags except you can
439 * (optionally) make the key permanent (token key).
440 */
441PK11SymKey *PK11_UnwrapSymKey(PK11SymKey *key,
442 CK_MECHANISM_TYPE wraptype, SECItem *param, SECItem *wrapppedKey,
443 CK_MECHANISM_TYPE target, CK_ATTRIBUTE_TYPE operation, int keySize);
444PK11SymKey *PK11_UnwrapSymKeyWithFlags(PK11SymKey *wrappingKey,
445 CK_MECHANISM_TYPE wrapType, SECItem *param, SECItem *wrappedKey,
446 CK_MECHANISM_TYPE target, CK_ATTRIBUTE_TYPE operation, int keySize,
447 CK_FLAGS flags);
448PK11SymKey *PK11_UnwrapSymKeyWithFlagsPerm(PK11SymKey *wrappingKey,
449 CK_MECHANISM_TYPE wrapType,
450 SECItem *param, SECItem *wrappedKey,
451 CK_MECHANISM_TYPE target, CK_ATTRIBUTE_TYPE operation,
452 int keySize, CK_FLAGS flags, PRBool isPerm);
453
454/*
455 * unwrap a new key with a private key.
456 * PK11_PubUnwrap returns a key which can do exactly one operation, and is
457 * ephemeral (session key).
458 * PK11_PubUnwrapWithFlagsPerm is the same as PK11_PubUnwrap except you can
459 * use * CKF_ flags to enable more than one operation, and optionally make
460 * the key permanent (token key).
461 */
462PK11SymKey *PK11_PubUnwrapSymKey(SECKEYPrivateKey *key, SECItem *wrapppedKey,
463 CK_MECHANISM_TYPE target, CK_ATTRIBUTE_TYPE operation, int keySize);
464PK11SymKey *PK11_PubUnwrapSymKeyWithMechanism(SECKEYPrivateKey *key,
465 CK_MECHANISM_TYPE mechType,
466 SECItem *param,
467 SECItem *wrapppedKey,
468 CK_MECHANISM_TYPE target,
469 CK_ATTRIBUTE_TYPE operation,
470 int keySize);
471PK11SymKey *PK11_PubUnwrapSymKeyWithFlagsPerm(SECKEYPrivateKey *wrappingKey,
472 SECItem *wrappedKey, CK_MECHANISM_TYPE target,
473 CK_ATTRIBUTE_TYPE operation, int keySize,
474 CK_FLAGS flags, PRBool isPerm);
475PK11SymKey *PK11_FindFixedKey(PK11SlotInfo *slot, CK_MECHANISM_TYPE type,
476 SECItem *keyID, void *wincx);
477SECStatus PK11_DeleteTokenPrivateKey(SECKEYPrivateKey *privKey, PRBool force);
478SECStatus PK11_DeleteTokenPublicKey(SECKEYPublicKey *pubKey);
479SECStatus PK11_DeleteTokenSymKey(PK11SymKey *symKey);
480SECStatus PK11_DeleteTokenCertAndKey(CERTCertificate *cert, void *wincx);
481SECKEYPrivateKey *PK11_LoadPrivKey(PK11SlotInfo *slot,
482 SECKEYPrivateKey *privKey, SECKEYPublicKey *pubKey,
483 PRBool token, PRBool sensitive);
484char *PK11_GetSymKeyNickname(PK11SymKey *symKey);
485char *PK11_GetPrivateKeyNickname(SECKEYPrivateKey *privKey);
486char *PK11_GetPublicKeyNickname(SECKEYPublicKey *pubKey);
487SECStatus PK11_SetSymKeyNickname(PK11SymKey *symKey, const char *nickname);
488SECStatus PK11_SetPrivateKeyNickname(SECKEYPrivateKey *privKey,
489 const char *nickname);
490SECStatus PK11_SetPublicKeyNickname(SECKEYPublicKey *pubKey,
491 const char *nickname);
492
493/*
494 * Using __PK11_SetCertificateNickname is *DANGEROUS*.
495 *
496 * The API will update the NSS database, but it *will NOT* update the in-memory data.
497 * As a result, after calling this API, there will be INCONSISTENCY between
498 * in-memory data and the database.
499 *
500 * Use of the API should be limited to short-lived tools, which will exit immediately
501 * after using this API.
502 *
503 * If you ignore this warning, your process is TAINTED and will most likely misbehave.
504 */
505SECStatus __PK11_SetCertificateNickname(CERTCertificate *cert,
506 const char *nickname);
507
508/* size to hold key in bytes */
509unsigned int PK11_GetKeyLength(PK11SymKey *key);
510/* size of actual secret parts of key in bits */
511/* algid is because RC4 strength is determined by the effective bits as well
512 * as the key bits */
513unsigned int PK11_GetKeyStrength(PK11SymKey *key, SECAlgorithmID *algid);
514SECStatus PK11_ExtractKeyValue(PK11SymKey *symKey);
515SECItem *PK11_GetKeyData(PK11SymKey *symKey);
516PK11SlotInfo *PK11_GetSlotFromKey(PK11SymKey *symKey);
517void *PK11_GetWindow(PK11SymKey *symKey);
518
519/*
520 * Explicitly set the key usage for the generated private key.
521 *
522 * This allows us to specify single use EC and RSA keys whose usage
523 * can be regulated by the underlying token.
524 *
525 * The underlying key usage is set using opFlags. opFlagsMask specifies
526 * which operations are specified by opFlags. For instance to turn encrypt
527 * on and signing off, opFlags would be CKF_ENCRYPT|CKF_DECRYPT and
528 * opFlagsMask would be CKF_ENCRYPT|CKF_DECRYPT|CKF_SIGN|CKF_VERIFY. You
529 * need to specify both the public and private key flags,
530 * PK11_GenerateKeyPairWithOpFlags will sort out the correct flag to the
531 * correct key type. Flags not specified in opFlagMask will be defaulted
532 * according to mechanism type and token capabilities.
533 */
534SECKEYPrivateKey *PK11_GenerateKeyPairWithOpFlags(PK11SlotInfo *slot,
535 CK_MECHANISM_TYPE type, void *param, SECKEYPublicKey **pubk,
536 PK11AttrFlags attrFlags, CK_FLAGS opFlags, CK_FLAGS opFlagsMask,
537 void *wincx);
538/*
539 * The attrFlags is the logical OR of the PK11_ATTR_XXX bitflags.
540 * These flags apply to the private key. The PK11_ATTR_TOKEN,
541 * PK11_ATTR_SESSION, PK11_ATTR_MODIFIABLE, and PK11_ATTR_UNMODIFIABLE
542 * flags also apply to the public key.
543 */
544SECKEYPrivateKey *PK11_GenerateKeyPairWithFlags(PK11SlotInfo *slot,
545 CK_MECHANISM_TYPE type, void *param, SECKEYPublicKey **pubk,
546 PK11AttrFlags attrFlags, void *wincx);
547SECKEYPrivateKey *PK11_GenerateKeyPair(PK11SlotInfo *slot,
548 CK_MECHANISM_TYPE type, void *param, SECKEYPublicKey **pubk,
549 PRBool isPerm, PRBool isSensitive, void *wincx);
550SECKEYPrivateKey *PK11_FindPrivateKeyFromCert(PK11SlotInfo *slot,
551 CERTCertificate *cert, void *wincx);
552SECKEYPrivateKey *PK11_FindKeyByAnyCert(CERTCertificate *cert, void *wincx);
553SECKEYPrivateKey *PK11_FindKeyByKeyID(PK11SlotInfo *slot, SECItem *keyID,
554 void *wincx);
555int PK11_GetPrivateModulusLen(SECKEYPrivateKey *key);
556
557SECStatus PK11_Decrypt(PK11SymKey *symkey,
558 CK_MECHANISM_TYPE mechanism, SECItem *param,
559 unsigned char *out, unsigned int *outLen,
560 unsigned int maxLen,
561 const unsigned char *enc, unsigned int encLen);
562SECStatus PK11_Encrypt(PK11SymKey *symKey,
563 CK_MECHANISM_TYPE mechanism, SECItem *param,
564 unsigned char *out, unsigned int *outLen,
565 unsigned int maxLen,
566 const unsigned char *data, unsigned int dataLen);
567
568/* note: despite the name, this function takes a private key. */
569SECStatus PK11_PubDecryptRaw(SECKEYPrivateKey *key,
570 unsigned char *data, unsigned *outLen,
571 unsigned int maxLen,
572 const unsigned char *enc, unsigned encLen);
573#define PK11_PrivDecryptRaw PK11_PubDecryptRaw
574/* The encrypt function that complements the above decrypt function. */
575SECStatus PK11_PubEncryptRaw(SECKEYPublicKey *key,
576 unsigned char *enc,
577 const unsigned char *data, unsigned dataLen,
578 void *wincx);
579
580SECStatus PK11_PrivDecryptPKCS1(SECKEYPrivateKey *key,
581 unsigned char *data, unsigned *outLen,
582 unsigned int maxLen,
583 const unsigned char *enc, unsigned encLen);
584/* The encrypt function that complements the above decrypt function. */
585SECStatus PK11_PubEncryptPKCS1(SECKEYPublicKey *key,
586 unsigned char *enc,
587 const unsigned char *data, unsigned dataLen,
588 void *wincx);
589
590SECStatus PK11_PrivDecrypt(SECKEYPrivateKey *key,
591 CK_MECHANISM_TYPE mechanism, SECItem *param,
592 unsigned char *out, unsigned int *outLen,
593 unsigned int maxLen,
594 const unsigned char *enc, unsigned int encLen);
595SECStatus PK11_PubEncrypt(SECKEYPublicKey *key,
596 CK_MECHANISM_TYPE mechanism, SECItem *param,
597 unsigned char *out, unsigned int *outLen,
598 unsigned int maxLen,
599 const unsigned char *data, unsigned int dataLen,
600 void *wincx);
601
602SECStatus PK11_ImportPrivateKeyInfo(PK11SlotInfo *slot,
603 SECKEYPrivateKeyInfo *pki, SECItem *nickname,
604 SECItem *publicValue, PRBool isPerm, PRBool isPrivate,
605 unsigned int usage, void *wincx);
606SECStatus PK11_ImportPrivateKeyInfoAndReturnKey(PK11SlotInfo *slot,
607 SECKEYPrivateKeyInfo *pki, SECItem *nickname,
608 SECItem *publicValue, PRBool isPerm, PRBool isPrivate,
609 unsigned int usage, SECKEYPrivateKey **privk, void *wincx);
610SECStatus PK11_ImportDERPrivateKeyInfo(PK11SlotInfo *slot,
611 SECItem *derPKI, SECItem *nickname,
612 SECItem *publicValue, PRBool isPerm, PRBool isPrivate,
613 unsigned int usage, void *wincx);
614SECStatus PK11_ImportDERPrivateKeyInfoAndReturnKey(PK11SlotInfo *slot,
615 SECItem *derPKI, SECItem *nickname,
616 SECItem *publicValue, PRBool isPerm, PRBool isPrivate,
617 unsigned int usage, SECKEYPrivateKey **privk, void *wincx);
618SECStatus PK11_ImportEncryptedPrivateKeyInfo(PK11SlotInfo *slot,
619 SECKEYEncryptedPrivateKeyInfo *epki, SECItem *pwitem,
620 SECItem *nickname, SECItem *publicValue, PRBool isPerm,
621 PRBool isPrivate, KeyType type,
622 unsigned int usage, void *wincx);
623SECStatus PK11_ImportEncryptedPrivateKeyInfoAndReturnKey(PK11SlotInfo *slot,
624 SECKEYEncryptedPrivateKeyInfo *epki, SECItem *pwitem,
625 SECItem *nickname, SECItem *publicValue, PRBool isPerm,
626 PRBool isPrivate, KeyType type,
627 unsigned int usage, SECKEYPrivateKey **privk, void *wincx);
628SECItem *PK11_ExportDERPrivateKeyInfo(SECKEYPrivateKey *pk, void *wincx);
629SECKEYPrivateKeyInfo *PK11_ExportPrivKeyInfo(
630 SECKEYPrivateKey *pk, void *wincx);
631SECKEYPrivateKeyInfo *PK11_ExportPrivateKeyInfo(
632 CERTCertificate *cert, void *wincx);
633SECKEYEncryptedPrivateKeyInfo *PK11_ExportEncryptedPrivKeyInfo(
634 PK11SlotInfo *slot, SECOidTag algTag, SECItem *pwitem,
635 SECKEYPrivateKey *pk, int iteration, void *pwArg);
636SECKEYEncryptedPrivateKeyInfo *PK11_ExportEncryptedPrivateKeyInfo(
637 PK11SlotInfo *slot, SECOidTag algTag, SECItem *pwitem,
638 CERTCertificate *cert, int iteration, void *pwArg);
639/* V2 refers to PKCS #5 V2 here. If a PKCS #5 v1 or PKCS #12 pbe is passed
640 * for pbeTag, then encTag and hashTag are ignored. If pbe is an encryption
641 * algorithm, then PKCS #5 V2 is used with prfTag for the prf. If prfTag isn't
642 * supplied prf will be SEC_OID_HMAC_SHA1 */
643SECKEYEncryptedPrivateKeyInfo *PK11_ExportEncryptedPrivKeyInfoV2(
644 PK11SlotInfo *slot, SECOidTag pbeTag, SECOidTag encTag, SECOidTag prfTag,
645 SECItem *pwitem, SECKEYPrivateKey *pk, int iteration, void *pwArg);
646SECKEYEncryptedPrivateKeyInfo *PK11_ExportEncryptedPrivateKeyInfoV2(
647 PK11SlotInfo *slot, SECOidTag pbeTag, SECOidTag encTag, SECOidTag prfTag,
648 SECItem *pwitem, CERTCertificate *cert, int iteration, void *pwArg);
649SECKEYPrivateKey *PK11_FindKeyByDERCert(PK11SlotInfo *slot,
650 CERTCertificate *cert, void *wincx);
651SECKEYPublicKey *PK11_MakeKEAPubKey(unsigned char *data, int length);
652SECStatus PK11_DigestKey(PK11Context *context, PK11SymKey *key);
653PRBool PK11_VerifyKeyOK(PK11SymKey *key);
654SECKEYPrivateKey *PK11_UnwrapPrivKey(PK11SlotInfo *slot,
655 PK11SymKey *wrappingKey, CK_MECHANISM_TYPE wrapType,
656 SECItem *param, SECItem *wrappedKey, SECItem *label,
657 SECItem *publicValue, PRBool token, PRBool sensitive,
658 CK_KEY_TYPE keyType, CK_ATTRIBUTE_TYPE *usage, int usageCount,
659 void *wincx);
660SECStatus PK11_WrapPrivKey(PK11SlotInfo *slot, PK11SymKey *wrappingKey,
661 SECKEYPrivateKey *privKey, CK_MECHANISM_TYPE wrapType,
662 SECItem *param, SECItem *wrappedKey, void *wincx);
663/*
664 * The caller of PK11_DEREncodePublicKey should free the returned SECItem with
665 * a SECITEM_FreeItem(..., PR_TRUE) call.
666 */
667SECItem *PK11_DEREncodePublicKey(const SECKEYPublicKey *pubk);
668PK11SymKey *PK11_CopySymKeyForSigning(PK11SymKey *originalKey,
669 CK_MECHANISM_TYPE mech);
670SECKEYPrivateKeyList *PK11_ListPrivKeysInSlot(PK11SlotInfo *slot,
671 char *nickname, void *wincx);
672SECKEYPublicKeyList *PK11_ListPublicKeysInSlot(PK11SlotInfo *slot,
673 char *nickname);
674SECKEYPQGParams *PK11_GetPQGParamsFromPrivateKey(SECKEYPrivateKey *privKey);
675/* deprecated */
676SECKEYPrivateKeyList *PK11_ListPrivateKeysInSlot(PK11SlotInfo *slot);
677
678PK11SymKey *PK11_ConvertSessionSymKeyToTokenSymKey(PK11SymKey *symk,
679 void *wincx);
680SECKEYPrivateKey *PK11_ConvertSessionPrivKeyToTokenPrivKey(
681 SECKEYPrivateKey *privk, void *wincx);
682SECKEYPrivateKey *PK11_CopyTokenPrivKeyToSessionPrivKey(PK11SlotInfo *destSlot,
683 SECKEYPrivateKey *privKey);
684
685/**********************************************************************
686 * Certs
687 **********************************************************************/
688SECItem *PK11_MakeIDFromPubKey(SECItem *pubKeyData);
689SECStatus PK11_TraverseSlotCerts(
690 SECStatus (*callback)(CERTCertificate *, SECItem *, void *),
691 void *arg, void *wincx);
692CERTCertificate *PK11_FindCertFromNickname(const char *nickname, void *wincx);
693CERTCertificate *PK11_FindCertFromURI(const char *uri, void *wincx);
694CERTCertList *PK11_FindCertsFromURI(const char *uri, void *wincx);
695CERTCertList *PK11_FindCertsFromEmailAddress(const char *email, void *wincx);
696CERTCertList *PK11_FindCertsFromNickname(const char *nickname, void *wincx);
697CERTCertificate *PK11_GetCertFromPrivateKey(SECKEYPrivateKey *privKey);
698SECStatus PK11_ImportCert(PK11SlotInfo *slot, CERTCertificate *cert,
699 CK_OBJECT_HANDLE key, const char *nickname,
700 PRBool includeTrust);
701SECStatus PK11_ImportDERCert(PK11SlotInfo *slot, SECItem *derCert,
702 CK_OBJECT_HANDLE key, char *nickname, PRBool includeTrust);
703PK11SlotInfo *PK11_ImportCertForKey(CERTCertificate *cert,
704 const char *nickname, void *wincx);
705PK11SlotInfo *PK11_ImportDERCertForKey(SECItem *derCert, char *nickname,
706 void *wincx);
707PK11SlotInfo *PK11_KeyForCertExists(CERTCertificate *cert,
708 CK_OBJECT_HANDLE *keyPtr, void *wincx);
709PK11SlotInfo *PK11_KeyForDERCertExists(SECItem *derCert,
710 CK_OBJECT_HANDLE *keyPtr, void *wincx);
711CERTCertificate *PK11_FindCertByIssuerAndSN(PK11SlotInfo **slot,
712 CERTIssuerAndSN *sn, void *wincx);
713CERTCertificate *PK11_FindCertAndKeyByRecipientList(PK11SlotInfo **slot,
714 SEC_PKCS7RecipientInfo **array, SEC_PKCS7RecipientInfo **rip,
715 SECKEYPrivateKey **privKey, void *wincx);
716int PK11_FindCertAndKeyByRecipientListNew(NSSCMSRecipient **recipientlist,
717 void *wincx);
718SECStatus PK11_TraverseCertsForSubjectInSlot(CERTCertificate *cert,
719 PK11SlotInfo *slot, SECStatus (*callback)(CERTCertificate *, void *),
720 void *arg);
721CERTCertificate *PK11_FindCertFromDERCert(PK11SlotInfo *slot,
722 CERTCertificate *cert, void *wincx);
723CERTCertificate *PK11_FindCertFromDERCertItem(PK11SlotInfo *slot,
724 const SECItem *derCert, void *wincx);
725SECStatus PK11_ImportCertForKeyToSlot(PK11SlotInfo *slot, CERTCertificate *cert,
726 char *nickname, PRBool addUsage,
727 void *wincx);
728CERTCertificate *PK11_FindBestKEAMatch(CERTCertificate *serverCert, void *wincx);
729PRBool PK11_FortezzaHasKEA(CERTCertificate *cert);
730CK_OBJECT_HANDLE PK11_FindEncodedCertInSlot(PK11SlotInfo *slot, SECItem *derCert, void *wincx);
731CK_OBJECT_HANDLE PK11_FindCertInSlot(PK11SlotInfo *slot, CERTCertificate *cert,
732 void *wincx);
733CK_OBJECT_HANDLE PK11_FindObjectForCert(CERTCertificate *cert,
734 void *wincx, PK11SlotInfo **pSlot);
735SECStatus PK11_TraverseCertsForNicknameInSlot(SECItem *nickname,
736 PK11SlotInfo *slot, SECStatus (*callback)(CERTCertificate *, void *),
737 void *arg);
738CERTCertList *PK11_ListCerts(PK11CertListType type, void *pwarg);
739CERTCertList *PK11_ListCertsInSlot(PK11SlotInfo *slot);
740CERTSignedCrl *PK11_ImportCRL(PK11SlotInfo *slot, SECItem *derCRL, char *url,
741 int type, void *wincx, PRInt32 importOptions, PLArenaPool *arena, PRInt32 decodeOptions);
742CK_BBOOL PK11_HasAttributeSet(PK11SlotInfo *slot,
743 CK_OBJECT_HANDLE id,
744 CK_ATTRIBUTE_TYPE type,
745 PRBool haslock /* must be set to PR_FALSE */);
746
747/**********************************************************************
748 * Hybrid Public Key Encryption
749 **********************************************************************/
750
751/* Some of the various HPKE arguments would ideally be const, but the
752 * underlying PK11 functions take them as non-const. To avoid lying to
753 * the application with a cast, this idiosyncrasy is exposed. */
754SECStatus PK11_HPKE_ValidateParameters(HpkeKemId kemId, HpkeKdfId kdfId, HpkeAeadId aeadId);
755HpkeContext *PK11_HPKE_NewContext(HpkeKemId kemId, HpkeKdfId kdfId, HpkeAeadId aeadId,
756 PK11SymKey *psk, const SECItem *pskId);
757SECStatus PK11_HPKE_Deserialize(const HpkeContext *cx, const PRUint8 *enc,
758 unsigned int encLen, SECKEYPublicKey **outPubKey);
759void PK11_HPKE_DestroyContext(HpkeContext *cx, PRBool freeit);
760
761/* Serialize an initialized receiver context. This only retains the keys and
762 * associated information necessary to resume Export and Open operations after
763 * import. Serialization is currently supported for receiver contexts only.
764 * This is done for two reasons: 1) it avoids having to move the encryption
765 * sequence number outside of the token (or adding encryption context
766 * serialization support to softoken), and 2) we don't have to worry about IV
767 * reuse due to sequence number cloning.
768 *
769 * |wrapKey| is required when exporting in FIPS mode. If exported with a
770 * wrapping key, that same key must be provided to the import function,
771 * otherwise behavior is undefined.
772 *
773 * Even when exported with key wrap, HPKE expects the nonce to also be kept
774 * secret and that value is not protected by wrapKey. Applications are
775 * responsible for maintaining the confidentiality of the exported information.
776 */
777SECStatus PK11_HPKE_ExportContext(const HpkeContext *cx, PK11SymKey *wrapKey, SECItem **serialized);
778SECStatus PK11_HPKE_ExportSecret(const HpkeContext *cx, const SECItem *info, unsigned int L,
779 PK11SymKey **outKey);
780const SECItem *PK11_HPKE_GetEncapPubKey(const HpkeContext *cx);
781HpkeContext *PK11_HPKE_ImportContext(const SECItem *serialized, PK11SymKey *wrapKey);
782SECStatus PK11_HPKE_Open(HpkeContext *cx, const SECItem *aad, const SECItem *ct, SECItem **outPt);
783SECStatus PK11_HPKE_Seal(HpkeContext *cx, const SECItem *aad, const SECItem *pt, SECItem **outCt);
784SECStatus PK11_HPKE_Serialize(const SECKEYPublicKey *pk, PRUint8 *buf, unsigned int *len, unsigned int maxLen);
785SECStatus PK11_HPKE_SetupS(HpkeContext *cx, const SECKEYPublicKey *pkE, SECKEYPrivateKey *skE,
786 SECKEYPublicKey *pkR, const SECItem *info);
787SECStatus PK11_HPKE_SetupR(HpkeContext *cx, const SECKEYPublicKey *pkR, SECKEYPrivateKey *skR,
788 const SECItem *enc, const SECItem *info);
789
790/**********************************************************************
791 * Sign/Verify
792 **********************************************************************/
793
794/*
795 * Return the length in bytes of a signature generated with the
796 * private key.
797 *
798 * Return 0 or -1 on failure. (XXX Should we fix it to always return
799 * -1 on failure?)
800 */
801int PK11_SignatureLen(SECKEYPrivateKey *key);
802PK11SlotInfo *PK11_GetSlotFromPrivateKey(SECKEYPrivateKey *key);
803SECStatus PK11_Sign(SECKEYPrivateKey *key, SECItem *sig,
804 const SECItem *hash);
805SECStatus PK11_SignWithMechanism(SECKEYPrivateKey *key,
806 CK_MECHANISM_TYPE mechanism,
807 const SECItem *param, SECItem *sig,
808 const SECItem *hash);
809SECStatus PK11_SignWithSymKey(PK11SymKey *symKey, CK_MECHANISM_TYPE mechanism,
810 SECItem *param, SECItem *sig, const SECItem *data);
811SECStatus PK11_VerifyRecover(SECKEYPublicKey *key, const SECItem *sig,
812 SECItem *dsig, void *wincx);
813SECStatus PK11_Verify(SECKEYPublicKey *key, const SECItem *sig,
814 const SECItem *hash, void *wincx);
815SECStatus PK11_VerifyWithMechanism(SECKEYPublicKey *key,
816 CK_MECHANISM_TYPE mechanism,
817 const SECItem *param, const SECItem *sig,
818 const SECItem *hash, void *wincx);
819
820/**********************************************************************
821 * Key Encapsulation Mechanisms
822 **********************************************************************/
823
824/*
825 * Using the given |pubKey|, generate a shared secret in |outKey| and an
826 * encapsulation of it in |ciphertext|. |outKey| will have usage attributes as
827 * specified in |attrFlags| and operation attributes as specified in |opFlags|.
828 *
829 * The function asserts that |pubKey|, |outKey|, and |ciphertext| are not NULL.
830
831 * If an error occurs, no allocations are made to |outKey| and |ciphertext|;
832 * otherwise (if SECSuccess is returned) allocations are made to |outKey| and
833 * |ciphertext| and the caller is responsible for freeing the memory occupied
834 * by these structures.
835 */
836SECStatus PK11_Encapsulate(SECKEYPublicKey *pubKey, CK_MECHANISM_TYPE target,
837 PK11AttrFlags attrFlags, CK_FLAGS opFlags,
838 PK11SymKey **outKey, SECItem **outCiphertext);
839
840/*
841 * Using the given |privKey|, decapsulate |ciphertext| and put the resulting
842 * shared secret in |outKey|. |outKey| will have usage attributes as specified
843 * in |attrFlags| and operation attributes as specified in |opFlags|.
844 *
845 * The function asserts that |privKey|, |ciphertext|, and |outKey| are not NULL.
846
847 * If an error occurs, |outKey| is not allocated; otherwise (if SECSuccess is
848 * returned) |outKey| is allocated and the caller is responsible for freeing
849 * the memory occupied by it.
850 */
851SECStatus
852PK11_Decapsulate(SECKEYPrivateKey *privKey, const SECItem *ciphertext,
853 CK_MECHANISM_TYPE target, PK11AttrFlags attrFlags,
854 CK_FLAGS opFlags, PK11SymKey **outKey);
855
856/**********************************************************************
857 * Crypto Contexts
858 **********************************************************************/
859void PK11_DestroyContext(PK11Context *context, PRBool freeit);
860PK11Context *PK11_CreateContextBySymKey(CK_MECHANISM_TYPE type,
861 CK_ATTRIBUTE_TYPE operation,
862 PK11SymKey *symKey,
863 const SECItem *param);
864PK11Context *PK11_CreateContextByPubKey(CK_MECHANISM_TYPE type,
865 CK_ATTRIBUTE_TYPE operation,
866 SECKEYPublicKey *pubKey,
867 const SECItem *param, void *pwArg);
868PK11Context *PK11_CreateContextByPrivKey(CK_MECHANISM_TYPE type,
869 CK_ATTRIBUTE_TYPE operation,
870 SECKEYPrivateKey *privKey,
871 const SECItem *param);
872PK11Context *PK11_CreateDigestContext(SECOidTag hashAlg);
873PK11Context *PK11_CloneContext(PK11Context *old);
874SECStatus PK11_DigestBegin(PK11Context *cx);
875/*
876 * The output buffer 'out' must be big enough to hold the output of
877 * the hash algorithm 'hashAlg'.
878 */
879SECStatus PK11_HashBuf(SECOidTag hashAlg, unsigned char *out,
880 const unsigned char *in, PRInt32 len);
881SECStatus PK11_DigestOp(PK11Context *context, const unsigned char *in,
882 unsigned len);
883SECStatus PK11_CipherOp(PK11Context *context, unsigned char *out, int *outlen,
884 int maxout, const unsigned char *in, int inlen);
885/* application builds the mechanism specific params */
886SECStatus PK11_AEADRawOp(PK11Context *context, void *params, int paramslen,
887 const unsigned char *aad, int aadlen,
888 unsigned char *out, int *outlen,
889 int maxout, const unsigned char *in, int inlen);
890/* NSS builds the mechanism specific params */
891SECStatus PK11_AEADOp(PK11Context *context, CK_GENERATOR_FUNCTION ivGen,
892 int fixedbits, unsigned char *iv, int ivlen,
893 const unsigned char *aad, int aadlen,
894 unsigned char *out, int *outlen,
895 int maxout, unsigned char *tag, int taglen,
896 const unsigned char *in, int inlen);
897
898SECStatus PK11_Finalize(PK11Context *context);
899SECStatus PK11_DigestFinal(PK11Context *context, unsigned char *data,
900 unsigned int *outLen, unsigned int length);
901#define PK11_CipherFinal PK11_DigestFinal
902SECStatus PK11_SaveContext(PK11Context *cx, unsigned char *save,
903 int *len, int saveLength);
904
905/* Save the context's state, with possible allocation.
906 * The caller may supply an already allocated buffer in preAllocBuf,
907 * with length pabLen. If the buffer is large enough for the context's
908 * state, it will receive the state.
909 * If the buffer is not large enough (or NULL), then a new buffer will
910 * be allocated with PORT_Alloc.
911 * In either case, the state will be returned as a buffer, and the length
912 * of the state will be given in *stateLen.
913 */
914unsigned char *
915PK11_SaveContextAlloc(PK11Context *cx,
916 unsigned char *preAllocBuf, unsigned int pabLen,
917 unsigned int *stateLen);
918
919SECStatus PK11_RestoreContext(PK11Context *cx, unsigned char *save, int len);
920SECStatus PK11_GenerateFortezzaIV(PK11SymKey *symKey, unsigned char *iv, int len);
921void PK11_SetFortezzaHack(PK11SymKey *symKey);
922
923/**********************************************************************
924 * PBE functions
925 **********************************************************************/
926
927/* This function creates PBE parameters from the given inputs. The result
928 * can be used to create a password integrity key for PKCS#12, by sending
929 * the return value to PK11_KeyGen along with the appropriate mechanism.
930 */
931SECItem *
932PK11_CreatePBEParams(SECItem *salt, SECItem *pwd, unsigned int iterations);
933
934/* free params created above (can be called after keygen is done */
935void PK11_DestroyPBEParams(SECItem *params);
936
937SECAlgorithmID *
938PK11_CreatePBEAlgorithmID(SECOidTag algorithm, int iteration, SECItem *salt);
939
940/* use to create PKCS5 V2 algorithms with finder control than that provided
941 * by PK11_CreatePBEAlgorithmID. */
942SECAlgorithmID *
943PK11_CreatePBEV2AlgorithmID(SECOidTag pbeAlgTag, SECOidTag cipherAlgTag,
944 SECOidTag prfAlgTag, int keyLength, int iteration,
945 SECItem *salt);
946PK11SymKey *
947PK11_PBEKeyGen(PK11SlotInfo *slot, SECAlgorithmID *algid, SECItem *pwitem,
948 PRBool faulty3DES, void *wincx);
949
950/* warning: cannot work with PKCS 5 v2 use PK11_PBEKeyGen instead */
951PK11SymKey *
952PK11_RawPBEKeyGen(PK11SlotInfo *slot, CK_MECHANISM_TYPE type, SECItem *params,
953 SECItem *pwitem, PRBool faulty3DES, void *wincx);
954SECItem *
955PK11_GetPBEIV(SECAlgorithmID *algid, SECItem *pwitem);
956/*
957 * Get the Mechanism and parameter of the base encryption or mac scheme from
958 * a PBE algorithm ID.
959 * Caller is responsible for freeing the return parameter (param).
960 */
961CK_MECHANISM_TYPE
962PK11_GetPBECryptoMechanism(SECAlgorithmID *algid,
963 SECItem **param, SECItem *pwd);
964
965/**********************************************************************
966 * Functions to manage secmod flags
967 **********************************************************************/
968const PK11DefaultArrayEntry *PK11_GetDefaultArray(int *size);
969SECStatus PK11_UpdateSlotAttribute(PK11SlotInfo *slot,
970 const PK11DefaultArrayEntry *entry,
971 PRBool add);
972
973/**********************************************************************
974 * Functions to look at PKCS #11 dependent data
975 **********************************************************************/
976PK11GenericObject *PK11_FindGenericObjects(PK11SlotInfo *slot,
977 CK_OBJECT_CLASS objClass);
978PK11GenericObject *PK11_GetNextGenericObject(PK11GenericObject *object);
979PK11GenericObject *PK11_GetPrevGenericObject(PK11GenericObject *object);
980SECStatus PK11_UnlinkGenericObject(PK11GenericObject *object);
981SECStatus PK11_LinkGenericObject(PK11GenericObject *list,
982 PK11GenericObject *object);
983SECStatus PK11_DestroyGenericObjects(PK11GenericObject *object);
984SECStatus PK11_DestroyGenericObject(PK11GenericObject *object);
985PK11GenericObject *PK11_CreateManagedGenericObject(PK11SlotInfo *slot,
986 const CK_ATTRIBUTE *pTemplate,
987 int count, PRBool token);
988/* deprecated */
989PK11GenericObject *PK11_CreateGenericObject(PK11SlotInfo *slot,
990 const CK_ATTRIBUTE *pTemplate,
991 int count, PRBool token);
992
993/*
994 * PK11_ReadRawAttribute and PK11_WriteRawAttribute are generic
995 * functions to read and modify the actual PKCS #11 attributes of
996 * the underlying pkcs #11 object.
997 *
998 * object is a pointer to an NSS object that represents the underlying
999 * PKCS #11 object. It's type must match the type of PK11ObjectType
1000 * as follows:
1001 *
1002 * type object
1003 * PK11_TypeGeneric PK11GenericObject *
1004 * PK11_TypePrivKey SECKEYPrivateKey *
1005 * PK11_TypePubKey SECKEYPublicKey *
1006 * PK11_TypeSymKey PK11SymKey *
1007 *
1008 * All other types are considered invalid. If type does not match the object
1009 * passed, unpredictable results will occur.
1010 *
1011 * PK11_ReadRawAttribute allocates the buffer for returning the attribute
1012 * value. The caller of PK11_ReadRawAttribute should free the data buffer
1013 * pointed to by item using a SECITEM_FreeItem(item, PR_FALSE) or
1014 * PORT_Free(item->data) call.
1015 */
1016SECStatus PK11_ReadRawAttribute(PK11ObjectType type, void *object,
1017 CK_ATTRIBUTE_TYPE attr, SECItem *item);
1018SECStatus PK11_ReadRawAttributes(PLArenaPool *arena, PK11ObjectType type, void *object,
1019 CK_ATTRIBUTE *pTemplate, unsigned int count);
1020SECStatus PK11_WriteRawAttribute(PK11ObjectType type, void *object,
1021 CK_ATTRIBUTE_TYPE attr, SECItem *item);
1022/* get the PKCS #11 handle and slot for a generic object */
1023CK_OBJECT_HANDLE PK11_GetObjectHandle(PK11ObjectType objType, void *objSpec,
1024 PK11SlotInfo **slotp);
1025
1026/*
1027 * PK11_GetAllSlotsForCert returns all the slots that a given certificate
1028 * exists on, since it's possible for a cert to exist on more than one
1029 * PKCS#11 token.
1030 */
1031PK11SlotList *
1032PK11_GetAllSlotsForCert(CERTCertificate *cert, void *arg);
1033
1034/*
1035 * Finds all certificates on the given slot with the given subject distinguished
1036 * name and returns them as DER bytes. If no such certificates can be found,
1037 * returns SECSuccess and sets *results to NULL. If a failure is encountered
1038 * while fetching any of the matching certificates, SECFailure is returned and
1039 * *results will be NULL.
1040 */
1041SECStatus
1042PK11_FindRawCertsWithSubject(PK11SlotInfo *slot, SECItem *derSubject,
1043 CERTCertificateList **results);
1044
1045/*
1046 * Finds and returns all certificates with a public key that matches the given
1047 * private key. May return an empty list if no certificates match. Returns NULL
1048 * if a failure is encountered.
1049 */
1050CERTCertList *
1051PK11_GetCertsMatchingPrivateKey(SECKEYPrivateKey *privKey);
1052
1053/**********************************************************************
1054 * New functions which are already deprecated....
1055 **********************************************************************/
1056SECItem *
1057PK11_GetLowLevelKeyIDForCert(PK11SlotInfo *slot,
1058 CERTCertificate *cert, void *pwarg);
1059SECItem *
1060PK11_GetLowLevelKeyIDForPrivateKey(SECKEYPrivateKey *key);
1061
1062PRBool SECMOD_HasRootCerts(void);
1063
1064/**********************************************************************
1065 * Other Utilities
1066 **********************************************************************/
1067/*
1068 * Get the state of the system FIPS mode -
1069 * NSS uses this to force FIPS mode if the system bit is on. This returns
1070 * the system state independent of the database state and can be called
1071 * before NSS initializes.
1072 */
1073int SECMOD_GetSystemFIPSEnabled(void);
1074
1075/* FIPS indicator functions. Some operations are physically allowed, but
1076 * are against the NSS FIPS security policy. This is because sometimes NSS
1077 * functions are used in non-security contexts. You can call these functions
1078 * to determine if you are operating inside or outside the the current vendor's
1079 * FIPS Security Policy for NSS. NOTE: if the current version of NSS is not
1080 * actually FIPS certified, then these functions will always return PR_FALSE */
1081
1082/* This function tells if if the last single shot operation on the slot
1083 * was inside or outside the FIPS security policy */
1084PRBool PK11_SlotGetLastFIPSStatus(PK11SlotInfo *slot);
1085/* This tells you if the current operation is within the FIPS security policy. If
1086 * you have called finalize on the context, it tells you if the last operation
1087 * was within the FIPS security policy */
1088PRBool PK11_ContextGetFIPSStatus(PK11Context *context);
1089/* This tells you if the requested object was created in accordance to the
1090 * NSS FIPS security policy. */
1091PRBool PK11_ObjectGetFIPSStatus(PK11ObjectType objType, void *objSpec);
1092
1093SEC_END_PROTOS
1094
1095#endif
1096

source code of include/nss/pk11pub.h