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