The Tor Browser / file revision

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

 #define NSSPKIT_H

 /*

  * nsspkit.h

  *

  * This file defines the types of the top-level PKI objects.

  */

 #ifndef NSSBASET_H

 #include "nssbaset.h"

 #endif /* NSSBASET_H */

 PR_BEGIN_EXTERN_C

 /*

  * NSSCertificate

  *

  * This is the public representation of a Certificate.  The certificate

  * may be one found on a smartcard or other token, one decoded from data

  * received as part of a protocol, one constructed from constituent

  * parts, etc.  Usually it is associated with ("in") a trust domain; as

  * it can be verified only within a trust domain.  The underlying type

  * of certificate may be of any supported standard, e.g. PKIX, PGP, etc.

  *

  * People speak of "verifying (with) the server's, or correspondant's, 

  * certificate"; for simple operations we support that simplification

  * by implementing public-key crypto operations as methods on this type.

  */

 struct NSSCertificateStr;

 typedef struct NSSCertificateStr NSSCertificate;

 /*

  * NSSUserCertificate

  *

  * A ``User'' certificate is one for which the private key is available.

  * People speak of "using my certificate to sign my email" and "using

  * my certificate to authenticate to (or login to) the server"; for

  * simple operations, we support that simplification by implementing

  * private-key crypto operations as methods on this type.

  *

  * The current design only weakly distinguishes between certificates

  * and user certificates: as far as the compiler goes they're 

  * interchangeable; debug libraries only have one common pointer-tracker;

  * etc.  However, attempts to do private-key operations on a certificate

  * for which the private key is not available will fail.

  *

  * Open design question: should these types be more firmly separated?

  */

 typedef NSSCertificate NSSUserCertificate;

 /*

  * NSSPrivateKey

  *

  * This is the public representation of a Private Key.  In general,

  * the actual value of the key is not available, but operations may

  * be performed with it.

  */

 struct NSSPrivateKeyStr;

 typedef struct NSSPrivateKeyStr NSSPrivateKey;

 /*

  * NSSPublicKey

  *

  */

 struct NSSPublicKeyStr;

 typedef struct NSSPublicKeyStr NSSPublicKey;

 /*

  * NSSSymmetricKey

  *

  */

 struct NSSSymmetricKeyStr;

 typedef struct NSSSymmetricKeyStr NSSSymmetricKey;

 /*

  * NSSTrustDomain

  *

  * A Trust Domain is the field in which certificates may be validated.

  * A trust domain will generally have one or more cryptographic modules

  * open; these modules perform the cryptographic operations, and 

  * provide the basic "root" trust information from which the trust in

  * a specific certificate or key depends.

  *

  * A client program, or a simple server, would typically have one

  * trust domain.  A server supporting multiple "virtual servers" might

  * have a separate trust domain for each virtual server.  The separate

  * trust domains might share some modules (e.g., a hardware crypto

  * accelerator) but not others (e.g., the tokens storing the different

  * servers' private keys, or the databases with each server's trusted

  * root certificates).

  *

  * This object descends from the "permananet database" in the old code.

  */

 struct NSSTrustDomainStr;

 typedef struct NSSTrustDomainStr NSSTrustDomain;

 /*

  * NSSCryptoContext

  *

  * A Crypto Context is a short-term, "helper" object which is used

  * for the lifetime of one ongoing "crypto operation."  Such an

  * operation may be the creation of a signed message, the use of an

  * TLS socket connection, etc.  Each crypto context is "in" a

  * specific trust domain, and it may have associated with it a

  * distinguished certificate, public key, private key, and/or

  * symmetric key.  It can also temporarily hold and use temporary

  * data (e.g. intermediate certificates) which is not stored

  * permanently in the trust domain.

  *

  * In OO terms, this interface inherits interfaces from the trust

  * domain, the certificates, and the keys.  It also provides

  * streaming crypto operations.

  *

  * This object descends from the "temporary database" concept in the

  * old code, but it has changed a lot as a result of what we've 

  * learned.

  */

 typedef struct NSSCryptoContextStr NSSCryptoContext;

 /*

  * fgmr others

  */

 /*

  * OBJECT IDENTIFIER

  *

  * This is the basic OID that crops up everywhere.

  */

 struct NSSOIDStr;  /* unused opaque structure */

 typedef struct NSSOIDStr NSSOID;

 /* 

  * NSSTime

  *

  * Unfortunately, we need an "exceptional" value to indicate

  * an error upon return, or "no value" on input.  Note that zero

  * is a perfectly valid value for both time_t and PRTime.

  *

  * If we were to create a "range" object, with two times for

  * Not Before and Not After, we would have an obvious place for

  * the somewhat arbitrary logic involved in comparing them.

  *

  * Failing that, let's have an NSSTime_CompareRanges function.

  */

 struct NSSTimeStr;

 typedef struct NSSTimeStr NSSTime;

 struct NSSTrustStr;

 typedef struct NSSTrustStr NSSTrust;

 /*

  * NSSUsage

  *

  * This is trickier than originally planned; I'll write up a

  * doc on it.

  *

  * We'd still like nsspki.h to have a list of common usages,

  * e.g.:

  *

  *  extern const NSSUsage *NSSUsage_ClientAuth;

  *  extern const NSSUsage *NSSUsage_ServerAuth;

  *  extern const NSSUsage *NSSUsage_SignEmail;

  *  extern const NSSUsage *NSSUsage_EncryptEmail;

  *  etc.

  */

 struct NSSUsageStr;

 typedef struct NSSUsageStr NSSUsage;

 /*

  * NSSPolicies

  *

  * Placeholder, for now.

  */

 struct NSSPoliciesStr;

 typedef struct NSSPoliciesStr NSSPolicies;

 /*

  * NSSAlgorithmAndParameters

  *

  * Algorithm is an OID

  * Parameters depend on the algorithm

  */

 struct NSSAlgorithmAndParametersStr;

 typedef struct NSSAlgorithmAndParametersStr NSSAlgorithmAndParameters;

 /*

  * NSSCallback

  *

  * At minimum, a "challenge" method and a closure argument.

  * Usually the challenge will just be prompting for a password.

  * How OO do we want to make it?

  */

 typedef struct NSSCallbackStr NSSCallback;

 struct NSSCallbackStr {

     /* Prompt for a password to initialize a slot.  */

     PRStatus (* getInitPW)(NSSUTF8 *slotName, void *arg, 

                            NSSUTF8 **ssoPW, NSSUTF8 **userPW); 

     /* Prompt for oldPW and newPW in order to change the 

      * password on a slot.  

      */

     PRStatus (* getNewPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,

                           NSSUTF8 **oldPW, NSSUTF8 **newPW); 

     /* Prompt for slot password.  */

     PRStatus (* getPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,

                        NSSUTF8 **password); 

     void *arg;

 };

 /* set errors - user cancelled, ... */

 typedef PRUint32 NSSOperations;

 /* 1) Do we want these to be preprocessor definitions or constants? */

 /* 2) What is the correct and complete list? */

 #define NSSOperations_ENCRYPT           0x0001

 #define NSSOperations_DECRYPT           0x0002

 #define NSSOperations_WRAP              0x0004

 #define NSSOperations_UNWRAP            0x0008

 #define NSSOperations_SIGN              0x0010

 #define NSSOperations_SIGN_RECOVER      0x0020

 #define NSSOperations_VERIFY            0x0040

 #define NSSOperations_VERIFY_RECOVER    0x0080

 struct NSSPKIXCertificateStr;

 PR_END_EXTERN_C

 #endif /* NSSPKIT_H */