summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/pki/nsspki.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--security/nss/lib/pki/nsspki.h2791
1 files changed, 2791 insertions, 0 deletions
diff --git a/security/nss/lib/pki/nsspki.h b/security/nss/lib/pki/nsspki.h
new file mode 100644
index 0000000000..f3c6e51684
--- /dev/null
+++ b/security/nss/lib/pki/nsspki.h
@@ -0,0 +1,2791 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+#ifndef NSSPKI_H
+#define NSSPKI_H
+
+/*
+ * nsspki.h
+ *
+ * This file prototypes the methods of the top-level PKI objects.
+ */
+
+#ifndef NSSDEVT_H
+#include "nssdevt.h"
+#endif /* NSSDEVT_H */
+
+#ifndef NSSPKIT_H
+#include "nsspkit.h"
+#endif /* NSSPKIT_H */
+
+#ifndef BASE_H
+#include "base.h"
+#endif /* BASE_H */
+
+#include "pkcs11uri.h"
+
+PR_BEGIN_EXTERN_C
+
+/*
+ * A note about interfaces
+ *
+ * Although these APIs are specified in C, a language which does
+ * not have fancy support for abstract interfaces, this library
+ * was designed from an object-oriented perspective. It may be
+ * useful to consider the standard interfaces which went into
+ * the writing of these APIs.
+ *
+ * Basic operations on all objects:
+ * Destroy -- free a pointer to an object
+ * DeleteStoredObject -- delete an object permanently
+ *
+ * Public Key cryptographic operations:
+ * Encrypt
+ * Verify
+ * VerifyRecover
+ * Wrap
+ * Derive
+ *
+ * Private Key cryptographic operations:
+ * IsStillPresent
+ * Decrypt
+ * Sign
+ * SignRecover
+ * Unwrap
+ * Derive
+ *
+ * Symmetric Key cryptographic operations:
+ * IsStillPresent
+ * Encrypt
+ * Decrypt
+ * Sign
+ * SignRecover
+ * Verify
+ * VerifyRecover
+ * Wrap
+ * Unwrap
+ * Derive
+ *
+ */
+
+/*
+ * NSSCertificate
+ *
+ * These things can do crypto ops like public keys, except that the trust,
+ * usage, and other constraints are checked. These objects are "high-level,"
+ * so trust, usages, etc. are in the form we throw around (client auth,
+ * email signing, etc.). Remember that theoretically another implementation
+ * (think PGP) could be beneath this object.
+ */
+
+/*
+ * NSSCertificate_Destroy
+ *
+ * Free a pointer to a certificate object.
+ */
+
+NSS_EXTERN PRStatus
+NSSCertificate_Destroy(NSSCertificate *c);
+
+/*
+ * NSSCertificate_DeleteStoredObject
+ *
+ * Permanently remove this certificate from storage. If this is the
+ * only (remaining) certificate corresponding to a private key,
+ * public key, and/or other object; then that object (those objects)
+ * are deleted too.
+ */
+
+NSS_EXTERN PRStatus
+NSSCertificate_DeleteStoredObject(
+ NSSCertificate *c,
+ NSSCallback *uhh);
+
+/*
+ * NSSCertificate_Validate
+ *
+ * Verify that this certificate is trusted, for the specified usage(s),
+ * at the specified time, {word word} the specified policies.
+ */
+
+NSS_EXTERN PRStatus
+NSSCertificate_Validate(
+ NSSCertificate *c,
+ NSSTime *timeOpt, /* NULL for "now" */
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt /* NULL for none */
+);
+
+/*
+ * NSSCertificate_ValidateCompletely
+ *
+ * Verify that this certificate is trusted. The difference between
+ * this and the previous call is that NSSCertificate_Validate merely
+ * returns success or failure with an appropriate error stack.
+ * However, there may be (and often are) multiple problems with a
+ * certificate. This routine returns an array of errors, specifying
+ * every problem.
+ */
+
+/*
+ * Return value must be an array of objects, each of which has
+ * an NSSError, and any corresponding certificate (in the chain)
+ * and/or policy.
+ */
+
+NSS_EXTERN void ** /* void *[] */
+NSSCertificate_ValidateCompletely(
+ NSSCertificate *c,
+ NSSTime *timeOpt, /* NULL for "now" */
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt, /* NULL for none */
+ void **rvOpt, /* NULL for allocate */
+ PRUint32 rvLimit, /* zero for no limit */
+ NSSArena *arenaOpt /* NULL for heap */
+);
+
+/*
+ * NSSCertificate_ValidateAndDiscoverUsagesAndPolicies
+ *
+ * Returns PR_SUCCESS if the certificate is valid for at least something.
+ */
+
+NSS_EXTERN PRStatus
+NSSCertificate_ValidateAndDiscoverUsagesAndPolicies(
+ NSSCertificate *c,
+ NSSTime **notBeforeOutOpt,
+ NSSTime **notAfterOutOpt,
+ void *allowedUsages,
+ void *disallowedUsages,
+ void *allowedPolicies,
+ void *disallowedPolicies,
+ /* more args.. work on this fgmr */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCertificate_Encode
+ *
+ */
+
+NSS_EXTERN NSSDER *
+NSSCertificate_Encode(
+ NSSCertificate *c,
+ NSSDER *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCertificate_BuildChain
+ *
+ * This routine returns NSSCertificate *'s for each certificate
+ * in the "chain" starting from the specified one up to and
+ * including the root. The zeroth element in the array is the
+ * specified ("leaf") certificate.
+ *
+ * If statusOpt is supplied, and is returned as PR_FAILURE, possible
+ * error values are:
+ *
+ * NSS_ERROR_CERTIFICATE_ISSUER_NOT_FOUND - the chain is incomplete
+ *
+ */
+
+extern const NSSError NSS_ERROR_CERTIFICATE_ISSUER_NOT_FOUND;
+
+NSS_EXTERN NSSCertificate **
+NSSCertificate_BuildChain(
+ NSSCertificate *c,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCertificate **rvOpt,
+ PRUint32 rvLimit, /* zero for no limit */
+ NSSArena *arenaOpt,
+ PRStatus *statusOpt,
+ NSSTrustDomain *td,
+ NSSCryptoContext *cc);
+
+/*
+ * NSSCertificate_GetTrustDomain
+ *
+ */
+
+NSS_EXTERN NSSTrustDomain *
+NSSCertificate_GetTrustDomain(NSSCertificate *c);
+
+/*
+ * NSSCertificate_GetToken
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSToken *
+NSSCertificate_GetToken(
+ NSSCertificate *c,
+ PRStatus *statusOpt);
+
+/*
+ * NSSCertificate_GetSlot
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSSlot *
+NSSCertificate_GetSlot(
+ NSSCertificate *c,
+ PRStatus *statusOpt);
+
+/*
+ * NSSCertificate_GetModule
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSModule *
+NSSCertificate_GetModule(
+ NSSCertificate *c,
+ PRStatus *statusOpt);
+
+/*
+ * NSSCertificate_Encrypt
+ *
+ * Encrypt a single chunk of data with the public key corresponding to
+ * this certificate.
+ */
+
+NSS_EXTERN NSSItem *
+NSSCertificate_Encrypt(
+ NSSCertificate *c,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCertificate_Verify
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCertificate_Verify(
+ NSSCertificate *c,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSItem *signature,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCallback *uhh);
+
+/*
+ * NSSCertificate_VerifyRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCertificate_VerifyRecover(
+ NSSCertificate *c,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *signature,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCertificate_WrapSymmetricKey
+ *
+ * This method tries very hard to to succeed, even in situations
+ * involving sensitive keys and multiple modules.
+ * { relyea: want to add verbiage? }
+ */
+
+NSS_EXTERN NSSItem *
+NSSCertificate_WrapSymmetricKey(
+ NSSCertificate *c,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSSymmetricKey *keyToWrap,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCertificate_CreateCryptoContext
+ *
+ * Create a crypto context, in this certificate's trust domain, with this
+ * as the distinguished certificate.
+ */
+
+NSS_EXTERN NSSCryptoContext *
+NSSCertificate_CreateCryptoContext(
+ NSSCertificate *c,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCallback *uhh);
+
+/*
+ * NSSCertificate_GetPublicKey
+ *
+ * Returns the public key corresponding to this certificate.
+ */
+
+NSS_EXTERN NSSPublicKey *
+NSSCertificate_GetPublicKey(NSSCertificate *c);
+
+/*
+ * NSSCertificate_FindPrivateKey
+ *
+ * Finds and returns the private key corresponding to this certificate,
+ * if it is available.
+ *
+ * { Should this hang off of NSSUserCertificate? }
+ */
+
+NSS_EXTERN NSSPrivateKey *
+NSSCertificate_FindPrivateKey(
+ NSSCertificate *c,
+ NSSCallback *uhh);
+
+/*
+ * NSSCertificate_IsPrivateKeyAvailable
+ *
+ * Returns success if the private key corresponding to this certificate
+ * is available to be used.
+ *
+ * { Should *this* hang off of NSSUserCertificate?? }
+ */
+
+NSS_EXTERN PRBool
+NSSCertificate_IsPrivateKeyAvailable(
+ NSSCertificate *c,
+ NSSCallback *uhh,
+ PRStatus *statusOpt);
+
+/*
+ * If we make NSSUserCertificate not a typedef of NSSCertificate,
+ * then we'll need implementations of the following:
+ *
+ * NSSUserCertificate_Destroy
+ * NSSUserCertificate_DeleteStoredObject
+ * NSSUserCertificate_Validate
+ * NSSUserCertificate_ValidateCompletely
+ * NSSUserCertificate_ValidateAndDiscoverUsagesAndPolicies
+ * NSSUserCertificate_Encode
+ * NSSUserCertificate_BuildChain
+ * NSSUserCertificate_GetTrustDomain
+ * NSSUserCertificate_GetToken
+ * NSSUserCertificate_GetSlot
+ * NSSUserCertificate_GetModule
+ * NSSUserCertificate_GetCryptoContext
+ * NSSUserCertificate_GetPublicKey
+ */
+
+/*
+ * NSSUserCertificate_IsStillPresent
+ *
+ * Verify that if this certificate lives on a token, that the token
+ * is still present and the certificate still exists. This is a
+ * lightweight call which should be used whenever it should be
+ * verified that the user hasn't perhaps popped out his or her
+ * token and strolled away.
+ */
+
+NSS_EXTERN PRBool
+NSSUserCertificate_IsStillPresent(
+ NSSUserCertificate *uc,
+ PRStatus *statusOpt);
+
+/*
+ * NSSUserCertificate_Decrypt
+ *
+ * Decrypt a single chunk of data with the private key corresponding
+ * to this certificate.
+ */
+
+NSS_EXTERN NSSItem *
+NSSUserCertificate_Decrypt(
+ NSSUserCertificate *uc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSUserCertificate_Sign
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSUserCertificate_Sign(
+ NSSUserCertificate *uc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSUserCertificate_SignRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSUserCertificate_SignRecover(
+ NSSUserCertificate *uc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSUserCertificate_UnwrapSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSUserCertificate_UnwrapSymmetricKey(
+ NSSUserCertificate *uc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *wrappedKey,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSUserCertificate_DeriveSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSUserCertificate_DeriveSymmetricKey(
+ NSSUserCertificate *uc, /* provides private key */
+ NSSCertificate *c, /* provides public key */
+ NSSAlgorithmAndParameters *apOpt,
+ NSSOID *target,
+ PRUint32 keySizeOpt, /* zero for best allowed */
+ NSSOperations operations,
+ NSSCallback *uhh);
+
+/* filter-certs function(s) */
+
+/**
+ ** fgmr -- trust objects
+ **/
+
+/*
+ * NSSPrivateKey
+ *
+ */
+
+/*
+ * NSSPrivateKey_Destroy
+ *
+ * Free a pointer to a private key object.
+ */
+
+NSS_EXTERN PRStatus
+NSSPrivateKey_Destroy(NSSPrivateKey *vk);
+
+/*
+ * NSSPrivateKey_DeleteStoredObject
+ *
+ * Permanently remove this object, and any related objects (such as the
+ * certificates corresponding to this key).
+ */
+
+NSS_EXTERN PRStatus
+NSSPrivateKey_DeleteStoredObject(
+ NSSPrivateKey *vk,
+ NSSCallback *uhh);
+
+/*
+ * NSSPrivateKey_GetSignatureLength
+ *
+ */
+
+NSS_EXTERN PRUint32
+NSSPrivateKey_GetSignatureLength(NSSPrivateKey *vk);
+
+/*
+ * NSSPrivateKey_GetPrivateModulusLength
+ *
+ */
+
+NSS_EXTERN PRUint32
+NSSPrivateKey_GetPrivateModulusLength(NSSPrivateKey *vk);
+
+/*
+ * NSSPrivateKey_IsStillPresent
+ *
+ */
+
+NSS_EXTERN PRBool
+NSSPrivateKey_IsStillPresent(
+ NSSPrivateKey *vk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSPrivateKey_Encode
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSPrivateKey_Encode(
+ NSSPrivateKey *vk,
+ NSSAlgorithmAndParameters *ap,
+ NSSItem *passwordOpt, /* NULL will cause a callback; "" for no password */
+ NSSCallback *uhhOpt,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPrivateKey_GetTrustDomain
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSTrustDomain *
+NSSPrivateKey_GetTrustDomain(
+ NSSPrivateKey *vk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSPrivateKey_GetToken
+ *
+ */
+
+NSS_EXTERN NSSToken *
+NSSPrivateKey_GetToken(NSSPrivateKey *vk);
+
+/*
+ * NSSPrivateKey_GetSlot
+ *
+ */
+
+NSS_EXTERN NSSSlot *
+NSSPrivateKey_GetSlot(NSSPrivateKey *vk);
+
+/*
+ * NSSPrivateKey_GetModule
+ *
+ */
+
+NSS_EXTERN NSSModule *
+NSSPrivateKey_GetModule(NSSPrivateKey *vk);
+
+/*
+ * NSSPrivateKey_Decrypt
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSPrivateKey_Decrypt(
+ NSSPrivateKey *vk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *encryptedData,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPrivateKey_Sign
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSPrivateKey_Sign(
+ NSSPrivateKey *vk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPrivateKey_SignRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSPrivateKey_SignRecover(
+ NSSPrivateKey *vk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPrivateKey_UnwrapSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSPrivateKey_UnwrapSymmetricKey(
+ NSSPrivateKey *vk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *wrappedKey,
+ NSSCallback *uhh);
+
+/*
+ * NSSPrivateKey_DeriveSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSPrivateKey_DeriveSymmetricKey(
+ NSSPrivateKey *vk,
+ NSSPublicKey *bk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSOID *target,
+ PRUint32 keySizeOpt, /* zero for best allowed */
+ NSSOperations operations,
+ NSSCallback *uhh);
+
+/*
+ * NSSPrivateKey_FindPublicKey
+ *
+ */
+
+NSS_EXTERN NSSPublicKey *
+NSSPrivateKey_FindPublicKey(
+ NSSPrivateKey *vk
+ /* { don't need the callback here, right? } */
+);
+
+/*
+ * NSSPrivateKey_CreateCryptoContext
+ *
+ * Create a crypto context, in this key's trust domain,
+ * with this as the distinguished private key.
+ */
+
+NSS_EXTERN NSSCryptoContext *
+NSSPrivateKey_CreateCryptoContext(
+ NSSPrivateKey *vk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSCallback *uhh);
+
+/*
+ * NSSPrivateKey_FindCertificates
+ *
+ * Note that there may be more than one certificate for this
+ * private key. { FilterCertificates function to further
+ * reduce the list. }
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSPrivateKey_FindCertificates(
+ NSSPrivateKey *vk,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPrivateKey_FindBestCertificate
+ *
+ * The parameters for this function will depend on what the users
+ * need. This is just a starting point.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSPrivateKey_FindBestCertificate(
+ NSSPrivateKey *vk,
+ NSSTime *timeOpt,
+ NSSUsage *usageOpt,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSPublicKey
+ *
+ * Once you generate, find, or derive one of these, you can use it
+ * to perform (simple) cryptographic operations. Though there may
+ * be certificates associated with these public keys, they are not
+ * verified.
+ */
+
+/*
+ * NSSPublicKey_Destroy
+ *
+ * Free a pointer to a public key object.
+ */
+
+NSS_EXTERN PRStatus
+NSSPublicKey_Destroy(NSSPublicKey *bk);
+
+/*
+ * NSSPublicKey_DeleteStoredObject
+ *
+ * Permanently remove this object, and any related objects (such as the
+ * corresponding private keys and certificates).
+ */
+
+NSS_EXTERN PRStatus
+NSSPublicKey_DeleteStoredObject(
+ NSSPublicKey *bk,
+ NSSCallback *uhh);
+
+/*
+ * NSSPublicKey_Encode
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSPublicKey_Encode(
+ NSSPublicKey *bk,
+ NSSAlgorithmAndParameters *ap,
+ NSSCallback *uhhOpt,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPublicKey_GetTrustDomain
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSTrustDomain *
+NSSPublicKey_GetTrustDomain(
+ NSSPublicKey *bk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSPublicKey_GetToken
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSToken *
+NSSPublicKey_GetToken(
+ NSSPublicKey *bk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSPublicKey_GetSlot
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSSlot *
+NSSPublicKey_GetSlot(
+ NSSPublicKey *bk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSPublicKey_GetModule
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSModule *
+NSSPublicKey_GetModule(
+ NSSPublicKey *bk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSPublicKey_Encrypt
+ *
+ * Encrypt a single chunk of data with the public key corresponding to
+ * this certificate.
+ */
+
+NSS_EXTERN NSSItem *
+NSSPublicKey_Encrypt(
+ NSSPublicKey *bk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPublicKey_Verify
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSPublicKey_Verify(
+ NSSPublicKey *bk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSItem *signature,
+ NSSCallback *uhh);
+
+/*
+ * NSSPublicKey_VerifyRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSPublicKey_VerifyRecover(
+ NSSPublicKey *bk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *signature,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPublicKey_WrapSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSPublicKey_WrapSymmetricKey(
+ NSSPublicKey *bk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSSymmetricKey *keyToWrap,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPublicKey_CreateCryptoContext
+ *
+ * Create a crypto context, in this key's trust domain, with this
+ * as the distinguished public key.
+ */
+
+NSS_EXTERN NSSCryptoContext *
+NSSPublicKey_CreateCryptoContext(
+ NSSPublicKey *bk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSCallback *uhh);
+
+/*
+ * NSSPublicKey_FindCertificates
+ *
+ * Note that there may be more than one certificate for this
+ * public key. The current implementation may not find every
+ * last certificate available for this public key: that would
+ * involve trolling e.g. huge ldap databases, which will be
+ * grossly inefficient and not generally useful.
+ * { FilterCertificates function to further reduce the list }
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSPublicKey_FindCertificates(
+ NSSPublicKey *bk,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSPrivateKey_FindBestCertificate
+ *
+ * The parameters for this function will depend on what the users
+ * need. This is just a starting point.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSPublicKey_FindBestCertificate(
+ NSSPublicKey *bk,
+ NSSTime *timeOpt,
+ NSSUsage *usageOpt,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSPublicKey_FindPrivateKey
+ *
+ */
+
+NSS_EXTERN NSSPrivateKey *
+NSSPublicKey_FindPrivateKey(
+ NSSPublicKey *bk,
+ NSSCallback *uhh);
+
+/*
+ * NSSSymmetricKey
+ *
+ */
+
+/*
+ * NSSSymmetricKey_Destroy
+ *
+ * Free a pointer to a symmetric key object.
+ */
+
+NSS_EXTERN PRStatus
+NSSSymmetricKey_Destroy(NSSSymmetricKey *mk);
+
+/*
+ * NSSSymmetricKey_DeleteStoredObject
+ *
+ * Permanently remove this object.
+ */
+
+NSS_EXTERN PRStatus
+NSSSymmetricKey_DeleteStoredObject(
+ NSSSymmetricKey *mk,
+ NSSCallback *uhh);
+
+/*
+ * NSSSymmetricKey_GetKeyLength
+ *
+ */
+
+NSS_EXTERN PRUint32
+NSSSymmetricKey_GetKeyLength(NSSSymmetricKey *mk);
+
+/*
+ * NSSSymmetricKey_GetKeyStrength
+ *
+ */
+
+NSS_EXTERN PRUint32
+NSSSymmetricKey_GetKeyStrength(NSSSymmetricKey *mk);
+
+/*
+ * NSSSymmetricKey_IsStillPresent
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSSymmetricKey_IsStillPresent(NSSSymmetricKey *mk);
+
+/*
+ * NSSSymmetricKey_GetTrustDomain
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSTrustDomain *
+NSSSymmetricKey_GetTrustDomain(
+ NSSSymmetricKey *mk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSSymmetricKey_GetToken
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSToken *
+NSSSymmetricKey_GetToken(
+ NSSSymmetricKey *mk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSSymmetricKey_GetSlot
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSSlot *
+NSSSymmetricKey_GetSlot(
+ NSSSymmetricKey *mk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSSymmetricKey_GetModule
+ *
+ * There doesn't have to be one.
+ */
+
+NSS_EXTERN NSSModule *
+NSSSymmetricKey_GetModule(
+ NSSSymmetricKey *mk,
+ PRStatus *statusOpt);
+
+/*
+ * NSSSymmetricKey_Encrypt
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSSymmetricKey_Encrypt(
+ NSSSymmetricKey *mk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSSymmetricKey_Decrypt
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSSymmetricKey_Decrypt(
+ NSSSymmetricKey *mk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *encryptedData,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSSymmetricKey_Sign
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSSymmetricKey_Sign(
+ NSSSymmetricKey *mk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSSymmetricKey_SignRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSSymmetricKey_SignRecover(
+ NSSSymmetricKey *mk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSSymmetricKey_Verify
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSSymmetricKey_Verify(
+ NSSSymmetricKey *mk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSItem *signature,
+ NSSCallback *uhh);
+
+/*
+ * NSSSymmetricKey_VerifyRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSSymmetricKey_VerifyRecover(
+ NSSSymmetricKey *mk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *signature,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSSymmetricKey_WrapSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSSymmetricKey_WrapSymmetricKey(
+ NSSSymmetricKey *wrappingKey,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSSymmetricKey *keyToWrap,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSSymmetricKey_WrapPrivateKey
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSSymmetricKey_WrapPrivateKey(
+ NSSSymmetricKey *wrappingKey,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSPrivateKey *keyToWrap,
+ NSSCallback *uhh,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSSymmetricKey_UnwrapSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSSymmetricKey_UnwrapSymmetricKey(
+ NSSSymmetricKey *wrappingKey,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *wrappedKey,
+ NSSOID *target,
+ PRUint32 keySizeOpt,
+ NSSOperations operations,
+ NSSCallback *uhh);
+
+/*
+ * NSSSymmetricKey_UnwrapPrivateKey
+ *
+ */
+
+NSS_EXTERN NSSPrivateKey *
+NSSSymmetricKey_UnwrapPrivateKey(
+ NSSSymmetricKey *wrappingKey,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *wrappedKey,
+ NSSUTF8 *labelOpt,
+ NSSItem *keyIDOpt,
+ PRBool persistant,
+ PRBool sensitive,
+ NSSToken *destinationOpt,
+ NSSCallback *uhh);
+
+/*
+ * NSSSymmetricKey_DeriveSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSSymmetricKey_DeriveSymmetricKey(
+ NSSSymmetricKey *originalKey,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSOID *target,
+ PRUint32 keySizeOpt,
+ NSSOperations operations,
+ NSSCallback *uhh);
+
+/*
+ * NSSSymmetricKey_CreateCryptoContext
+ *
+ * Create a crypto context, in this key's trust domain,
+ * with this as the distinguished symmetric key.
+ */
+
+NSS_EXTERN NSSCryptoContext *
+NSSSymmetricKey_CreateCryptoContext(
+ NSSSymmetricKey *mk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSCallback *uhh);
+
+/*
+ * NSSTrustDomain
+ *
+ */
+
+/*
+ * NSSTrustDomain_Create
+ *
+ * This creates a trust domain, optionally with an initial cryptoki
+ * module. If the module name is not null, the module is loaded if
+ * needed (using the uriOpt argument), and initialized with the
+ * opaqueOpt argument. If mumble mumble priority settings, then
+ * module-specification objects in the module can cause the loading
+ * and initialization of further modules.
+ *
+ * The uriOpt is defined to take a URI. At present, we only
+ * support file: URLs pointing to platform-native shared libraries.
+ * However, by specifying this as a URI, this keeps open the
+ * possibility of supporting other, possibly remote, resources.
+ *
+ * The "reserved" arguments is held for when we figure out the
+ * module priority stuff.
+ */
+
+NSS_EXTERN NSSTrustDomain *
+NSSTrustDomain_Create(
+ NSSUTF8 *moduleOpt,
+ NSSUTF8 *uriOpt,
+ NSSUTF8 *opaqueOpt,
+ void *reserved);
+
+/*
+ * NSSTrustDomain_Destroy
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSTrustDomain_Destroy(NSSTrustDomain *td);
+
+/*
+ * NSSTrustDomain_SetDefaultCallback
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSTrustDomain_SetDefaultCallback(
+ NSSTrustDomain *td,
+ NSSCallback *newCallback,
+ NSSCallback **oldCallbackOpt);
+
+/*
+ * NSSTrustDomain_GetDefaultCallback
+ *
+ */
+
+NSS_EXTERN NSSCallback *
+NSSTrustDomain_GetDefaultCallback(
+ NSSTrustDomain *td,
+ PRStatus *statusOpt);
+
+/*
+ * Default policies?
+ * Default usage?
+ * Default time, for completeness?
+ */
+
+/*
+ * NSSTrustDomain_LoadModule
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSTrustDomain_LoadModule(
+ NSSTrustDomain *td,
+ NSSUTF8 *moduleOpt,
+ NSSUTF8 *uriOpt,
+ NSSUTF8 *opaqueOpt,
+ void *reserved);
+
+/*
+ * NSSTrustDomain_AddModule
+ * NSSTrustDomain_AddSlot
+ * NSSTrustDomain_UnloadModule
+ * Managing modules, slots, tokens; priorities;
+ * Traversing all of the above
+ * this needs more work
+ */
+
+/*
+ * NSSTrustDomain_DisableToken
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSTrustDomain_DisableToken(
+ NSSTrustDomain *td,
+ NSSToken *token,
+ NSSError why);
+
+/*
+ * NSSTrustDomain_EnableToken
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSTrustDomain_EnableToken(
+ NSSTrustDomain *td,
+ NSSToken *token);
+
+/*
+ * NSSTrustDomain_IsTokenEnabled
+ *
+ * If disabled, "why" is always on the error stack.
+ * The optional argument is just for convenience.
+ */
+
+NSS_EXTERN PRStatus
+NSSTrustDomain_IsTokenEnabled(
+ NSSTrustDomain *td,
+ NSSToken *token,
+ NSSError *whyOpt);
+
+/*
+ * NSSTrustDomain_FindTokensByURI
+ *
+ */
+
+NSS_EXTERN NSSToken **
+NSSTrustDomain_FindTokensByURI(
+ NSSTrustDomain *td,
+ PK11URI *uri);
+
+/*
+ * NSSTrustDomain_FindSlotByName
+ *
+ */
+
+NSS_EXTERN NSSSlot *
+NSSTrustDomain_FindSlotByName(
+ NSSTrustDomain *td,
+ NSSUTF8 *slotName);
+
+/*
+ * NSSTrustDomain_FindTokenByName
+ *
+ */
+
+NSS_EXTERN NSSToken *
+NSSTrustDomain_FindTokenByName(
+ NSSTrustDomain *td,
+ NSSUTF8 *tokenName);
+
+/*
+ * NSSTrustDomain_FindTokenBySlotName
+ *
+ */
+
+NSS_EXTERN NSSToken *
+NSSTrustDomain_FindTokenBySlotName(
+ NSSTrustDomain *td,
+ NSSUTF8 *slotName);
+
+/*
+ * NSSTrustDomain_FindBestTokenForAlgorithm
+ *
+ */
+
+NSS_EXTERN NSSToken *
+NSSTrustDomain_FindTokenForAlgorithm(
+ NSSTrustDomain *td,
+ NSSOID *algorithm);
+
+/*
+ * NSSTrustDomain_FindBestTokenForAlgorithms
+ *
+ */
+
+NSS_EXTERN NSSToken *
+NSSTrustDomain_FindBestTokenForAlgorithms(
+ NSSTrustDomain *td,
+ NSSOID *algorithms[], /* may be null-terminated */
+ PRUint32 nAlgorithmsOpt /* limits the array if nonzero */
+);
+
+/*
+ * NSSTrustDomain_Login
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSTrustDomain_Login(
+ NSSTrustDomain *td,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSTrustDomain_Logout
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSTrustDomain_Logout(NSSTrustDomain *td);
+
+/* Importing things */
+
+/*
+ * NSSTrustDomain_ImportCertificate
+ *
+ * The implementation will pull some data out of the certificate
+ * (e.g. e-mail address) for use in pkcs#11 object attributes.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_ImportCertificate(
+ NSSTrustDomain *td,
+ NSSCertificate *c);
+
+/*
+ * NSSTrustDomain_ImportPKIXCertificate
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_ImportPKIXCertificate(
+ NSSTrustDomain *td,
+ /* declared as a struct until these "data types" are defined */
+ struct NSSPKIXCertificateStr *pc);
+
+/*
+ * NSSTrustDomain_ImportEncodedCertificate
+ *
+ * Imports any type of certificate we support.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_ImportEncodedCertificate(
+ NSSTrustDomain *td,
+ NSSBER *ber);
+
+/*
+ * NSSTrustDomain_ImportEncodedCertificateChain
+ *
+ * If you just want the leaf, pass in a maximum of one.
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSTrustDomain_ImportEncodedCertificateChain(
+ NSSTrustDomain *td,
+ NSSBER *ber,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSTrustDomain_ImportEncodedPrivateKey
+ *
+ */
+
+NSS_EXTERN NSSPrivateKey *
+NSSTrustDomain_ImportEncodedPrivateKey(
+ NSSTrustDomain *td,
+ NSSBER *ber,
+ NSSItem *passwordOpt, /* NULL will cause a callback */
+ NSSCallback *uhhOpt,
+ NSSToken *destination);
+
+/*
+ * NSSTrustDomain_ImportEncodedPublicKey
+ *
+ */
+
+NSS_EXTERN NSSPublicKey *
+NSSTrustDomain_ImportEncodedPublicKey(
+ NSSTrustDomain *td,
+ NSSBER *ber);
+
+/* Other importations: S/MIME capabilities */
+
+/*
+ * NSSTrustDomain_FindBestCertificateByNickname
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindBestCertificateByNickname(
+ NSSTrustDomain *td,
+ const NSSUTF8 *name,
+ NSSTime *timeOpt, /* NULL for "now" */
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt /* NULL for none */
+);
+
+/*
+ * NSSTrustDomain_FindCertificatesByNickname
+ *
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSTrustDomain_FindCertificatesByNickname(
+ NSSTrustDomain *td,
+ NSSUTF8 *name,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSTrustDomain_FindCertificateByIssuerAndSerialNumber
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindCertificateByIssuerAndSerialNumber(
+ NSSTrustDomain *td,
+ NSSDER *issuer,
+ NSSDER *serialNumber);
+
+/*
+ * NSSTrustDomain_FindCertificatesByIssuerAndSerialNumber
+ *
+ * Theoretically, this should never happen. However, some companies
+ * we know have issued duplicate certificates with the same issuer
+ * and serial number. Do we just ignore them? I'm thinking yes.
+ */
+
+/*
+ * NSSTrustDomain_FindBestCertificateBySubject
+ *
+ * This does not search through alternate names hidden in extensions.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindBestCertificateBySubject(
+ NSSTrustDomain *td,
+ NSSDER /*NSSUTF8*/ *subject,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSTrustDomain_FindCertificatesBySubject
+ *
+ * This does not search through alternate names hidden in extensions.
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSTrustDomain_FindCertificatesBySubject(
+ NSSTrustDomain *td,
+ NSSDER /*NSSUTF8*/ *subject,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSTrustDomain_FindBestCertificateByNameComponents
+ *
+ * This call does try several tricks, including a pseudo pkcs#11
+ * attribute for the ldap module to try as a query. Eventually
+ * this call falls back to a traversal if that's what's required.
+ * It will search through alternate names hidden in extensions.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindBestCertificateByNameComponents(
+ NSSTrustDomain *td,
+ NSSUTF8 *nameComponents,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSTrustDomain_FindCertificatesByNameComponents
+ *
+ * This call, too, tries several tricks. It will stop on the first
+ * attempt that generates results, so it won't e.g. traverse the
+ * entire ldap database.
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSTrustDomain_FindCertificatesByNameComponents(
+ NSSTrustDomain *td,
+ NSSUTF8 *nameComponents,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSTrustDomain_FindCertificateByEncodedCertificate
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindCertificateByEncodedCertificate(
+ NSSTrustDomain *td,
+ NSSBER *encodedCertificate);
+
+/*
+ * NSSTrustDomain_FindBestCertificateByEmail
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindCertificateByEmail(
+ NSSTrustDomain *td,
+ NSSASCII7 *email,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSTrustDomain_FindCertificatesByEmail
+ *
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSTrustDomain_FindCertificatesByEmail(
+ NSSTrustDomain *td,
+ NSSASCII7 *email,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSTrustDomain_FindCertificateByOCSPHash
+ *
+ * There can be only one.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindCertificateByOCSPHash(
+ NSSTrustDomain *td,
+ NSSItem *hash);
+
+/*
+ * NSSTrustDomain_TraverseCertificates
+ *
+ * This function descends from one in older versions of NSS which
+ * traverses the certs in the permanent database. That function
+ * was used to implement selection routines, but was directly
+ * available too. Trust domains are going to contain a lot more
+ * certs now (e.g., an ldap server), so we'd really like to
+ * discourage traversal. Thus for now, this is commented out.
+ * If it's needed, let's look at the situation more closely to
+ * find out what the actual requirements are.
+ */
+
+/* For now, adding this function. This may only be for debugging
+ * purposes.
+ * Perhaps some equivalent function, on a specified token, will be
+ * needed in a "friend" header file?
+ */
+NSS_EXTERN PRStatus *
+NSSTrustDomain_TraverseCertificates(
+ NSSTrustDomain *td,
+ PRStatus (*callback)(NSSCertificate *c, void *arg),
+ void *arg);
+
+/*
+ * NSSTrustDomain_FindBestUserCertificate
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindBestUserCertificate(
+ NSSTrustDomain *td,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSTrustDomain_FindUserCertificates
+ *
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSTrustDomain_FindUserCertificates(
+ NSSTrustDomain *td,
+ NSSTime *timeOpt,
+ NSSUsage *usageOpt,
+ NSSPolicies *policiesOpt,
+ NSSCertificate **rvOpt,
+ PRUint32 rvLimit, /* zero for no limit */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSTrustDomain_FindBestUserCertificateForSSLClientAuth
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindBestUserCertificateForSSLClientAuth(
+ NSSTrustDomain *td,
+ NSSUTF8 *sslHostOpt,
+ NSSDER *rootCAsOpt[], /* null pointer for none */
+ PRUint32 rootCAsMaxOpt, /* zero means list is null-terminated */
+ NSSAlgorithmAndParameters *apOpt,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSTrustDomain_FindUserCertificatesForSSLClientAuth
+ *
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSTrustDomain_FindUserCertificatesForSSLClientAuth(
+ NSSTrustDomain *td,
+ NSSUTF8 *sslHostOpt,
+ NSSDER *rootCAsOpt[], /* null pointer for none */
+ PRUint32 rootCAsMaxOpt, /* zero means list is null-terminated */
+ NSSAlgorithmAndParameters *apOpt,
+ NSSPolicies *policiesOpt,
+ NSSCertificate **rvOpt,
+ PRUint32 rvLimit, /* zero for no limit */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSTrustDomain_FindBestUserCertificateForEmailSigning
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSTrustDomain_FindBestUserCertificateForEmailSigning(
+ NSSTrustDomain *td,
+ NSSASCII7 *signerOpt,
+ NSSASCII7 *recipientOpt,
+ /* anything more here? */
+ NSSAlgorithmAndParameters *apOpt,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSTrustDomain_FindUserCertificatesForEmailSigning
+ *
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSTrustDomain_FindUserCertificatesForEmailSigning(
+ NSSTrustDomain *td,
+ NSSASCII7 *signerOpt,
+ NSSASCII7 *recipientOpt,
+ /* anything more here? */
+ NSSAlgorithmAndParameters *apOpt,
+ NSSPolicies *policiesOpt,
+ NSSCertificate **rvOpt,
+ PRUint32 rvLimit, /* zero for no limit */
+ NSSArena *arenaOpt);
+
+/*
+ * Here is where we'd add more Find[Best]UserCertificate[s]For<usage>
+ * routines.
+ */
+
+/* Private Keys */
+
+/*
+ * NSSTrustDomain_GenerateKeyPair
+ *
+ * Creates persistant objects. If you want session objects, use
+ * NSSCryptoContext_GenerateKeyPair. The destination token is where
+ * the keys are stored. If that token can do the required math, then
+ * that's where the keys are generated too. Otherwise, the keys are
+ * generated elsewhere and moved to that token.
+ */
+
+NSS_EXTERN PRStatus
+NSSTrustDomain_GenerateKeyPair(
+ NSSTrustDomain *td,
+ NSSAlgorithmAndParameters *ap,
+ NSSPrivateKey **pvkOpt,
+ NSSPublicKey **pbkOpt,
+ PRBool privateKeyIsSensitive,
+ NSSToken *destination,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSTrustDomain_TraversePrivateKeys
+ *
+ *
+ * NSS_EXTERN PRStatus *
+ * NSSTrustDomain_TraversePrivateKeys
+ * (
+ * NSSTrustDomain *td,
+ * PRStatus (*callback)(NSSPrivateKey *vk, void *arg),
+ * void *arg
+ * );
+ */
+
+/* Symmetric Keys */
+
+/*
+ * NSSTrustDomain_GenerateSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSTrustDomain_GenerateSymmetricKey(
+ NSSTrustDomain *td,
+ NSSAlgorithmAndParameters *ap,
+ PRUint32 keysize,
+ NSSToken *destination,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSTrustDomain_GenerateSymmetricKeyFromPassword
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSTrustDomain_GenerateSymmetricKeyFromPassword(
+ NSSTrustDomain *td,
+ NSSAlgorithmAndParameters *ap,
+ NSSUTF8 *passwordOpt, /* if null, prompt */
+ NSSToken *destinationOpt,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSTrustDomain_FindSymmetricKeyByAlgorithm
+ *
+ * Is this still needed?
+ *
+ * NSS_EXTERN NSSSymmetricKey *
+ * NSSTrustDomain_FindSymmetricKeyByAlgorithm
+ * (
+ * NSSTrustDomain *td,
+ * NSSOID *algorithm,
+ * NSSCallback *uhhOpt
+ * );
+ */
+
+/*
+ * NSSTrustDomain_FindSymmetricKeyByAlgorithmAndKeyID
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSTrustDomain_FindSymmetricKeyByAlgorithmAndKeyID(
+ NSSTrustDomain *td,
+ NSSOID *algorithm,
+ NSSItem *keyID,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSTrustDomain_TraverseSymmetricKeys
+ *
+ *
+ * NSS_EXTERN PRStatus *
+ * NSSTrustDomain_TraverseSymmetricKeys
+ * (
+ * NSSTrustDomain *td,
+ * PRStatus (*callback)(NSSSymmetricKey *mk, void *arg),
+ * void *arg
+ * );
+ */
+
+/*
+ * NSSTrustDomain_CreateCryptoContext
+ *
+ * If a callback object is specified, it becomes the for the crypto
+ * context; otherwise, this trust domain's default (if any) is
+ * inherited.
+ */
+
+NSS_EXTERN NSSCryptoContext *
+NSSTrustDomain_CreateCryptoContext(
+ NSSTrustDomain *td,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSTrustDomain_CreateCryptoContextForAlgorithm
+ *
+ */
+
+NSS_EXTERN NSSCryptoContext *
+NSSTrustDomain_CreateCryptoContextForAlgorithm(
+ NSSTrustDomain *td,
+ NSSOID *algorithm);
+
+/*
+ * NSSTrustDomain_CreateCryptoContextForAlgorithmAndParameters
+ *
+ */
+
+NSS_EXTERN NSSCryptoContext *
+NSSTrustDomain_CreateCryptoContextForAlgorithmAndParameters(
+ NSSTrustDomain *td,
+ NSSAlgorithmAndParameters *ap);
+
+/* find/traverse other objects, e.g. s/mime profiles */
+
+/*
+ * NSSCryptoContext
+ *
+ * A crypto context is sort of a short-term snapshot of a trust domain,
+ * used for the life of "one crypto operation." You can also think of
+ * it as a "temporary database."
+ *
+ * Just about all of the things you can do with a trust domain -- importing
+ * or creating certs, keys, etc. -- can be done with a crypto context.
+ * The difference is that the objects will be temporary ("session") objects.
+ *
+ * Also, if the context was created for a key, cert, and/or algorithm; or
+ * if such objects have been "associated" with the context, then the context
+ * can do everything the keys can, like crypto operations.
+ *
+ * And finally, because it keeps the state of the crypto operations, it
+ * can do streaming crypto ops.
+ */
+
+/*
+ * NSSTrustDomain_Destroy
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_Destroy(NSSCryptoContext *cc);
+
+/* establishing a default callback */
+
+/*
+ * NSSCryptoContext_SetDefaultCallback
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_SetDefaultCallback(
+ NSSCryptoContext *cc,
+ NSSCallback *newCallback,
+ NSSCallback **oldCallbackOpt);
+
+/*
+ * NSSCryptoContext_GetDefaultCallback
+ *
+ */
+
+NSS_EXTERN NSSCallback *
+NSSCryptoContext_GetDefaultCallback(
+ NSSCryptoContext *cc,
+ PRStatus *statusOpt);
+
+/*
+ * NSSCryptoContext_GetTrustDomain
+ *
+ */
+
+NSS_EXTERN NSSTrustDomain *
+NSSCryptoContext_GetTrustDomain(
+ NSSCryptoContext *cc);
+
+/* AddModule, etc: should we allow "temporary" changes here? */
+/* DisableToken, etc: ditto */
+/* Ordering of tokens? */
+/* Finding slots+token etc. */
+/* login+logout */
+
+/* Importing things */
+
+/*
+ * NSSCryptoContext_FindOrImportCertificate
+ *
+ * If the certificate store already contains this DER cert, return the
+ * address of the matching NSSCertificate that is already in the store,
+ * and bump its reference count.
+ *
+ * If this DER cert is NOT already in the store, then add the new
+ * NSSCertificate to the store and bump its reference count,
+ * then return its address.
+ *
+ * if this DER cert is not in the store and cannot be added to it,
+ * return NULL;
+ *
+ * Record the associated crypto context in the certificate.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindOrImportCertificate(
+ NSSCryptoContext *cc,
+ NSSCertificate *c);
+
+/*
+ * NSSCryptoContext_ImportPKIXCertificate
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_ImportPKIXCertificate(
+ NSSCryptoContext *cc,
+ struct NSSPKIXCertificateStr *pc);
+
+/*
+ * NSSCryptoContext_ImportEncodedCertificate
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_ImportEncodedCertificate(
+ NSSCryptoContext *cc,
+ NSSBER *ber);
+
+/*
+ * NSSCryptoContext_ImportEncodedPKIXCertificateChain
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_ImportEncodedPKIXCertificateChain(
+ NSSCryptoContext *cc,
+ NSSBER *ber);
+
+/* Other importations: S/MIME capabilities
+ */
+
+/*
+ * NSSCryptoContext_FindBestCertificateByNickname
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindBestCertificateByNickname(
+ NSSCryptoContext *cc,
+ const NSSUTF8 *name,
+ NSSTime *timeOpt, /* NULL for "now" */
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt /* NULL for none */
+);
+
+/*
+ * NSSCryptoContext_FindCertificatesByNickname
+ *
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSCryptoContext_FindCertificatesByNickname(
+ NSSCryptoContext *cc,
+ NSSUTF8 *name,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FindCertificateByIssuerAndSerialNumber
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindCertificateByIssuerAndSerialNumber(
+ NSSCryptoContext *cc,
+ NSSDER *issuer,
+ NSSDER *serialNumber);
+
+/*
+ * NSSCryptoContext_FindBestCertificateBySubject
+ *
+ * This does not search through alternate names hidden in extensions.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindBestCertificateBySubject(
+ NSSCryptoContext *cc,
+ NSSDER /*NSSUTF8*/ *subject,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSCryptoContext_FindCertificatesBySubject
+ *
+ * This does not search through alternate names hidden in extensions.
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSCryptoContext_FindCertificatesBySubject(
+ NSSCryptoContext *cc,
+ NSSDER /*NSSUTF8*/ *subject,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FindBestCertificateByNameComponents
+ *
+ * This call does try several tricks, including a pseudo pkcs#11
+ * attribute for the ldap module to try as a query. Eventually
+ * this call falls back to a traversal if that's what's required.
+ * It will search through alternate names hidden in extensions.
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindBestCertificateByNameComponents(
+ NSSCryptoContext *cc,
+ NSSUTF8 *nameComponents,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSCryptoContext_FindCertificatesByNameComponents
+ *
+ * This call, too, tries several tricks. It will stop on the first
+ * attempt that generates results, so it won't e.g. traverse the
+ * entire ldap database.
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSCryptoContext_FindCertificatesByNameComponents(
+ NSSCryptoContext *cc,
+ NSSUTF8 *nameComponents,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FindCertificateByEncodedCertificate
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindCertificateByEncodedCertificate(
+ NSSCryptoContext *cc,
+ NSSBER *encodedCertificate);
+
+/*
+ * NSSCryptoContext_FindBestCertificateByEmail
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindBestCertificateByEmail(
+ NSSCryptoContext *cc,
+ NSSASCII7 *email,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSCryptoContext_FindCertificatesByEmail
+ *
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSCryptoContext_FindCertificatesByEmail(
+ NSSCryptoContext *cc,
+ NSSASCII7 *email,
+ NSSCertificate *rvOpt[],
+ PRUint32 maximumOpt, /* 0 for no max */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FindCertificateByOCSPHash
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindCertificateByOCSPHash(
+ NSSCryptoContext *cc,
+ NSSItem *hash);
+
+/*
+ * NSSCryptoContext_TraverseCertificates
+ *
+ *
+ * NSS_EXTERN PRStatus *
+ * NSSCryptoContext_TraverseCertificates
+ * (
+ * NSSCryptoContext *cc,
+ * PRStatus (*callback)(NSSCertificate *c, void *arg),
+ * void *arg
+ * );
+ */
+
+/*
+ * NSSCryptoContext_FindBestUserCertificate
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindBestUserCertificate(
+ NSSCryptoContext *cc,
+ NSSTime *timeOpt,
+ NSSUsage *usage,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSCryptoContext_FindUserCertificates
+ *
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSCryptoContext_FindUserCertificates(
+ NSSCryptoContext *cc,
+ NSSTime *timeOpt,
+ NSSUsage *usageOpt,
+ NSSPolicies *policiesOpt,
+ NSSCertificate **rvOpt,
+ PRUint32 rvLimit, /* zero for no limit */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FindBestUserCertificateForSSLClientAuth
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindBestUserCertificateForSSLClientAuth(
+ NSSCryptoContext *cc,
+ NSSUTF8 *sslHostOpt,
+ NSSDER *rootCAsOpt[], /* null pointer for none */
+ PRUint32 rootCAsMaxOpt, /* zero means list is null-terminated */
+ NSSAlgorithmAndParameters *apOpt,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSCryptoContext_FindUserCertificatesForSSLClientAuth
+ *
+ */
+
+NSS_EXTERN NSSCertificate **
+NSSCryptoContext_FindUserCertificatesForSSLClientAuth(
+ NSSCryptoContext *cc,
+ NSSUTF8 *sslHostOpt,
+ NSSDER *rootCAsOpt[], /* null pointer for none */
+ PRUint32 rootCAsMaxOpt, /* zero means list is null-terminated */
+ NSSAlgorithmAndParameters *apOpt,
+ NSSPolicies *policiesOpt,
+ NSSCertificate **rvOpt,
+ PRUint32 rvLimit, /* zero for no limit */
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FindBestUserCertificateForEmailSigning
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindBestUserCertificateForEmailSigning(
+ NSSCryptoContext *cc,
+ NSSASCII7 *signerOpt,
+ NSSASCII7 *recipientOpt,
+ /* anything more here? */
+ NSSAlgorithmAndParameters *apOpt,
+ NSSPolicies *policiesOpt);
+
+/*
+ * NSSCryptoContext_FindUserCertificatesForEmailSigning
+ *
+ */
+
+NSS_EXTERN NSSCertificate *
+NSSCryptoContext_FindUserCertificatesForEmailSigning(
+ NSSCryptoContext *cc,
+ NSSASCII7 *signerOpt, /* fgmr or a more general name? */
+ NSSASCII7 *recipientOpt,
+ /* anything more here? */
+ NSSAlgorithmAndParameters *apOpt,
+ NSSPolicies *policiesOpt,
+ NSSCertificate **rvOpt,
+ PRUint32 rvLimit, /* zero for no limit */
+ NSSArena *arenaOpt);
+
+/* Private Keys */
+
+/*
+ * NSSCryptoContext_GenerateKeyPair
+ *
+ * Creates session objects. If you want persistant objects, use
+ * NSSTrustDomain_GenerateKeyPair. The destination token is where
+ * the keys are stored. If that token can do the required math, then
+ * that's where the keys are generated too. Otherwise, the keys are
+ * generated elsewhere and moved to that token.
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_GenerateKeyPair(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *ap,
+ NSSPrivateKey **pvkOpt,
+ NSSPublicKey **pbkOpt,
+ PRBool privateKeyIsSensitive,
+ NSSToken *destination,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_TraversePrivateKeys
+ *
+ *
+ * NSS_EXTERN PRStatus *
+ * NSSCryptoContext_TraversePrivateKeys
+ * (
+ * NSSCryptoContext *cc,
+ * PRStatus (*callback)(NSSPrivateKey *vk, void *arg),
+ * void *arg
+ * );
+ */
+
+/* Symmetric Keys */
+
+/*
+ * NSSCryptoContext_GenerateSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSCryptoContext_GenerateSymmetricKey(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *ap,
+ PRUint32 keysize,
+ NSSToken *destination,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_GenerateSymmetricKeyFromPassword
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSCryptoContext_GenerateSymmetricKeyFromPassword(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *ap,
+ NSSUTF8 *passwordOpt, /* if null, prompt */
+ NSSToken *destinationOpt,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_FindSymmetricKeyByAlgorithm
+ *
+ *
+ * NSS_EXTERN NSSSymmetricKey *
+ * NSSCryptoContext_FindSymmetricKeyByType
+ * (
+ * NSSCryptoContext *cc,
+ * NSSOID *type,
+ * NSSCallback *uhhOpt
+ * );
+ */
+
+/*
+ * NSSCryptoContext_FindSymmetricKeyByAlgorithmAndKeyID
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSCryptoContext_FindSymmetricKeyByAlgorithmAndKeyID(
+ NSSCryptoContext *cc,
+ NSSOID *algorithm,
+ NSSItem *keyID,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_TraverseSymmetricKeys
+ *
+ *
+ * NSS_EXTERN PRStatus *
+ * NSSCryptoContext_TraverseSymmetricKeys
+ * (
+ * NSSCryptoContext *cc,
+ * PRStatus (*callback)(NSSSymmetricKey *mk, void *arg),
+ * void *arg
+ * );
+ */
+
+/* Crypto ops on distinguished keys */
+
+/*
+ * NSSCryptoContext_Decrypt
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_Decrypt(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *encryptedData,
+ NSSCallback *uhhOpt,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_BeginDecrypt
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_BeginDecrypt(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_ContinueDecrypt
+ *
+ */
+
+/*
+ * NSSItem semantics:
+ *
+ * If rvOpt is NULL, a new NSSItem and buffer are allocated.
+ * If rvOpt is not null, but the buffer pointer is null,
+ * then rvOpt is returned but a new buffer is allocated.
+ * In this case, if the length value is not zero, then
+ * no more than that much space will be allocated.
+ * If rvOpt is not null and the buffer pointer is not null,
+ * then that buffer is re-used. No more than the buffer
+ * length value will be used; if it's not enough, an
+ * error is returned. If less is used, the number is
+ * adjusted downwards.
+ *
+ * Note that although this is short of some ideal "Item"
+ * definition, we can usually tell how big these buffers
+ * have to be.
+ *
+ * Feedback is requested; and earlier is better than later.
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_ContinueDecrypt(
+ NSSCryptoContext *cc,
+ NSSItem *data,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FinishDecrypt
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_FinishDecrypt(
+ NSSCryptoContext *cc,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_Sign
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_Sign(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhhOpt,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_BeginSign
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_BeginSign(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_ContinueSign
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_ContinueSign(
+ NSSCryptoContext *cc,
+ NSSItem *data);
+
+/*
+ * NSSCryptoContext_FinishSign
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_FinishSign(
+ NSSCryptoContext *cc,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_SignRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_SignRecover(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhhOpt,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_BeginSignRecover
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_BeginSignRecover(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_ContinueSignRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_ContinueSignRecover(
+ NSSCryptoContext *cc,
+ NSSItem *data,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FinishSignRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_FinishSignRecover(
+ NSSCryptoContext *cc,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_UnwrapSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSCryptoContext_UnwrapSymmetricKey(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *wrappedKey,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_DeriveSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSSymmetricKey *
+NSSCryptoContext_DeriveSymmetricKey(
+ NSSCryptoContext *cc,
+ NSSPublicKey *bk,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSOID *target,
+ PRUint32 keySizeOpt, /* zero for best allowed */
+ NSSOperations operations,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_Encrypt
+ *
+ * Encrypt a single chunk of data with the distinguished public key
+ * of this crypto context.
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_Encrypt(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhhOpt,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_BeginEncrypt
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_BeginEncrypt(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_ContinueEncrypt
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_ContinueEncrypt(
+ NSSCryptoContext *cc,
+ NSSItem *data,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FinishEncrypt
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_FinishEncrypt(
+ NSSCryptoContext *cc,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_Verify
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_Verify(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSItem *signature,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_BeginVerify
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_BeginVerify(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *signature,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_ContinueVerify
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_ContinueVerify(
+ NSSCryptoContext *cc,
+ NSSItem *data);
+
+/*
+ * NSSCryptoContext_FinishVerify
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_FinishVerify(
+ NSSCryptoContext *cc);
+
+/*
+ * NSSCryptoContext_VerifyRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_VerifyRecover(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *signature,
+ NSSCallback *uhhOpt,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_BeginVerifyRecover
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_BeginVerifyRecover(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_ContinueVerifyRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_ContinueVerifyRecover(
+ NSSCryptoContext *cc,
+ NSSItem *data,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_FinishVerifyRecover
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_FinishVerifyRecover(
+ NSSCryptoContext *cc,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_WrapSymmetricKey
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_WrapSymmetricKey(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSSymmetricKey *keyToWrap,
+ NSSCallback *uhhOpt,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_Digest
+ *
+ * Digest a single chunk of data with the distinguished digest key
+ * of this crypto context.
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_Digest(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *data,
+ NSSCallback *uhhOpt,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * NSSCryptoContext_BeginDigest
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_BeginDigest(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSCallback *uhhOpt);
+
+/*
+ * NSSCryptoContext_ContinueDigest
+ *
+ */
+
+NSS_EXTERN PRStatus
+NSSCryptoContext_ContinueDigest(
+ NSSCryptoContext *cc,
+ NSSAlgorithmAndParameters *apOpt,
+ NSSItem *item);
+
+/*
+ * NSSCryptoContext_FinishDigest
+ *
+ */
+
+NSS_EXTERN NSSItem *
+NSSCryptoContext_FinishDigest(
+ NSSCryptoContext *cc,
+ NSSItem *rvOpt,
+ NSSArena *arenaOpt);
+
+/*
+ * tbd: Combination ops
+ */
+
+/*
+ * NSSCryptoContext_Clone
+ *
+ */
+
+NSS_EXTERN NSSCryptoContext *
+NSSCryptoContext_Clone(NSSCryptoContext *cc);
+
+/*
+ * NSSCryptoContext_Save
+ * NSSCryptoContext_Restore
+ *
+ * We need to be able to save and restore the state of contexts.
+ * Perhaps a mark-and-release mechanism would be better?
+ */
+
+/*
+ * ..._SignTBSCertificate
+ *
+ * This requires feedback from the cert server team.
+ */
+
+/*
+ * PRBool NSSCertificate_GetIsTrustedFor{xxx}(NSSCertificate *c);
+ * PRStatus NSSCertificate_SetIsTrustedFor{xxx}(NSSCertificate *c, PRBool trusted);
+ *
+ * These will be helper functions which get the trust object for a cert,
+ * and then call the corresponding function(s) on it.
+ *
+ * PKIX trust objects will have methods to manipulate the low-level trust
+ * bits (which are based on key usage and extended key usage), and also the
+ * conceptual high-level usages (e.g. ssl client auth, email encryption, etc.)
+ *
+ * Other types of trust objects (if any) might have different low-level
+ * representations, but hopefully high-level concepts would map.
+ *
+ * Only these high-level general routines would be promoted to the
+ * general certificate level here. Hence the {xxx} above would be things
+ * like "EmailSigning."
+ *
+ *
+ * NSSPKIXTrust *NSSCertificate_GetPKIXTrustObject(NSSCertificate *c);
+ * PRStatus NSSCertificate_SetPKIXTrustObject(NSSCertificate *c, NSPKIXTrust *t);
+ *
+ * I want to hold off on any general trust object until we've investigated
+ * other models more thoroughly.
+ */
+
+PR_END_EXTERN_C
+
+#endif /* NSSPKI_H */