1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
/* 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 */
|
