path: root/security/nss/lib/pki/pkim.h

/* 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 PKIM_H
#define PKIM_H

#ifndef BASE_H
#include "base.h"
#endif /* BASE_H */

#ifndef PKI_H
#include "pki.h"
#endif /* PKI_H */

#ifndef PKITM_H
#include "pkitm.h"
#endif /* PKITM_H */

PR_BEGIN_EXTERN_C

/* nssPKIObject
 *
 * This is the base object class, common to all PKI objects defined in
 * in this module.  Each object can be safely 'casted' to an nssPKIObject,
 * then passed to these methods.
 *
 * nssPKIObject_Create
 * nssPKIObject_Destroy
 * nssPKIObject_AddRef
 * nssPKIObject_AddInstance
 * nssPKIObject_HasInstance
 * nssPKIObject_GetTokens
 * nssPKIObject_GetNicknameForToken
 * nssPKIObject_RemoveInstanceForToken
 * nssPKIObject_DeleteStoredObject
 */

NSS_EXTERN void nssPKIObject_Lock(nssPKIObject *object);
NSS_EXTERN void nssPKIObject_Unlock(nssPKIObject *object);
NSS_EXTERN PRStatus nssPKIObject_NewLock(nssPKIObject *object,
                                         nssPKILockType lockType);
NSS_EXTERN void nssPKIObject_DestroyLock(nssPKIObject *object);

/* nssPKIObject_Create
 *
 * A generic PKI object.  It must live in a trust domain.  It may be
 * initialized with a token instance, or alternatively in a crypto context.
 */
NSS_EXTERN nssPKIObject *
nssPKIObject_Create(
    NSSArena *arenaOpt,
    nssCryptokiObject *instanceOpt,
    NSSTrustDomain *td,
    NSSCryptoContext *ccOpt,
    nssPKILockType lockType);

/* nssPKIObject_AddRef
 */
NSS_EXTERN nssPKIObject *
nssPKIObject_AddRef(nssPKIObject *object);

/* nssPKIObject_Destroy
 *
 * Returns true if object was destroyed.  This notifies the subclass that
 * all references are gone and it should delete any members it owns.
 */
NSS_EXTERN PRBool
nssPKIObject_Destroy(nssPKIObject *object);

/* nssPKIObject_AddInstance
 *
 * Add a token instance to the object, if it does not have it already.
 */
NSS_EXTERN PRStatus
nssPKIObject_AddInstance(
    nssPKIObject *object,
    nssCryptokiObject *instance);

/* nssPKIObject_HasInstance
 *
 * Query the object for a token instance.
 */
NSS_EXTERN PRBool
nssPKIObject_HasInstance(
    nssPKIObject *object,
    nssCryptokiObject *instance);

/* nssPKIObject_GetTokens
 *
 * Get all tokens which have an instance of the object.
 */
NSS_EXTERN NSSToken **
nssPKIObject_GetTokens(
    nssPKIObject *object,
    PRStatus *statusOpt);

/* nssPKIObject_GetNicknameForToken
 *
 * tokenOpt == NULL means take the first available, otherwise return the
 * nickname for the specified token.
 */
NSS_EXTERN NSSUTF8 *
nssPKIObject_GetNicknameForToken(
    nssPKIObject *object,
    NSSToken *tokenOpt);

/* nssPKIObject_RemoveInstanceForToken
 *
 * Remove the instance of the object on the specified token.
 */
NSS_EXTERN PRStatus
nssPKIObject_RemoveInstanceForToken(
    nssPKIObject *object,
    NSSToken *token);

/* nssPKIObject_DeleteStoredObject
 *
 * Delete all token instances of the object, as well as any crypto context
 * instances (TODO).  If any of the instances are read-only, or if the
 * removal fails, the object will keep those instances.  'isFriendly' refers
 * to the object -- can this object be removed from a friendly token without
 * login?  For example, certificates are friendly, private keys are not.
 * Note that if the token is not friendly, authentication will be required
 * regardless of the value of 'isFriendly'.
 */
NSS_EXTERN PRStatus
nssPKIObject_DeleteStoredObject(
    nssPKIObject *object,
    NSSCallback *uhh,
    PRBool isFriendly);

NSS_EXTERN nssCryptokiObject **
nssPKIObject_GetInstances(
    nssPKIObject *object);

NSS_EXTERN NSSCertificate **
nssTrustDomain_FindCertificatesByID(
    NSSTrustDomain *td,
    NSSItem *id,
    NSSCertificate **rvOpt,
    PRUint32 maximumOpt,
    NSSArena *arenaOpt);

NSS_EXTERN NSSCRL **
nssTrustDomain_FindCRLsBySubject(
    NSSTrustDomain *td,
    NSSDER *subject);

/* module-private nsspki methods */

NSS_EXTERN NSSCryptoContext *
nssCryptoContext_Create(
    NSSTrustDomain *td,
    NSSCallback *uhhOpt);

/* XXX for the collection */
NSS_EXTERN NSSCertificate *
nssCertificate_Create(nssPKIObject *object);

NSS_EXTERN PRStatus
nssCertificate_SetCertTrust(
    NSSCertificate *c,
    NSSTrust *trust);

NSS_EXTERN nssDecodedCert *
nssCertificate_GetDecoding(NSSCertificate *c);

extern PRIntn
nssCertificate_SubjectListSort(
    void *v1,
    void *v2);

NSS_EXTERN nssDecodedCert *
nssDecodedCert_Create(
    NSSArena *arenaOpt,
    NSSDER *encoding,
    NSSCertificateType type);

NSS_EXTERN PRStatus
nssDecodedCert_Destroy(nssDecodedCert *dc);

NSS_EXTERN NSSTrust *
nssTrust_Create(
    nssPKIObject *object,
    NSSItem *certData);

NSS_EXTERN NSSCRL *
nssCRL_Create(nssPKIObject *object);

NSS_EXTERN NSSCRL *
nssCRL_AddRef(NSSCRL *crl);

NSS_EXTERN PRStatus
nssCRL_Destroy(NSSCRL *crl);

NSS_EXTERN PRStatus
nssCRL_DeleteStoredObject(
    NSSCRL *crl,
    NSSCallback *uhh);

NSS_EXTERN NSSPrivateKey *
nssPrivateKey_Create(nssPKIObject *o);

NSS_EXTERN NSSDER *
nssCRL_GetEncoding(NSSCRL *crl);

NSS_EXTERN NSSPublicKey *
nssPublicKey_Create(nssPKIObject *object);

/* nssCertificateArray
 *
 * These are being thrown around a lot, might as well group together some
 * functionality.
 *
 * nssCertificateArray_Destroy
 * nssCertificateArray_Join
 * nssCertificateArray_FindBestCertificate
 * nssCertificateArray_Traverse
 */

/* nssCertificateArray_Destroy
 *
 * Will destroy the array and the certs within it.  If the array was created
 * in an arena, will *not* (of course) destroy the arena.  However, is safe
 * to call this method on an arena-allocated array.
 */
NSS_EXTERN void
nssCertificateArray_Destroy(NSSCertificate **certs);

/* nssCertificateArray_Join
 *
 * Join two arrays into one.  The two arrays, certs1 and certs2, should
 * be considered invalid after a call to this function (they may be destroyed
 * as part of the join).  certs1 and/or certs2 may be NULL.  Safe to
 * call with arrays allocated in an arena, the result will also be in the
 * arena.
 */
NSS_EXTERN NSSCertificate **
nssCertificateArray_Join(
    NSSCertificate **certs1,
    NSSCertificate **certs2);

/* nssCertificateArray_FindBestCertificate
 *
 * Use the usual { time, usage, policies } to find the best cert in the
 * array.
 */
NSS_EXTERN NSSCertificate *
nssCertificateArray_FindBestCertificate(
    NSSCertificate **certs,
    NSSTime *timeOpt,
    const NSSUsage *usage,
    NSSPolicies *policiesOpt);

/* nssCertificateArray_Traverse
 *
 * Do the callback for each cert, terminate the traversal if the callback
 * fails.
 */
NSS_EXTERN PRStatus
nssCertificateArray_Traverse(
    NSSCertificate **certs,
    PRStatus (*callback)(NSSCertificate *c, void *arg),
    void *arg);

NSS_EXTERN void
nssCRLArray_Destroy(NSSCRL **crls);

/* nssPKIObjectCollection
 *
 * This is a handy way to group objects together and perform operations
 * on them.  It can also handle "proto-objects"-- references to
 * objects instances on tokens, where the actual object hasn't
 * been formed yet.
 *
 * nssCertificateCollection_Create
 * nssPrivateKeyCollection_Create
 * nssPublicKeyCollection_Create
 *
 * If this was a language that provided for inheritance, each type would
 * inherit all of the following methods.  Instead, there is only one
 * type (nssPKIObjectCollection), shared among all.  This may cause
 * confusion; an alternative would be to define all of the methods
 * for each subtype (nssCertificateCollection_Destroy, ...), but that doesn't
 * seem worth the code bloat..  It is left up to the caller to remember
 * what type of collection he/she is dealing with.
 *
 * nssPKIObjectCollection_Destroy
 * nssPKIObjectCollection_Count
 * nssPKIObjectCollection_AddObject
 * nssPKIObjectCollection_AddInstances
 * nssPKIObjectCollection_Traverse
 *
 * Back to type-specific methods.
 *
 * nssPKIObjectCollection_GetCertificates
 * nssPKIObjectCollection_GetCRLs
 * nssPKIObjectCollection_GetPrivateKeys
 * nssPKIObjectCollection_GetPublicKeys
 */

/* nssCertificateCollection_Create
 *
 * Create a collection of certificates in the specified trust domain.
 * Optionally provide a starting set of certs.
 */
NSS_EXTERN nssPKIObjectCollection *
nssCertificateCollection_Create(
    NSSTrustDomain *td,
    NSSCertificate **certsOpt);

/* nssCRLCollection_Create
 *
 * Create a collection of CRLs/KRLs in the specified trust domain.
 * Optionally provide a starting set of CRLs.
 */
NSS_EXTERN nssPKIObjectCollection *
nssCRLCollection_Create(
    NSSTrustDomain *td,
    NSSCRL **crlsOpt);

/* nssPrivateKeyCollection_Create
 *
 * Create a collection of private keys in the specified trust domain.
 * Optionally provide a starting set of keys.
 */
NSS_EXTERN nssPKIObjectCollection *
nssPrivateKeyCollection_Create(
    NSSTrustDomain *td,
    NSSPrivateKey **pvkOpt);

/* nssPublicKeyCollection_Create
 *
 * Create a collection of public keys in the specified trust domain.
 * Optionally provide a starting set of keys.
 */
NSS_EXTERN nssPKIObjectCollection *
nssPublicKeyCollection_Create(
    NSSTrustDomain *td,
    NSSPublicKey **pvkOpt);

/* nssPKIObjectCollection_Destroy
 */
NSS_EXTERN void
nssPKIObjectCollection_Destroy(nssPKIObjectCollection *collection);

/* nssPKIObjectCollection_Count
 */
NSS_EXTERN PRUint32
nssPKIObjectCollection_Count(nssPKIObjectCollection *collection);

NSS_EXTERN PRStatus
nssPKIObjectCollection_AddObject(
    nssPKIObjectCollection *collection,
    nssPKIObject *object);

/* nssPKIObjectCollection_AddInstances
 *
 * Add a set of object instances to the collection.  The instances
 * will be sorted into any existing certs/proto-certs that may be in
 * the collection.  The instances will be absorbed by the collection,
 * the array should not be used after this call (except to free it).
 *
 * Failure means the collection is in an invalid state.
 *
 * numInstances = 0 means the array is NULL-terminated
 */
NSS_EXTERN PRStatus
nssPKIObjectCollection_AddInstances(
    nssPKIObjectCollection *collection,
    nssCryptokiObject **instances,
    PRUint32 numInstances);

/* nssPKIObjectCollection_Traverse
 */
NSS_EXTERN PRStatus
nssPKIObjectCollection_Traverse(
    nssPKIObjectCollection *collection,
    nssPKIObjectCallback *callback);

/* This function is being added for NSS 3.5.  It corresponds to the function
 * nssToken_TraverseCertificates.  The idea is to use the collection during
 * a traversal, creating certs each time a new instance is added for which
 * a cert does not already exist.
 */
NSS_EXTERN PRStatus
nssPKIObjectCollection_AddInstanceAsObject(
    nssPKIObjectCollection *collection,
    nssCryptokiObject *instance);

/* nssPKIObjectCollection_GetCertificates
 *
 * Get all of the certificates in the collection.
 */
NSS_EXTERN NSSCertificate **
nssPKIObjectCollection_GetCertificates(
    nssPKIObjectCollection *collection,
    NSSCertificate **rvOpt,
    PRUint32 maximumOpt,
    NSSArena *arenaOpt);

NSS_EXTERN NSSCRL **
nssPKIObjectCollection_GetCRLs(
    nssPKIObjectCollection *collection,
    NSSCRL **rvOpt,
    PRUint32 maximumOpt,
    NSSArena *arenaOpt);

NSS_EXTERN NSSPrivateKey **
nssPKIObjectCollection_GetPrivateKeys(
    nssPKIObjectCollection *collection,
    NSSPrivateKey **rvOpt,
    PRUint32 maximumOpt,
    NSSArena *arenaOpt);

NSS_EXTERN NSSPublicKey **
nssPKIObjectCollection_GetPublicKeys(
    nssPKIObjectCollection *collection,
    NSSPublicKey **rvOpt,
    PRUint32 maximumOpt,
    NSSArena *arenaOpt);

NSS_EXTERN NSSTime *
NSSTime_Now(NSSTime *timeOpt);

NSS_EXTERN NSSTime *
NSSTime_SetPRTime(
    NSSTime *timeOpt,
    PRTime prTime);

NSS_EXTERN PRTime
NSSTime_GetPRTime(
    NSSTime *time);

NSS_EXTERN nssHash *
nssHash_CreateCertificate(
    NSSArena *arenaOpt,
    PRUint32 numBuckets);

/* 3.4 Certificate cache routines */

NSS_EXTERN PRStatus
nssTrustDomain_InitializeCache(
    NSSTrustDomain *td,
    PRUint32 cacheSize);

NSS_EXTERN PRStatus
nssTrustDomain_AddCertsToCache(
    NSSTrustDomain *td,
    NSSCertificate **certs,
    PRUint32 numCerts);

NSS_EXTERN void
nssTrustDomain_RemoveCertFromCacheLOCKED(
    NSSTrustDomain *td,
    NSSCertificate *cert);

NSS_EXTERN void
nssTrustDomain_LockCertCache(NSSTrustDomain *td);

NSS_EXTERN void
nssTrustDomain_UnlockCertCache(NSSTrustDomain *td);

NSS_IMPLEMENT PRStatus
nssTrustDomain_DestroyCache(NSSTrustDomain *td);

/*
 * Remove all certs for the given token from the cache.  This is
 * needed if the token is removed.
 */
NSS_EXTERN PRStatus
nssTrustDomain_RemoveTokenCertsFromCache(
    NSSTrustDomain *td,
    NSSToken *token);

NSS_EXTERN PRStatus
nssTrustDomain_UpdateCachedTokenCerts(
    NSSTrustDomain *td,
    NSSToken *token);

/*
 * Find all cached certs with this nickname (label).
 */
NSS_EXTERN NSSCertificate **
nssTrustDomain_GetCertsForNicknameFromCache(
    NSSTrustDomain *td,
    const NSSUTF8 *nickname,
    nssList *certListOpt);

/*
 * Find all cached certs with this email address.
 */
NSS_EXTERN NSSCertificate **
nssTrustDomain_GetCertsForEmailAddressFromCache(
    NSSTrustDomain *td,
    NSSASCII7 *email,
    nssList *certListOpt);

/*
 * Find all cached certs with this subject.
 */
NSS_EXTERN NSSCertificate **
nssTrustDomain_GetCertsForSubjectFromCache(
    NSSTrustDomain *td,
    NSSDER *subject,
    nssList *certListOpt);

/*
 * Look for a specific cert in the cache.
 */
NSS_EXTERN NSSCertificate *
nssTrustDomain_GetCertForIssuerAndSNFromCache(
    NSSTrustDomain *td,
    NSSDER *issuer,
    NSSDER *serialNum);

/*
 * Look for a specific cert in the cache.
 */
NSS_EXTERN NSSCertificate *
nssTrustDomain_GetCertByDERFromCache(
    NSSTrustDomain *td,
    NSSDER *der);

/* Get all certs from the cache */
/* XXX this is being included to make some old-style calls word, not to
 *     say we should keep it
 */
NSS_EXTERN NSSCertificate **
nssTrustDomain_GetCertsFromCache(
    NSSTrustDomain *td,
    nssList *certListOpt);

NSS_EXTERN void
nssTrustDomain_DumpCacheInfo(
    NSSTrustDomain *td,
    void (*cert_dump_iter)(const void *, void *, void *),
    void *arg);

NSS_EXTERN void
nssCertificateList_AddReferences(
    nssList *certList);

PR_END_EXTERN_C

#endif /* PKIM_H */