--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/nss/lib/pki/nsspki.h	Mon Jul 28 10:47:06 2014 +0200
@@ -0,0 +1,3164 @@
+/* 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 */
+
+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_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 */