michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef NSSPKIT_H
michael@0: #define NSSPKIT_H
michael@0: 
michael@0: /*
michael@0:  * nsspkit.h
michael@0:  *
michael@0:  * This file defines the types of the top-level PKI objects.
michael@0:  */
michael@0: 
michael@0: #ifndef NSSBASET_H
michael@0: #include "nssbaset.h"
michael@0: #endif /* NSSBASET_H */
michael@0: 
michael@0: PR_BEGIN_EXTERN_C
michael@0: 
michael@0: /*
michael@0:  * NSSCertificate
michael@0:  *
michael@0:  * This is the public representation of a Certificate.  The certificate
michael@0:  * may be one found on a smartcard or other token, one decoded from data
michael@0:  * received as part of a protocol, one constructed from constituent
michael@0:  * parts, etc.  Usually it is associated with ("in") a trust domain; as
michael@0:  * it can be verified only within a trust domain.  The underlying type
michael@0:  * of certificate may be of any supported standard, e.g. PKIX, PGP, etc.
michael@0:  *
michael@0:  * People speak of "verifying (with) the server's, or correspondant's, 
michael@0:  * certificate"; for simple operations we support that simplification
michael@0:  * by implementing public-key crypto operations as methods on this type.
michael@0:  */
michael@0: 
michael@0: struct NSSCertificateStr;
michael@0: typedef struct NSSCertificateStr NSSCertificate;
michael@0: 
michael@0: /*
michael@0:  * NSSUserCertificate
michael@0:  *
michael@0:  * A ``User'' certificate is one for which the private key is available.
michael@0:  * People speak of "using my certificate to sign my email" and "using
michael@0:  * my certificate to authenticate to (or login to) the server"; for
michael@0:  * simple operations, we support that simplification by implementing
michael@0:  * private-key crypto operations as methods on this type.
michael@0:  *
michael@0:  * The current design only weakly distinguishes between certificates
michael@0:  * and user certificates: as far as the compiler goes they're 
michael@0:  * interchangeable; debug libraries only have one common pointer-tracker;
michael@0:  * etc.  However, attempts to do private-key operations on a certificate
michael@0:  * for which the private key is not available will fail.
michael@0:  *
michael@0:  * Open design question: should these types be more firmly separated?
michael@0:  */
michael@0: 
michael@0: typedef NSSCertificate NSSUserCertificate;
michael@0: 
michael@0: /*
michael@0:  * NSSPrivateKey
michael@0:  *
michael@0:  * This is the public representation of a Private Key.  In general,
michael@0:  * the actual value of the key is not available, but operations may
michael@0:  * be performed with it.
michael@0:  */
michael@0: 
michael@0: struct NSSPrivateKeyStr;
michael@0: typedef struct NSSPrivateKeyStr NSSPrivateKey;
michael@0: 
michael@0: /*
michael@0:  * NSSPublicKey
michael@0:  *
michael@0:  */
michael@0: 
michael@0: struct NSSPublicKeyStr;
michael@0: typedef struct NSSPublicKeyStr NSSPublicKey;
michael@0: 
michael@0: /*
michael@0:  * NSSSymmetricKey
michael@0:  *
michael@0:  */
michael@0: 
michael@0: struct NSSSymmetricKeyStr;
michael@0: typedef struct NSSSymmetricKeyStr NSSSymmetricKey;
michael@0: 
michael@0: /*
michael@0:  * NSSTrustDomain
michael@0:  *
michael@0:  * A Trust Domain is the field in which certificates may be validated.
michael@0:  * A trust domain will generally have one or more cryptographic modules
michael@0:  * open; these modules perform the cryptographic operations, and 
michael@0:  * provide the basic "root" trust information from which the trust in
michael@0:  * a specific certificate or key depends.
michael@0:  *
michael@0:  * A client program, or a simple server, would typically have one
michael@0:  * trust domain.  A server supporting multiple "virtual servers" might
michael@0:  * have a separate trust domain for each virtual server.  The separate
michael@0:  * trust domains might share some modules (e.g., a hardware crypto
michael@0:  * accelerator) but not others (e.g., the tokens storing the different
michael@0:  * servers' private keys, or the databases with each server's trusted
michael@0:  * root certificates).
michael@0:  *
michael@0:  * This object descends from the "permananet database" in the old code.
michael@0:  */
michael@0: 
michael@0: struct NSSTrustDomainStr;
michael@0: typedef struct NSSTrustDomainStr NSSTrustDomain;
michael@0: 
michael@0: /*
michael@0:  * NSSCryptoContext
michael@0:  *
michael@0:  * A Crypto Context is a short-term, "helper" object which is used
michael@0:  * for the lifetime of one ongoing "crypto operation."  Such an
michael@0:  * operation may be the creation of a signed message, the use of an
michael@0:  * TLS socket connection, etc.  Each crypto context is "in" a
michael@0:  * specific trust domain, and it may have associated with it a
michael@0:  * distinguished certificate, public key, private key, and/or
michael@0:  * symmetric key.  It can also temporarily hold and use temporary
michael@0:  * data (e.g. intermediate certificates) which is not stored
michael@0:  * permanently in the trust domain.
michael@0:  *
michael@0:  * In OO terms, this interface inherits interfaces from the trust
michael@0:  * domain, the certificates, and the keys.  It also provides
michael@0:  * streaming crypto operations.
michael@0:  *
michael@0:  * This object descends from the "temporary database" concept in the
michael@0:  * old code, but it has changed a lot as a result of what we've 
michael@0:  * learned.
michael@0:  */
michael@0: 
michael@0: typedef struct NSSCryptoContextStr NSSCryptoContext;
michael@0: 
michael@0: /*
michael@0:  * fgmr others
michael@0:  */
michael@0: 
michael@0: /*
michael@0:  * OBJECT IDENTIFIER
michael@0:  *
michael@0:  * This is the basic OID that crops up everywhere.
michael@0:  */
michael@0: 
michael@0: struct NSSOIDStr;  /* unused opaque structure */
michael@0: typedef struct NSSOIDStr NSSOID;
michael@0: 
michael@0: /* 
michael@0:  * NSSTime
michael@0:  *
michael@0:  * Unfortunately, we need an "exceptional" value to indicate
michael@0:  * an error upon return, or "no value" on input.  Note that zero
michael@0:  * is a perfectly valid value for both time_t and PRTime.
michael@0:  *
michael@0:  * If we were to create a "range" object, with two times for
michael@0:  * Not Before and Not After, we would have an obvious place for
michael@0:  * the somewhat arbitrary logic involved in comparing them.
michael@0:  *
michael@0:  * Failing that, let's have an NSSTime_CompareRanges function.
michael@0:  */
michael@0: 
michael@0: struct NSSTimeStr;
michael@0: typedef struct NSSTimeStr NSSTime;
michael@0: 
michael@0: struct NSSTrustStr;
michael@0: typedef struct NSSTrustStr NSSTrust;
michael@0: 
michael@0: /*
michael@0:  * NSSUsage
michael@0:  *
michael@0:  * This is trickier than originally planned; I'll write up a
michael@0:  * doc on it.
michael@0:  *
michael@0:  * We'd still like nsspki.h to have a list of common usages,
michael@0:  * e.g.:
michael@0:  *
michael@0:  *  extern const NSSUsage *NSSUsage_ClientAuth;
michael@0:  *  extern const NSSUsage *NSSUsage_ServerAuth;
michael@0:  *  extern const NSSUsage *NSSUsage_SignEmail;
michael@0:  *  extern const NSSUsage *NSSUsage_EncryptEmail;
michael@0:  *  etc.
michael@0:  */
michael@0: 
michael@0: struct NSSUsageStr;
michael@0: typedef struct NSSUsageStr NSSUsage;
michael@0: 
michael@0: /*
michael@0:  * NSSPolicies
michael@0:  *
michael@0:  * Placeholder, for now.
michael@0:  */
michael@0: 
michael@0: struct NSSPoliciesStr;
michael@0: typedef struct NSSPoliciesStr NSSPolicies;
michael@0: 
michael@0: /*
michael@0:  * NSSAlgorithmAndParameters
michael@0:  *
michael@0:  * Algorithm is an OID
michael@0:  * Parameters depend on the algorithm
michael@0:  */
michael@0: 
michael@0: struct NSSAlgorithmAndParametersStr;
michael@0: typedef struct NSSAlgorithmAndParametersStr NSSAlgorithmAndParameters;
michael@0: 
michael@0: /*
michael@0:  * NSSCallback
michael@0:  *
michael@0:  * At minimum, a "challenge" method and a closure argument.
michael@0:  * Usually the challenge will just be prompting for a password.
michael@0:  * How OO do we want to make it?
michael@0:  */
michael@0: 
michael@0: typedef struct NSSCallbackStr NSSCallback;
michael@0: 
michael@0: struct NSSCallbackStr {
michael@0:     /* Prompt for a password to initialize a slot.  */
michael@0:     PRStatus (* getInitPW)(NSSUTF8 *slotName, void *arg, 
michael@0:                            NSSUTF8 **ssoPW, NSSUTF8 **userPW); 
michael@0:     /* Prompt for oldPW and newPW in order to change the 
michael@0:      * password on a slot.  
michael@0:      */
michael@0:     PRStatus (* getNewPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,
michael@0:                           NSSUTF8 **oldPW, NSSUTF8 **newPW); 
michael@0:     /* Prompt for slot password.  */
michael@0:     PRStatus (* getPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,
michael@0:                        NSSUTF8 **password); 
michael@0:     void *arg;
michael@0: };
michael@0: 
michael@0: /* set errors - user cancelled, ... */
michael@0: 
michael@0: typedef PRUint32 NSSOperations;
michael@0: /* 1) Do we want these to be preprocessor definitions or constants? */
michael@0: /* 2) What is the correct and complete list? */
michael@0: 
michael@0: #define NSSOperations_ENCRYPT           0x0001
michael@0: #define NSSOperations_DECRYPT           0x0002
michael@0: #define NSSOperations_WRAP              0x0004
michael@0: #define NSSOperations_UNWRAP            0x0008
michael@0: #define NSSOperations_SIGN              0x0010
michael@0: #define NSSOperations_SIGN_RECOVER      0x0020
michael@0: #define NSSOperations_VERIFY            0x0040
michael@0: #define NSSOperations_VERIFY_RECOVER    0x0080
michael@0: 
michael@0: struct NSSPKIXCertificateStr;
michael@0: 
michael@0: PR_END_EXTERN_C
michael@0: 
michael@0: #endif /* NSSPKIT_H */