/* 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 */