Back to index

lightning-sunbird  0.9+nobinonly
nsspkit.h
Go to the documentation of this file.
00001 /* ***** BEGIN LICENSE BLOCK *****
00002  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00003  *
00004  * The contents of this file are subject to the Mozilla Public License Version
00005  * 1.1 (the "License"); you may not use this file except in compliance with
00006  * the License. You may obtain a copy of the License at
00007  * http://www.mozilla.org/MPL/
00008  *
00009  * Software distributed under the License is distributed on an "AS IS" basis,
00010  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00011  * for the specific language governing rights and limitations under the
00012  * License.
00013  *
00014  * The Original Code is the Netscape security libraries.
00015  *
00016  * The Initial Developer of the Original Code is
00017  * Netscape Communications Corporation.
00018  * Portions created by the Initial Developer are Copyright (C) 1994-2000
00019  * the Initial Developer. All Rights Reserved.
00020  *
00021  * Contributor(s):
00022  *
00023  * Alternatively, the contents of this file may be used under the terms of
00024  * either the GNU General Public License Version 2 or later (the "GPL"), or
00025  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00026  * in which case the provisions of the GPL or the LGPL are applicable instead
00027  * of those above. If you wish to allow use of your version of this file only
00028  * under the terms of either the GPL or the LGPL, and not to allow others to
00029  * use your version of this file under the terms of the MPL, indicate your
00030  * decision by deleting the provisions above and replace them with the notice
00031  * and other provisions required by the GPL or the LGPL. If you do not delete
00032  * the provisions above, a recipient may use your version of this file under
00033  * the terms of any one of the MPL, the GPL or the LGPL.
00034  *
00035  * ***** END LICENSE BLOCK ***** */
00036 
00037 #ifndef NSSPKIT_H
00038 #define NSSPKIT_H
00039 
00040 #ifdef DEBUG
00041 static const char NSSPKIT_CVS_ID[] = "@(#) $RCSfile: nsspkit.h,v $ $Revision: 1.6 $ $Date: 2005/01/20 02:25:49 $";
00042 #endif /* DEBUG */
00043 
00044 /*
00045  * nsspkit.h
00046  *
00047  * This file defines the types of the top-level PKI objects.
00048  */
00049 
00050 #ifndef NSSBASET_H
00051 #include "nssbaset.h"
00052 #endif /* NSSBASET_H */
00053 
00054 PR_BEGIN_EXTERN_C
00055 
00056 /*
00057  * NSSCertificate
00058  *
00059  * This is the public representation of a Certificate.  The certificate
00060  * may be one found on a smartcard or other token, one decoded from data
00061  * received as part of a protocol, one constructed from constituent
00062  * parts, etc.  Usually it is associated with ("in") a trust domain; as
00063  * it can be verified only within a trust domain.  The underlying type
00064  * of certificate may be of any supported standard, e.g. PKIX, PGP, etc.
00065  *
00066  * People speak of "verifying (with) the server's, or correspondant's, 
00067  * certificate"; for simple operations we support that simplification
00068  * by implementing public-key crypto operations as methods on this type.
00069  */
00070 
00071 struct NSSCertificateStr;
00072 typedef struct NSSCertificateStr NSSCertificate;
00073 
00074 /*
00075  * NSSUserCertificate
00076  *
00077  * A ``User'' certificate is one for which the private key is available.
00078  * People speak of "using my certificate to sign my email" and "using
00079  * my certificate to authenticate to (or login to) the server"; for
00080  * simple operations, we support that simplification by implementing
00081  * private-key crypto operations as methods on this type.
00082  *
00083  * The current design only weakly distinguishes between certificates
00084  * and user certificates: as far as the compiler goes they're 
00085  * interchangable; debug libraries only have one common pointer-tracker;
00086  * etc.  However, attempts to do private-key operations on a certificate
00087  * for which the private key is not available will fail.
00088  *
00089  * Open design question: should these types be more firmly separated?
00090  */
00091 
00092 typedef NSSCertificate NSSUserCertificate;
00093 
00094 /*
00095  * NSSPrivateKey
00096  *
00097  * This is the public representation of a Private Key.  In general,
00098  * the actual value of the key is not available, but operations may
00099  * be performed with it.
00100  */
00101 
00102 struct NSSPrivateKeyStr;
00103 typedef struct NSSPrivateKeyStr NSSPrivateKey;
00104 
00105 /*
00106  * NSSPublicKey
00107  *
00108  */
00109 
00110 struct NSSPublicKeyStr;
00111 typedef struct NSSPublicKeyStr NSSPublicKey;
00112 
00113 /*
00114  * NSSSymmetricKey
00115  *
00116  */
00117 
00118 struct NSSSymmetricKeyStr;
00119 typedef struct NSSSymmetricKeyStr NSSSymmetricKey;
00120 
00121 /*
00122  * NSSTrustDomain
00123  *
00124  * A Trust Domain is the field in which certificates may be validated.
00125  * A trust domain will generally have one or more cryptographic modules
00126  * open; these modules perform the cryptographic operations, and 
00127  * provide the basic "root" trust information from which the trust in
00128  * a specific certificate or key depends.
00129  *
00130  * A client program, or a simple server, would typically have one
00131  * trust domain.  A server supporting multiple "virtual servers" might
00132  * have a separate trust domain for each virtual server.  The separate
00133  * trust domains might share some modules (e.g., a hardware crypto
00134  * accelerator) but not others (e.g., the tokens storing the different
00135  * servers' private keys, or the databases with each server's trusted
00136  * root certificates).
00137  *
00138  * This object descends from the "permananet database" in the old code.
00139  */
00140 
00141 struct NSSTrustDomainStr;
00142 typedef struct NSSTrustDomainStr NSSTrustDomain;
00143 
00144 /*
00145  * NSSCryptoContext
00146  *
00147  * A Crypto Context is a short-term, "helper" object which is used
00148  * for the lifetime of one ongoing "crypto operation."  Such an
00149  * operation may be the creation of a signed message, the use of an
00150  * TLS socket connection, etc.  Each crypto context is "in" a
00151  * specific trust domain, and it may have associated with it a
00152  * distinguished certificate, public key, private key, and/or
00153  * symmetric key.  It can also temporarily hold and use temporary
00154  * data (e.g. intermediate certificates) which is not stored
00155  * permanently in the trust domain.
00156  *
00157  * In OO terms, this interface inherits interfaces from the trust
00158  * domain, the certificates, and the keys.  It also provides
00159  * streaming crypto operations.
00160  *
00161  * This object descends from the "temporary database" concept in the
00162  * old code, but it has changed a lot as a result of what we've 
00163  * learned.
00164  */
00165 
00166 typedef struct NSSCryptoContextStr NSSCryptoContext;
00167 
00168 /*
00169  * fgmr others
00170  */
00171 
00172 /* 
00173  * NSSTime
00174  *
00175  * Unfortunately, we need an "exceptional" value to indicate
00176  * an error upon return, or "no value" on input.  Note that zero
00177  * is a perfectly valid value for both time_t and PRTime.
00178  *
00179  * If we were to create a "range" object, with two times for
00180  * Not Before and Not After, we would have an obvious place for
00181  * the somewhat arbitrary logic involved in comparing them.
00182  *
00183  * Failing that, let's have an NSSTime_CompareRanges function.
00184  */
00185 
00186 struct NSSTimeStr;
00187 typedef struct NSSTimeStr NSSTime;
00188 
00189 struct NSSTrustStr;
00190 typedef struct NSSTrustStr NSSTrust;
00191 
00192 /*
00193  * NSSUsage
00194  *
00195  * This is trickier than originally planned; I'll write up a
00196  * doc on it.
00197  *
00198  * We'd still like nsspki.h to have a list of common usages,
00199  * e.g.:
00200  *
00201  *  extern const NSSUsage *NSSUsage_ClientAuth;
00202  *  extern const NSSUsage *NSSUsage_ServerAuth;
00203  *  extern const NSSUsage *NSSUsage_SignEmail;
00204  *  extern const NSSUsage *NSSUsage_EncryptEmail;
00205  *  etc.
00206  */
00207 
00208 struct NSSUsageStr;
00209 typedef struct NSSUsageStr NSSUsage;
00210 
00211 /*
00212  * NSSPolicies
00213  *
00214  * Placeholder, for now.
00215  */
00216 
00217 struct NSSPoliciesStr;
00218 typedef struct NSSPoliciesStr NSSPolicies;
00219 
00220 /*
00221  * NSSAlgorithmAndParameters
00222  *
00223  * Algorithm is an OID
00224  * Parameters depend on the algorithm
00225  */
00226 
00227 struct NSSAlgorithmAndParametersStr;
00228 typedef struct NSSAlgorithmAndParametersStr NSSAlgorithmAndParameters;
00229 
00230 /*
00231  * NSSCallback
00232  *
00233  * At minimum, a "challenge" method and a closure argument.
00234  * Usually the challenge will just be prompting for a password.
00235  * How OO do we want to make it?
00236  */
00237 
00238 typedef struct NSSCallbackStr NSSCallback;
00239 
00240 struct NSSCallbackStr {
00241     /* Prompt for a password to initialize a slot.  */
00242     PRStatus (* getInitPW)(NSSUTF8 *slotName, void *arg, 
00243                            NSSUTF8 **ssoPW, NSSUTF8 **userPW); 
00244     /* Prompt for oldPW and newPW in order to change the 
00245      * password on a slot.  
00246      */
00247     PRStatus (* getNewPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,
00248                           NSSUTF8 **oldPW, NSSUTF8 **newPW); 
00249     /* Prompt for slot password.  */
00250     PRStatus (* getPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg,
00251                        NSSUTF8 **password); 
00252     void *arg;
00253 };
00254 
00255 /* set errors - user cancelled, ... */
00256 
00257 typedef PRUint32 NSSOperations;
00258 /* 1) Do we want these to be preprocessor definitions or constants? */
00259 /* 2) What is the correct and complete list? */
00260 
00261 #define NSSOperations_ENCRYPT           0x0001
00262 #define NSSOperations_DECRYPT           0x0002
00263 #define NSSOperations_WRAP              0x0004
00264 #define NSSOperations_UNWRAP            0x0008
00265 #define NSSOperations_SIGN              0x0010
00266 #define NSSOperations_SIGN_RECOVER      0x0020
00267 #define NSSOperations_VERIFY            0x0040
00268 #define NSSOperations_VERIFY_RECOVER    0x0080
00269 
00270 struct NSSPKIXCertificateStr;
00271 
00272 PR_END_EXTERN_C
00273 
00274 #endif /* NSSPKIT_H */