summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/crmf/crmffut.h
blob: d6f9374384fd3b6a6ea827e4b3455b777efc0ef2 (plain)
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
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
/* 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/. */

/*
 * These functions to be implemented in the future if the features
 * which these functions would implement wind up being needed.
 */

/*
 * Use this function to create the CRMFSinglePubInfo* variables that will
 * populate the inPubInfoArray parameter for the function
 * CRMF_CreatePKIPublicationInfo.
 *
 * "inPubMethod" specifies which publication method will be used
 * "pubLocation" is a representation of the location where
 */
extern CRMFSinglePubInfo *
CRMF_CreateSinglePubInfo(CRMFPublicationMethod inPubMethod,
                         CRMFGeneralName *pubLocation);

/*
 * Create a PKIPublicationInfo that can later be passed to the function
 * CRMFAddPubInfoControl.
 */
extern CRMFPKIPublicationInfo *
CRMF_CreatePKIPublicationInfo(CRMFPublicationAction inAction,
                              CRMFSinglePubInfo **inPubInfoArray,
                              int numPubInfo);

/*
 * Only call this function on a CRMFPublicationInfo that was created by
 * CRMF_CreatePKIPublicationInfo that was passed in NULL for arena.
 */

extern SECStatus
CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);

extern SECStatus CRMF_AddPubInfoControl(CRMFCertRequest *inCertReq,
                                        CRMFPKIPublicationInfo *inPubInfo);

/*
 * This is to create a Cert ID Control which can later be added to
 * a certificate request.
 */
extern CRMFCertID *CRMF_CreateCertID(CRMFGeneralName *issuer,
                                     long serialNumber);

extern SECStatus CRMF_DestroyCertID(CRMFCertID *certID);

extern SECStatus CRMF_AddCertIDControl(CRMFCertRequest *inCertReq,
                                       CRMFCertID *certID);

extern SECStatus
CRMF_AddProtocolEncryptioKeyControl(CRMFCertRequest *inCertReq,
                                    CERTSubjectPublicKeyInfo *spki);

/*
 * Add the ASCII Pairs Registration Info to the Certificate Request.
 * The SECItem must be an OCTET string representation.
 */
extern SECStatus
CRMF_AddUTF8PairsRegInfo(CRMFCertRequest *inCertReq,
                         SECItem *asciiPairs);

/*
 * This takes a CertRequest and adds it to another CertRequest.
 */
extern SECStatus
CRMF_AddCertReqToRegInfo(CRMFCertRequest *certReqToAddTo,
                         CRMFCertRequest *certReqBeingAdded);

/*
 * Returns which option was used for the authInfo field of POPOSigningKeyInput
 */
extern CRMFPOPOSkiInputAuthChoice
CRMF_GetSignKeyInputAuthChoice(CRMFPOPOSigningKeyInput *inKeyInput);

/*
 * Gets the PKMACValue associated with the POPOSigningKeyInput.
 * If the POPOSigningKeyInput did not use authInfo.publicKeyMAC
 * the function returns SECFailure and the value at *destValue is unchanged.
 *
 * If the POPOSigningKeyInput did use authInfo.publicKeyMAC, the function
 * returns SECSuccess and places the PKMACValue at *destValue.
 */
extern SECStatus
CRMF_GetSignKeyInputPKMACValue(CRMFPOPOSigningKeyInput *inKeyInput,
                               CRMFPKMACValue **destValue);
/*
 * Gets the SubjectPublicKeyInfo from the POPOSigningKeyInput
 */
extern CERTSubjectPublicKeyInfo *
CRMF_GetSignKeyInputPublicKey(CRMFPOPOSigningKeyInput *inKeyInput);

/*
 * Return the value for the PKIPublicationInfo Control.
 * A return value of NULL indicates that the Control was
 * not a PKIPublicationInfo Control.  Call
 * CRMF_DestroyPKIPublicationInfo on the return value when done
 * using the pointer.
 */
extern CRMFPKIPublicationInfo *CRMF_GetPKIPubInfo(CRMFControl *inControl);

/*
 * Free up a CRMFPKIPublicationInfo structure.
 */
extern SECStatus
CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);

/*
 * Get the choice used for action in this PKIPublicationInfo.
 */
extern CRMFPublicationAction
CRMF_GetPublicationAction(CRMFPKIPublicationInfo *inPubInfo);

/*
 * Get the number of pubInfos are stored in the PKIPubicationInfo.
 */
extern int CRMF_GetNumPubInfos(CRMFPKIPublicationInfo *inPubInfo);

/*
 * Get the pubInfo at index for the given PKIPubicationInfo.
 * Indexing is done like a traditional C Array. (0 .. numElements-1)
 */
extern CRMFSinglePubInfo *
CRMF_GetPubInfoAtIndex(CRMFPKIPublicationInfo *inPubInfo,
                       int index);

/*
 * Destroy the CRMFSinglePubInfo.
 */
extern SECStatus CRMF_DestroySinglePubInfo(CRMFSinglePubInfo *inPubInfo);

/*
 * Get the pubMethod used by the SinglePubInfo.
 */
extern CRMFPublicationMethod
CRMF_GetPublicationMethod(CRMFSinglePubInfo *inPubInfo);

/*
 * Get the pubLocation associated with the SinglePubInfo.
 * A NULL return value indicates there was no pubLocation associated
 * with the SinglePuInfo.
 */
extern CRMFGeneralName *CRMF_GetPubLocation(CRMFSinglePubInfo *inPubInfo);

/*
 * Get the authInfo.sender field out of the POPOSigningKeyInput.
 * If the POPOSigningKeyInput did not use the authInfo the function
 * returns SECFailure and the value at *destName is unchanged.
 *
 * If the POPOSigningKeyInput did use authInfo.sender, the function returns
 * SECSuccess and puts the authInfo.sender at *destName/
 */
extern SECStatus CRMF_GetSignKeyInputSender(CRMFPOPOSigningKeyInput *keyInput,
                                            CRMFGeneralName **destName);

/**************** CMMF Functions that need to be added. **********************/

/*
 * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
 * INPUTS:
 *    inDecKeyChall
 *        The CMMFPOPODecKeyChallContent to operate on.
 *    inRandom
 *        The random number to use when generating the challenge,
 *    inSender
 *        The GeneralName representation of the sender of the challenge.
 *    inPubKey
 *        The public key to use when encrypting the challenge.
 * NOTES:
 *    This function adds a challenge to the end of the list of challenges
 *    contained by 'inDecKeyChall'.  Refer to the CMMF draft on how the
 *    the random number passed in and the sender's GeneralName are used
 *    to generate the challenge and witness fields of the challenge.  This
 *    library will use SHA1 as the one-way function for generating the
 *    witess field of the challenge.
 *
 * RETURN:
 *    SECSuccess if generating the challenge and adding to the end of list
 *    of challenges was successful.  Any other return value indicates an error
 *    while trying to generate the challenge.
 */
extern SECStatus
CMMF_POPODecKeyChallContentSetNextChallenge(CMMFPOPODecKeyChallContent *inDecKeyChall,
                                            long inRandom,
                                            CERTGeneralName *inSender,
                                            SECKEYPublicKey *inPubKey);

/*
 * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
 * INPUTS:
 *    inKeyChallCont
 *        The CMMFPOPODecKeyChallContent to operate on.
 * RETURN:
 *    This function returns the number of CMMFChallenges are contained in
 *    the CMMFPOPODecKeyChallContent structure.
 */
extern int CMMF_POPODecKeyChallContentGetNumChallenges(CMMFPOPODecKeyChallContent *inKeyChallCont);

/*
 * FUNCTION: CMMF_ChallengeGetRandomNumber
 * INPUTS:
 *    inChallenge
 *        The CMMFChallenge to operate on.
 *    inDest
 *        A pointer to a user supplied buffer where the library
 *        can place a copy of the random integer contatained in the
 *        challenge.
 * NOTES:
 *    This function returns the value held in the decrypted Rand structure
 *    corresponding to the random integer.  The user must call
 *    CMMF_ChallengeDecryptWitness before calling this function.  Call
 *    CMMF_ChallengeIsDecrypted to find out if the challenge has been
 *    decrypted.
 *
 * RETURN:
 *    SECSuccess indicates the witness field has been previously decrypted
 *    and the value for the random integer was successfully placed at *inDest.
 *    Any other return value indicates an error and that the value at *inDest
 *    is not a valid value.
 */
extern SECStatus CMMF_ChallengeGetRandomNumber(CMMFChallenge *inChallenge,
                                               long *inDest);

/*
 * FUNCTION: CMMF_ChallengeGetSender
 * INPUTS:
 *    inChallenge
 *        the CMMFChallenge to operate on.
 * NOTES:
 *    This function returns the value held in the decrypted Rand structure
 *    corresponding to the sender.  The user must call
 *    CMMF_ChallengeDecryptWitness before calling this function.  Call
 *    CMMF_ChallengeIsDecrypted to find out if the witness field has been
 *    decrypted.  The user must call CERT_DestroyGeneralName after the return
 *    value is no longer needed.
 *
 * RETURN:
 *    A pointer to a copy of the sender CERTGeneralName.  A return value of
 *    NULL indicates an error in trying to copy the information or that the
 *    witness field has not been decrypted.
 */
extern CERTGeneralName *CMMF_ChallengeGetSender(CMMFChallenge *inChallenge);

/*
 * FUNCTION: CMMF_ChallengeGetAlgId
 * INPUTS:
 *    inChallenge
 *        The CMMFChallenge to operate on.
 *    inDestAlgId
 *        A pointer to memory where a pointer to a copy of the algorithm
 *        id can be placed.
 * NOTES:
 *    This function retrieves the one way function algorithm identifier
 *    contained within the CMMFChallenge if the optional field is present.
 *
 * RETURN:
 *    SECSucces indicates the function was able to place a pointer to a copy of
 *    the alogrithm id at *inAlgId.  If the value at *inDestAlgId is NULL,
 *    that means there was no algorithm identifier present in the
 *    CMMFChallenge.  Any other return value indicates the function was not
 *    able to make a copy of the algorithm identifier.  In this case the value
 *    at *inDestAlgId is not valid.
 */
extern SECStatus CMMF_ChallengeGetAlgId(CMMFChallenge *inChallenge,
                                        SECAlgorithmID *inAlgId);

/*
 * FUNCTION: CMMF_DestroyChallenge
 * INPUTS:
 *    inChallenge
 *        The CMMFChallenge to free up.
 * NOTES:
 *    This function frees up all the memory associated with the CMMFChallenge
 *    passed in.
 * RETURN:
 *    SECSuccess if freeing all the memory associated with the CMMFChallenge
 *    passed in is successful.  Any other return value indicates an error
 *    while freeing the memory.
 */
extern SECStatus CMMF_DestroyChallenge(CMMFChallenge *inChallenge);

/*
 * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
 * INPUTS:
 *    inDecKeyResp
 *        The CMMFPOPODecKeyRespContent structure to free.
 * NOTES:
 *    This function frees up all the memory associate with the
 *    CMMFPOPODecKeyRespContent.
 *
 * RETURN:
 *    SECSuccess if freeint up all the memory associated with the
 *    CMMFPOPODecKeyRespContent structure is successful.  Any other
 *    return value indicates an error while freeing the memory.
 */
extern SECStatus
CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);

/*
 * FUNCTION: CMMF_ChallengeDecryptWitness
 * INPUTS:
 *    inChallenge
 *        The CMMFChallenge to operate on.
 *    inPrivKey
 *        The private key to use to decrypt the witness field.
 * NOTES:
 *    This function uses the private key to decrypt the challenge field
 *    contained in the CMMFChallenge.  Make sure the private key matches the
 *    public key that was used to encrypt the witness.  The creator of
 *    the challenge will most likely be an RA that has the public key
 *    from a Cert request.  So the private key should be the private key
 *    associated with public key in that request.  This function will also
 *    verify the witness field of the challenge.
 *
 * RETURN:
 *    SECSuccess if decrypting the witness field was successful.  This does
 *    not indicate that the decrypted data is valid, since the private key
 *    passed in may not be the actual key needed to properly decrypt the
 *    witness field.  Meaning that there is a decrypted structure now, but
 *    may be garbage because the private key was incorrect.
 *    Any other return value indicates the function could not complete the
 *    decryption process.
 */
extern SECStatus CMMF_ChallengeDecryptWitness(CMMFChallenge *inChallenge,
                                              SECKEYPrivateKey *inPrivKey);

/*
 * FUNCTION: CMMF_ChallengeIsDecrypted
 * INPUTS:
 *    inChallenge
 *        The CMMFChallenge to operate on.
 * RETURN:
 *    This is a predicate function that returns PR_TRUE if the decryption
 *    process has already been performed.  The function return PR_FALSE if
 *    the decryption process has not been performed yet.
 */
extern PRBool CMMF_ChallengeIsDecrypted(CMMFChallenge *inChallenge);

/*
 * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
 * INPUTS:
 *    inDecKeyCont
 *        The CMMFPOPODecKeyChallContent to free
 * NOTES:
 *    This function frees up all the memory associated with the
 *    CMMFPOPODecKeyChallContent
 * RETURN:
 *    SECSuccess if freeing up all the memory associatd with the
 *    CMMFPOPODecKeyChallContent is successful.  Any other return value
 *    indicates an error while freeing the memory.
 *
 */
extern SECStatus
CMMF_DestroyPOPODecKeyChallContent(CMMFPOPODecKeyChallContent *inDecKeyCont);