nsspkit.h (7251B)
1 /* This Source Code Form is subject to the terms of the Mozilla Public 2 * License, v. 2.0. If a copy of the MPL was not distributed with this 3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 4 5 #ifndef NSSPKIT_H 6 #define NSSPKIT_H 7 8 /* 9 * nsspkit.h 10 * 11 * This file defines the types of the top-level PKI objects. 12 */ 13 14 #ifndef NSSBASET_H 15 #include "nssbaset.h" 16 #endif /* NSSBASET_H */ 17 18 PR_BEGIN_EXTERN_C 19 20 /* 21 * NSSCertificate 22 * 23 * This is the public representation of a Certificate. The certificate 24 * may be one found on a smartcard or other token, one decoded from data 25 * received as part of a protocol, one constructed from constituent 26 * parts, etc. Usually it is associated with ("in") a trust domain; as 27 * it can be verified only within a trust domain. The underlying type 28 * of certificate may be of any supported standard, e.g. PKIX, PGP, etc. 29 * 30 * People speak of "verifying (with) the server's, or correspondant's, 31 * certificate"; for simple operations we support that simplification 32 * by implementing public-key crypto operations as methods on this type. 33 */ 34 35 struct NSSCertificateStr; 36 typedef struct NSSCertificateStr NSSCertificate; 37 38 /* 39 * NSSUserCertificate 40 * 41 * A ``User'' certificate is one for which the private key is available. 42 * People speak of "using my certificate to sign my email" and "using 43 * my certificate to authenticate to (or login to) the server"; for 44 * simple operations, we support that simplification by implementing 45 * private-key crypto operations as methods on this type. 46 * 47 * The current design only weakly distinguishes between certificates 48 * and user certificates: as far as the compiler goes they're 49 * interchangeable; debug libraries only have one common pointer-tracker; 50 * etc. However, attempts to do private-key operations on a certificate 51 * for which the private key is not available will fail. 52 * 53 * Open design question: should these types be more firmly separated? 54 */ 55 56 typedef NSSCertificate NSSUserCertificate; 57 58 /* 59 * NSSPrivateKey 60 * 61 * This is the public representation of a Private Key. In general, 62 * the actual value of the key is not available, but operations may 63 * be performed with it. 64 */ 65 66 struct NSSPrivateKeyStr; 67 typedef struct NSSPrivateKeyStr NSSPrivateKey; 68 69 /* 70 * NSSPublicKey 71 * 72 */ 73 74 struct NSSPublicKeyStr; 75 typedef struct NSSPublicKeyStr NSSPublicKey; 76 77 /* 78 * NSSSymmetricKey 79 * 80 */ 81 82 struct NSSSymmetricKeyStr; 83 typedef struct NSSSymmetricKeyStr NSSSymmetricKey; 84 85 /* 86 * NSSTrustDomain 87 * 88 * A Trust Domain is the field in which certificates may be validated. 89 * A trust domain will generally have one or more cryptographic modules 90 * open; these modules perform the cryptographic operations, and 91 * provide the basic "root" trust information from which the trust in 92 * a specific certificate or key depends. 93 * 94 * A client program, or a simple server, would typically have one 95 * trust domain. A server supporting multiple "virtual servers" might 96 * have a separate trust domain for each virtual server. The separate 97 * trust domains might share some modules (e.g., a hardware crypto 98 * accelerator) but not others (e.g., the tokens storing the different 99 * servers' private keys, or the databases with each server's trusted 100 * root certificates). 101 * 102 * This object descends from the "permananet database" in the old code. 103 */ 104 105 struct NSSTrustDomainStr; 106 typedef struct NSSTrustDomainStr NSSTrustDomain; 107 108 /* 109 * NSSCryptoContext 110 * 111 * A Crypto Context is a short-term, "helper" object which is used 112 * for the lifetime of one ongoing "crypto operation." Such an 113 * operation may be the creation of a signed message, the use of an 114 * TLS socket connection, etc. Each crypto context is "in" a 115 * specific trust domain, and it may have associated with it a 116 * distinguished certificate, public key, private key, and/or 117 * symmetric key. It can also temporarily hold and use temporary 118 * data (e.g. intermediate certificates) which is not stored 119 * permanently in the trust domain. 120 * 121 * In OO terms, this interface inherits interfaces from the trust 122 * domain, the certificates, and the keys. It also provides 123 * streaming crypto operations. 124 * 125 * This object descends from the "temporary database" concept in the 126 * old code, but it has changed a lot as a result of what we've 127 * learned. 128 */ 129 130 typedef struct NSSCryptoContextStr NSSCryptoContext; 131 132 /* 133 * fgmr others 134 */ 135 136 /* 137 * OBJECT IDENTIFIER 138 * 139 * This is the basic OID that crops up everywhere. 140 */ 141 142 struct NSSOIDStr; /* unused opaque structure */ 143 typedef struct NSSOIDStr NSSOID; 144 145 /* 146 * NSSTime 147 * 148 * Unfortunately, we need an "exceptional" value to indicate 149 * an error upon return, or "no value" on input. Note that zero 150 * is a perfectly valid value for both time_t and PRTime. 151 * 152 * If we were to create a "range" object, with two times for 153 * Not Before and Not After, we would have an obvious place for 154 * the somewhat arbitrary logic involved in comparing them. 155 * 156 * Failing that, let's have an NSSTime_CompareRanges function. 157 */ 158 159 struct NSSTimeStr; 160 typedef struct NSSTimeStr NSSTime; 161 162 struct NSSTrustStr; 163 typedef struct NSSTrustStr NSSTrust; 164 165 /* 166 * NSSUsage 167 * 168 * This is trickier than originally planned; I'll write up a 169 * doc on it. 170 * 171 * We'd still like nsspki.h to have a list of common usages, 172 * e.g.: 173 * 174 * extern const NSSUsage *NSSUsage_ClientAuth; 175 * extern const NSSUsage *NSSUsage_ServerAuth; 176 * extern const NSSUsage *NSSUsage_SignEmail; 177 * extern const NSSUsage *NSSUsage_EncryptEmail; 178 * etc. 179 */ 180 181 struct NSSUsageStr; 182 typedef struct NSSUsageStr NSSUsage; 183 184 /* 185 * NSSPolicies 186 * 187 * Placeholder, for now. 188 */ 189 190 struct NSSPoliciesStr; 191 typedef struct NSSPoliciesStr NSSPolicies; 192 193 /* 194 * NSSAlgorithmAndParameters 195 * 196 * Algorithm is an OID 197 * Parameters depend on the algorithm 198 */ 199 200 struct NSSAlgorithmAndParametersStr; 201 typedef struct NSSAlgorithmAndParametersStr NSSAlgorithmAndParameters; 202 203 /* 204 * NSSCallback 205 * 206 * At minimum, a "challenge" method and a closure argument. 207 * Usually the challenge will just be prompting for a password. 208 * How OO do we want to make it? 209 */ 210 211 typedef struct NSSCallbackStr NSSCallback; 212 213 struct NSSCallbackStr { 214 /* Prompt for a password to initialize a slot. */ 215 PRStatus (*getInitPW)(NSSUTF8 *slotName, void *arg, 216 NSSUTF8 **ssoPW, NSSUTF8 **userPW); 217 /* Prompt for oldPW and newPW in order to change the 218 * password on a slot. 219 */ 220 PRStatus (*getNewPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg, 221 NSSUTF8 **oldPW, NSSUTF8 **newPW); 222 /* Prompt for slot password. */ 223 PRStatus (*getPW)(NSSUTF8 *slotName, PRUint32 *retries, void *arg, 224 NSSUTF8 **password); 225 void *arg; 226 }; 227 228 /* set errors - user cancelled, ... */ 229 230 typedef PRUint32 NSSOperations; 231 /* 1) Do we want these to be preprocessor definitions or constants? */ 232 /* 2) What is the correct and complete list? */ 233 234 #define NSSOperations_ENCRYPT 0x0001 235 #define NSSOperations_DECRYPT 0x0002 236 #define NSSOperations_WRAP 0x0004 237 #define NSSOperations_UNWRAP 0x0008 238 #define NSSOperations_SIGN 0x0010 239 #define NSSOperations_SIGN_RECOVER 0x0020 240 #define NSSOperations_VERIFY 0x0040 241 #define NSSOperations_VERIFY_RECOVER 0x0080 242 243 struct NSSPKIXCertificateStr; 244 245 PR_END_EXTERN_C 246 247 #endif /* NSSPKIT_H */