← Back to branch summary

~ubuntu-branches/ubuntu/precise/kompozer/precise

« back to all changes in this revision

Viewing changes to mozilla/security/nss/lib/crmf/crmffut.h

  • Committer: Bazaar Package Importer
  • Author(s): Anthony Yarusso
  • Date: 2007-08-27 01:11:03 UTC
  • Revision ID: james.westby@ubuntu.com-20070827011103-2jgf4s6532gqu2ka
Tags: upstream-0.7.10
Import upstream version 0.7.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
mozilla/security/nss/lib/crmf/crmffut.h
 
1
/*
 
2
 * The contents of this file are subject to the Mozilla Public
 
3
 * License Version 1.1 (the "License"); you may not use this file
 
4
 * except in compliance with the License. You may obtain a copy of
 
5
 * the License at http://www.mozilla.org/MPL/
 
6
 * 
 
7
 * Software distributed under the License is distributed on an "AS
 
8
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 
9
 * implied. See the License for the specific language governing
 
10
 * rights and limitations under the License.
 
11
 * 
 
12
 * The Original Code is the Netscape security libraries.
 
13
 * 
 
14
 * The Initial Developer of the Original Code is Netscape
 
15
 * Communications Corporation.  Portions created by Netscape are 
 
16
 * Copyright (C) 1994-2000 Netscape Communications Corporation.  All
 
17
 * Rights Reserved.
 
18
 * 
 
19
 * Contributor(s):
 
20
 * 
 
21
 * Alternatively, the contents of this file may be used under the
 
22
 * terms of the GNU General Public License Version 2 or later (the
 
23
 * "GPL"), in which case the provisions of the GPL are applicable 
 
24
 * instead of those above.  If you wish to allow use of your 
 
25
 * version of this file only under the terms of the GPL and not to
 
26
 * allow others to use your version of this file under the MPL,
 
27
 * indicate your decision by deleting the provisions above and
 
28
 * replace them with the notice and other provisions required by
 
29
 * the GPL.  If you do not delete the provisions above, a recipient
 
30
 * may use your version of this file under either the MPL or the
 
31
 * GPL.
 
32
 */
 
33
 
 
34
/*
 
35
 * These functions to be implemented in the future if the features
 
36
 * which these functions would implement wind up being needed.
 
37
 */
 
38
 
 
39
/*
 
40
 * Use this functionto create the CRMFSinglePubInfo* variables that will 
 
41
 * populate the inPubInfoArray paramter for the funciton
 
42
 * CRMF_CreatePKIPublicationInfo.
 
43
 *
 
44
 * "inPubMethod" specifies which publication method will be used
 
45
 * "pubLocation" is a representation of the location where 
 
46
 */
 
47
extern CRMFSinglePubInfo* 
 
48
      CRMF_CreateSinglePubInfo(CRMFPublicationMethod  inPubMethod,
 
49
                               CRMFGeneralName       *pubLocation);
 
50
 
 
51
/*
 
52
 * Create a PKIPublicationInfo that can later be passed to the function
 
53
 * CRMFAddPubInfoControl.
 
54
 */
 
55
extern CRMFPKIPublicationInfo *
 
56
     CRMF_CreatePKIPublicationInfo(CRMFPublicationAction  inAction,
 
57
                                   CRMFSinglePubInfo    **inPubInfoArray,
 
58
                                   int                    numPubInfo);
 
59
 
 
60
/*
 
61
 * Only call this function on a CRMFPublicationInfo that was created by
 
62
 * CRMF_CreatePKIPublicationInfo that was passed in NULL for arena.
 
63
 */
 
64
 
 
65
extern SECStatus 
 
66
       CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
 
67
 
 
68
extern SECStatus CRMF_AddPubInfoControl(CRMFCertRequest        *inCertReq,
 
69
                                        CRMFPKIPublicationInfo *inPubInfo);
 
70
 
 
71
/*
 
72
 * This is to create a Cert ID Control which can later be added to 
 
73
 * a certificate request.
 
74
 */
 
75
extern CRMFCertID* CRMF_CreateCertID(CRMFGeneralName *issuer,
 
76
                                     long             serialNumber);
 
77
 
 
78
extern SECStatus CRMF_DestroyCertID(CRMFCertID* certID);
 
79
 
 
80
extern SECStatus CRMF_AddCertIDControl(CRMFCertRequest *inCertReq,
 
81
                                       CRMFCertID      *certID);
 
82
 
 
83
extern SECStatus 
 
84
       CRMF_AddProtocolEncryptioKeyControl(CRMFCertRequest          *inCertReq,
 
85
                                           CERTSubjectPublicKeyInfo *spki);
 
86
 
 
87
/*
 
88
 * Add the ASCII Pairs Registration Info to the Certificate Request.
 
89
 * The SECItem must be an OCTET string representation.
 
90
 */
 
91
extern SECStatus
 
92
       CRMF_AddUTF8PairsRegInfo(CRMFCertRequest *inCertReq,
 
93
                                 SECItem         *asciiPairs);
 
94
 
 
95
/*
 
96
 * This takes a CertRequest and adds it to another CertRequest.  
 
97
 */
 
98
extern SECStatus
 
99
       CRMF_AddCertReqToRegInfo(CRMFCertRequest *certReqToAddTo,
 
100
                                CRMFCertRequest *certReqBeingAdded);
 
101
 
 
102
/*
 
103
 * Returns which option was used for the authInfo field of POPOSigningKeyInput
 
104
 */
 
105
extern CRMFPOPOSkiInputAuthChoice 
 
106
       CRMF_GetSignKeyInputAuthChoice(CRMFPOPOSigningKeyInput *inKeyInput);
 
107
 
 
108
/*
 
109
 * Gets the PKMACValue associated with the POPOSigningKeyInput.
 
110
 * If the POPOSigningKeyInput did not use authInfo.publicKeyMAC 
 
111
 * the function returns SECFailure and the value at *destValue is unchanged.
 
112
 *
 
113
 * If the POPOSigningKeyInput did use authInfo.publicKeyMAC, the function
 
114
 * returns SECSuccess and places the PKMACValue at *destValue.
 
115
 */
 
116
extern SECStatus 
 
117
       CRMF_GetSignKeyInputPKMACValue(CRMFPOPOSigningKeyInput *inKeyInput,
 
118
                                      CRMFPKMACValue          **destValue);
 
119
/*
 
120
 * Gets the SubjectPublicKeyInfo from the POPOSigningKeyInput
 
121
 */
 
122
extern CERTSubjectPublicKeyInfo *
 
123
       CRMF_GetSignKeyInputPublicKey(CRMFPOPOSigningKeyInput *inKeyInput);
 
124
 
 
125
 
 
126
/*
 
127
 * Return the value for the PKIPublicationInfo Control.
 
128
 * A return value of NULL indicates that the Control was 
 
129
 * not a PKIPublicationInfo Control.  Call 
 
130
 * CRMF_DestroyPKIPublicationInfo on the return value when done
 
131
 * using the pointer.
 
132
 */
 
133
extern CRMFPKIPublicationInfo* CRMF_GetPKIPubInfo(CRMFControl *inControl);
 
134
 
 
135
/*
 
136
 * Free up a CRMFPKIPublicationInfo structure.
 
137
 */
 
138
extern SECStatus 
 
139
       CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
 
140
 
 
141
/*
 
142
 * Get the choice used for action in this PKIPublicationInfo.
 
143
 */
 
144
extern CRMFPublicationAction 
 
145
       CRMF_GetPublicationAction(CRMFPKIPublicationInfo *inPubInfo);
 
146
 
 
147
/*
 
148
 * Get the number of pubInfos are stored in the PKIPubicationInfo.
 
149
 */
 
150
extern int CRMF_GetNumPubInfos(CRMFPKIPublicationInfo *inPubInfo);
 
151
 
 
152
/*
 
153
 * Get the pubInfo at index for the given PKIPubicationInfo.
 
154
 * Indexing is done like a traditional C Array. (0 .. numElements-1)
 
155
 */
 
156
extern CRMFSinglePubInfo* 
 
157
       CRMF_GetPubInfoAtIndex(CRMFPKIPublicationInfo *inPubInfo,
 
158
                              int                     index);
 
159
 
 
160
/*
 
161
 * Destroy the CRMFSinglePubInfo.
 
162
 */
 
163
extern SECStatus CRMF_DestroySinglePubInfo(CRMFSinglePubInfo *inPubInfo);
 
164
 
 
165
/*
 
166
 * Get the pubMethod used by the SinglePubInfo.
 
167
 */
 
168
extern CRMFPublicationMethod 
 
169
       CRMF_GetPublicationMethod(CRMFSinglePubInfo *inPubInfo);
 
170
 
 
171
/*
 
172
 * Get the pubLocation associated with the SinglePubInfo.
 
173
 * A NULL return value indicates there was no pubLocation associated
 
174
 * with the SinglePuInfo.
 
175
 */
 
176
extern CRMFGeneralName* CRMF_GetPubLocation(CRMFSinglePubInfo *inPubInfo);
 
177
 
 
178
/*
 
179
 * Get the authInfo.sender field out of the POPOSigningKeyInput.
 
180
 * If the POPOSigningKeyInput did not use the authInfo the function
 
181
 * returns SECFailure and the value at *destName is unchanged.
 
182
 *
 
183
 * If the POPOSigningKeyInput did use authInfo.sender, the function returns
 
184
 * SECSuccess and puts the authInfo.sender at *destName/
 
185
 */
 
186
extern SECStatus CRMF_GetSignKeyInputSender(CRMFPOPOSigningKeyInput *keyInput,
 
187
                                            CRMFGeneralName        **destName);
 
188
 
 
189
/**************** CMMF Functions that need to be added. **********************/
 
190
 
 
191
/*
 
192
 * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
 
193
 * INPUTS:
 
194
 *    inDecKeyChall
 
195
 *        The CMMFPOPODecKeyChallContent to operate on.
 
196
 *    inRandom
 
197
 *        The random number to use when generating the challenge,
 
198
 *    inSender
 
199
 *        The GeneralName representation of the sender of the challenge.
 
200
 *    inPubKey
 
201
 *        The public key to use when encrypting the challenge.
 
202
 * NOTES:
 
203
 *    This function adds a challenge to the end of the list of challenges
 
204
 *    contained by 'inDecKeyChall'.  Refer to the CMMF draft on how the
 
205
 *    the random number passed in and the sender's GeneralName are used
 
206
 *    to generate the challenge and witness fields of the challenge.  This
 
207
 *    library will use SHA1 as the one-way function for generating the 
 
208
 *    witess field of the challenge.
 
209
 *
 
210
 * RETURN:
 
211
 *    SECSuccess if generating the challenge and adding to the end of list
 
212
 *    of challenges was successful.  Any other return value indicates an error
 
213
 *    while trying to generate the challenge.
 
214
 */
 
215
extern SECStatus
 
216
CMMF_POPODecKeyChallContentSetNextChallenge
 
217
                                   (CMMFPOPODecKeyChallContent *inDecKeyChall,
 
218
                                    long                        inRandom,
 
219
                                    CERTGeneralName            *inSender,
 
220
                                    SECKEYPublicKey            *inPubKey);
 
221
 
 
222
/*
 
223
 * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
 
224
 * INPUTS:
 
225
 *    inKeyChallCont
 
226
 *        The CMMFPOPODecKeyChallContent to operate on.
 
227
 * RETURN:
 
228
 *    This function returns the number of CMMFChallenges are contained in 
 
229
 *    the CMMFPOPODecKeyChallContent structure.
 
230
 */
 
231
extern int CMMF_POPODecKeyChallContentGetNumChallenges
 
232
                                  (CMMFPOPODecKeyChallContent *inKeyChallCont);
 
233
 
 
234
/*
 
235
 * FUNCTION: CMMF_ChallengeGetRandomNumber
 
236
 * INPUTS:
 
237
 *    inChallenge
 
238
 *        The CMMFChallenge to operate on.
 
239
 *    inDest
 
240
 *        A pointer to a user supplied buffer where the library
 
241
 *        can place a copy of the random integer contatained in the
 
242
 *        challenge.
 
243
 * NOTES:
 
244
 *    This function returns the value held in the decrypted Rand structure
 
245
 *    corresponding to the random integer.  The user must call 
 
246
 *    CMMF_ChallengeDecryptWitness before calling this function.  Call 
 
247
 *    CMMF_ChallengeIsDecrypted to find out if the challenge has been 
 
248
 *    decrypted.
 
249
 *
 
250
 * RETURN:
 
251
 *    SECSuccess indicates the witness field has been previously decrypted
 
252
 *    and the value for the random integer was successfully placed at *inDest.
 
253
 *    Any other return value indicates an error and that the value at *inDest
 
254
 *    is not a valid value.
 
255
 */
 
256
extern SECStatus CMMF_ChallengeGetRandomNumber(CMMFChallenge *inChallenge,
 
257
                                               long          *inDest);
 
258
 
 
259
/*
 
260
 * FUNCTION: CMMF_ChallengeGetSender
 
261
 * INPUTS:
 
262
 *    inChallenge
 
263
 *        the CMMFChallenge to operate on.
 
264
 * NOTES:
 
265
 *    This function returns the value held in the decrypted Rand structure
 
266
 *    corresponding to the sender.  The user must call 
 
267
 *    CMMF_ChallengeDecryptWitness before calling this function.  Call 
 
268
 *    CMMF_ChallengeIsDecrypted to find out if the witness field has been
 
269
 *    decrypted.  The user must call CERT_DestroyGeneralName after the return
 
270
 *    value is no longer needed.
 
271
 *
 
272
 * RETURN:
 
273
 *    A pointer to a copy of the sender CERTGeneralName.  A return value of
 
274
 *    NULL indicates an error in trying to copy the information or that the
 
275
 *    witness field has not been decrypted.
 
276
 */
 
277
extern CERTGeneralName* CMMF_ChallengeGetSender(CMMFChallenge *inChallenge);
 
278
 
 
279
/*
 
280
 * FUNCTION: CMMF_ChallengeGetAlgId
 
281
 * INPUTS:
 
282
 *    inChallenge
 
283
 *        The CMMFChallenge to operate on.
 
284
 *    inDestAlgId
 
285
 *        A pointer to memory where a pointer to a copy of the algorithm
 
286
 *        id can be placed.
 
287
 * NOTES:
 
288
 *    This function retrieves the one way function algorithm identifier 
 
289
 *    contained within the CMMFChallenge if the optional field is present.
 
290
 *
 
291
 * RETURN:
 
292
 *    SECSucces indicates the function was able to place a pointer to a copy of
 
293
 *    the alogrithm id at *inAlgId.  If the value at *inDestAlgId is NULL, 
 
294
 *    that means there was no algorithm identifier present in the 
 
295
 *    CMMFChallenge.  Any other return value indicates the function was not 
 
296
 *    able to make a copy of the algorithm identifier.  In this case the value 
 
297
 *    at *inDestAlgId is not valid.
 
298
 */
 
299
extern SECStatus CMMF_ChallengeGetAlgId(CMMFChallenge  *inChallenge,
 
300
                                        SECAlgorithmID *inAlgId);
 
301
 
 
302
/*
 
303
 * FUNCTION: CMMF_DestroyChallenge
 
304
 * INPUTS:
 
305
 *    inChallenge
 
306
 *        The CMMFChallenge to free up.
 
307
 * NOTES:
 
308
 *    This function frees up all the memory associated with the CMMFChallenge 
 
309
 *    passed in.
 
310
 * RETURN:
 
311
 *    SECSuccess if freeing all the memory associated with the CMMFChallenge
 
312
 *    passed in is successful.  Any other return value indicates an error 
 
313
 *    while freeing the memory.
 
314
 */
 
315
extern SECStatus CMMF_DestroyChallenge (CMMFChallenge *inChallenge);
 
316
 
 
317
/*
 
318
 * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
 
319
 * INPUTS:
 
320
 *    inDecKeyResp
 
321
 *        The CMMFPOPODecKeyRespContent structure to free.
 
322
 * NOTES:
 
323
 *    This function frees up all the memory associate with the 
 
324
 *    CMMFPOPODecKeyRespContent.
 
325
 *
 
326
 * RETURN:
 
327
 *    SECSuccess if freeint up all the memory associated with the
 
328
 *    CMMFPOPODecKeyRespContent structure is successful.  Any other
 
329
 *    return value indicates an error while freeing the memory.
 
330
 */
 
331
extern SECStatus
 
332
     CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
 
333
 
 
334
/*
 
335
 * FUNCTION: CMMF_ChallengeDecryptWitness
 
336
 * INPUTS:
 
337
 *    inChallenge
 
338
 *        The CMMFChallenge to operate on.
 
339
 *    inPrivKey
 
340
 *        The private key to use to decrypt the witness field.
 
341
 * NOTES:
 
342
 *    This function uses the private key to decrypt the challenge field
 
343
 *    contained in the CMMFChallenge.  Make sure the private key matches the
 
344
 *    public key that was used to encrypt the witness.  The creator of 
 
345
 *    the challenge will most likely be an RA that has the public key
 
346
 *    from a Cert request.  So the private key should be the private key
 
347
 *    associated with public key in that request.  This function will also
 
348
 *    verify the witness field of the challenge.
 
349
 *
 
350
 * RETURN:
 
351
 *    SECSuccess if decrypting the witness field was successful.  This does
 
352
 *    not indicate that the decrypted data is valid, since the private key 
 
353
 *    passed in may not be the actual key needed to properly decrypt the 
 
354
 *    witness field.  Meaning that there is a decrypted structure now, but
 
355
 *    may be garbage because the private key was incorrect.
 
356
 *    Any other return value indicates the function could not complete the
 
357
 *    decryption process.
 
358
 */
 
359
extern SECStatus CMMF_ChallengeDecryptWitness(CMMFChallenge    *inChallenge,
 
360
                                              SECKEYPrivateKey *inPrivKey);
 
361
 
 
362
/*
 
363
 * FUNCTION: CMMF_ChallengeIsDecrypted
 
364
 * INPUTS:
 
365
 *    inChallenge
 
366
 *        The CMMFChallenge to operate on.
 
367
 * RETURN:
 
368
 *    This is a predicate function that returns PR_TRUE if the decryption 
 
369
 *    process has already been performed.  The function return PR_FALSE if 
 
370
 *    the decryption process has not been performed yet.
 
371
 */
 
372
extern PRBool CMMF_ChallengeIsDecrypted(CMMFChallenge *inChallenge);
 
373
 
 
374
/*
 
375
 * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
 
376
 * INPUTS:
 
377
 *    inDecKeyCont
 
378
 *        The CMMFPOPODecKeyChallContent to free
 
379
 * NOTES:
 
380
 *    This function frees up all the memory associated with the 
 
381
 *    CMMFPOPODecKeyChallContent 
 
382
 * RETURN:
 
383
 *    SECSuccess if freeing up all the memory associatd with the 
 
384
 *    CMMFPOPODecKeyChallContent is successful.  Any other return value
 
385
 *    indicates an error while freeing the memory.
 
386
 *
 
387
 */
 
388
extern SECStatus 
 
389
 CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
 
390