The Tor Browser / file comparison

comparison: security/nss/lib/pki/nsspkit.h

security/nss/lib/pki/nsspkit.h

changeset 2
7e26c7da4463
equal deleted inserted replaced
-1:000000000000 0:51e0fb7f68cd
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 */

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial