security/nss/lib/crmf/crmffut.h@6474c204b198
security/nss/lib/crmf/crmffut.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
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/. */
5 /*
6 * These functions to be implemented in the future if the features
7 * which these functions would implement wind up being needed.
8 */
10 /*
11 * Use this function to create the CRMFSinglePubInfo* variables that will
12 * populate the inPubInfoArray parameter for the function
13 * CRMF_CreatePKIPublicationInfo.
14 *
15 * "inPubMethod" specifies which publication method will be used
16 * "pubLocation" is a representation of the location where
17 */
18 extern CRMFSinglePubInfo*
19 CRMF_CreateSinglePubInfo(CRMFPublicationMethod inPubMethod,
20 CRMFGeneralName *pubLocation);
22 /*
23 * Create a PKIPublicationInfo that can later be passed to the function
24 * CRMFAddPubInfoControl.
25 */
26 extern CRMFPKIPublicationInfo *
27 CRMF_CreatePKIPublicationInfo(CRMFPublicationAction inAction,
28 CRMFSinglePubInfo **inPubInfoArray,
29 int numPubInfo);
31 /*
32 * Only call this function on a CRMFPublicationInfo that was created by
33 * CRMF_CreatePKIPublicationInfo that was passed in NULL for arena.
34 */
36 extern SECStatus
37 CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
39 extern SECStatus CRMF_AddPubInfoControl(CRMFCertRequest *inCertReq,
40 CRMFPKIPublicationInfo *inPubInfo);
42 /*
43 * This is to create a Cert ID Control which can later be added to
44 * a certificate request.
45 */
46 extern CRMFCertID* CRMF_CreateCertID(CRMFGeneralName *issuer,
47 long serialNumber);
49 extern SECStatus CRMF_DestroyCertID(CRMFCertID* certID);
51 extern SECStatus CRMF_AddCertIDControl(CRMFCertRequest *inCertReq,
52 CRMFCertID *certID);
54 extern SECStatus
55 CRMF_AddProtocolEncryptioKeyControl(CRMFCertRequest *inCertReq,
56 CERTSubjectPublicKeyInfo *spki);
58 /*
59 * Add the ASCII Pairs Registration Info to the Certificate Request.
60 * The SECItem must be an OCTET string representation.
61 */
62 extern SECStatus
63 CRMF_AddUTF8PairsRegInfo(CRMFCertRequest *inCertReq,
64 SECItem *asciiPairs);
66 /*
67 * This takes a CertRequest and adds it to another CertRequest.
68 */
69 extern SECStatus
70 CRMF_AddCertReqToRegInfo(CRMFCertRequest *certReqToAddTo,
71 CRMFCertRequest *certReqBeingAdded);
73 /*
74 * Returns which option was used for the authInfo field of POPOSigningKeyInput
75 */
76 extern CRMFPOPOSkiInputAuthChoice
77 CRMF_GetSignKeyInputAuthChoice(CRMFPOPOSigningKeyInput *inKeyInput);
79 /*
80 * Gets the PKMACValue associated with the POPOSigningKeyInput.
81 * If the POPOSigningKeyInput did not use authInfo.publicKeyMAC
82 * the function returns SECFailure and the value at *destValue is unchanged.
83 *
84 * If the POPOSigningKeyInput did use authInfo.publicKeyMAC, the function
85 * returns SECSuccess and places the PKMACValue at *destValue.
86 */
87 extern SECStatus
88 CRMF_GetSignKeyInputPKMACValue(CRMFPOPOSigningKeyInput *inKeyInput,
89 CRMFPKMACValue **destValue);
90 /*
91 * Gets the SubjectPublicKeyInfo from the POPOSigningKeyInput
92 */
93 extern CERTSubjectPublicKeyInfo *
94 CRMF_GetSignKeyInputPublicKey(CRMFPOPOSigningKeyInput *inKeyInput);
97 /*
98 * Return the value for the PKIPublicationInfo Control.
99 * A return value of NULL indicates that the Control was
100 * not a PKIPublicationInfo Control. Call
101 * CRMF_DestroyPKIPublicationInfo on the return value when done
102 * using the pointer.
103 */
104 extern CRMFPKIPublicationInfo* CRMF_GetPKIPubInfo(CRMFControl *inControl);
106 /*
107 * Free up a CRMFPKIPublicationInfo structure.
108 */
109 extern SECStatus
110 CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
112 /*
113 * Get the choice used for action in this PKIPublicationInfo.
114 */
115 extern CRMFPublicationAction
116 CRMF_GetPublicationAction(CRMFPKIPublicationInfo *inPubInfo);
118 /*
119 * Get the number of pubInfos are stored in the PKIPubicationInfo.
120 */
121 extern int CRMF_GetNumPubInfos(CRMFPKIPublicationInfo *inPubInfo);
123 /*
124 * Get the pubInfo at index for the given PKIPubicationInfo.
125 * Indexing is done like a traditional C Array. (0 .. numElements-1)
126 */
127 extern CRMFSinglePubInfo*
128 CRMF_GetPubInfoAtIndex(CRMFPKIPublicationInfo *inPubInfo,
129 int index);
131 /*
132 * Destroy the CRMFSinglePubInfo.
133 */
134 extern SECStatus CRMF_DestroySinglePubInfo(CRMFSinglePubInfo *inPubInfo);
136 /*
137 * Get the pubMethod used by the SinglePubInfo.
138 */
139 extern CRMFPublicationMethod
140 CRMF_GetPublicationMethod(CRMFSinglePubInfo *inPubInfo);
142 /*
143 * Get the pubLocation associated with the SinglePubInfo.
144 * A NULL return value indicates there was no pubLocation associated
145 * with the SinglePuInfo.
146 */
147 extern CRMFGeneralName* CRMF_GetPubLocation(CRMFSinglePubInfo *inPubInfo);
149 /*
150 * Get the authInfo.sender field out of the POPOSigningKeyInput.
151 * If the POPOSigningKeyInput did not use the authInfo the function
152 * returns SECFailure and the value at *destName is unchanged.
153 *
154 * If the POPOSigningKeyInput did use authInfo.sender, the function returns
155 * SECSuccess and puts the authInfo.sender at *destName/
156 */
157 extern SECStatus CRMF_GetSignKeyInputSender(CRMFPOPOSigningKeyInput *keyInput,
158 CRMFGeneralName **destName);
160 /**************** CMMF Functions that need to be added. **********************/
162 /*
163 * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
164 * INPUTS:
165 * inDecKeyChall
166 * The CMMFPOPODecKeyChallContent to operate on.
167 * inRandom
168 * The random number to use when generating the challenge,
169 * inSender
170 * The GeneralName representation of the sender of the challenge.
171 * inPubKey
172 * The public key to use when encrypting the challenge.
173 * NOTES:
174 * This function adds a challenge to the end of the list of challenges
175 * contained by 'inDecKeyChall'. Refer to the CMMF draft on how the
176 * the random number passed in and the sender's GeneralName are used
177 * to generate the challenge and witness fields of the challenge. This
178 * library will use SHA1 as the one-way function for generating the
179 * witess field of the challenge.
180 *
181 * RETURN:
182 * SECSuccess if generating the challenge and adding to the end of list
183 * of challenges was successful. Any other return value indicates an error
184 * while trying to generate the challenge.
185 */
186 extern SECStatus
187 CMMF_POPODecKeyChallContentSetNextChallenge
188 (CMMFPOPODecKeyChallContent *inDecKeyChall,
189 long inRandom,
190 CERTGeneralName *inSender,
191 SECKEYPublicKey *inPubKey);
193 /*
194 * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
195 * INPUTS:
196 * inKeyChallCont
197 * The CMMFPOPODecKeyChallContent to operate on.
198 * RETURN:
199 * This function returns the number of CMMFChallenges are contained in
200 * the CMMFPOPODecKeyChallContent structure.
201 */
202 extern int CMMF_POPODecKeyChallContentGetNumChallenges
203 (CMMFPOPODecKeyChallContent *inKeyChallCont);
205 /*
206 * FUNCTION: CMMF_ChallengeGetRandomNumber
207 * INPUTS:
208 * inChallenge
209 * The CMMFChallenge to operate on.
210 * inDest
211 * A pointer to a user supplied buffer where the library
212 * can place a copy of the random integer contatained in the
213 * challenge.
214 * NOTES:
215 * This function returns the value held in the decrypted Rand structure
216 * corresponding to the random integer. The user must call
217 * CMMF_ChallengeDecryptWitness before calling this function. Call
218 * CMMF_ChallengeIsDecrypted to find out if the challenge has been
219 * decrypted.
220 *
221 * RETURN:
222 * SECSuccess indicates the witness field has been previously decrypted
223 * and the value for the random integer was successfully placed at *inDest.
224 * Any other return value indicates an error and that the value at *inDest
225 * is not a valid value.
226 */
227 extern SECStatus CMMF_ChallengeGetRandomNumber(CMMFChallenge *inChallenge,
228 long *inDest);
230 /*
231 * FUNCTION: CMMF_ChallengeGetSender
232 * INPUTS:
233 * inChallenge
234 * the CMMFChallenge to operate on.
235 * NOTES:
236 * This function returns the value held in the decrypted Rand structure
237 * corresponding to the sender. The user must call
238 * CMMF_ChallengeDecryptWitness before calling this function. Call
239 * CMMF_ChallengeIsDecrypted to find out if the witness field has been
240 * decrypted. The user must call CERT_DestroyGeneralName after the return
241 * value is no longer needed.
242 *
243 * RETURN:
244 * A pointer to a copy of the sender CERTGeneralName. A return value of
245 * NULL indicates an error in trying to copy the information or that the
246 * witness field has not been decrypted.
247 */
248 extern CERTGeneralName* CMMF_ChallengeGetSender(CMMFChallenge *inChallenge);
250 /*
251 * FUNCTION: CMMF_ChallengeGetAlgId
252 * INPUTS:
253 * inChallenge
254 * The CMMFChallenge to operate on.
255 * inDestAlgId
256 * A pointer to memory where a pointer to a copy of the algorithm
257 * id can be placed.
258 * NOTES:
259 * This function retrieves the one way function algorithm identifier
260 * contained within the CMMFChallenge if the optional field is present.
261 *
262 * RETURN:
263 * SECSucces indicates the function was able to place a pointer to a copy of
264 * the alogrithm id at *inAlgId. If the value at *inDestAlgId is NULL,
265 * that means there was no algorithm identifier present in the
266 * CMMFChallenge. Any other return value indicates the function was not
267 * able to make a copy of the algorithm identifier. In this case the value
268 * at *inDestAlgId is not valid.
269 */
270 extern SECStatus CMMF_ChallengeGetAlgId(CMMFChallenge *inChallenge,
271 SECAlgorithmID *inAlgId);
273 /*
274 * FUNCTION: CMMF_DestroyChallenge
275 * INPUTS:
276 * inChallenge
277 * The CMMFChallenge to free up.
278 * NOTES:
279 * This function frees up all the memory associated with the CMMFChallenge
280 * passed in.
281 * RETURN:
282 * SECSuccess if freeing all the memory associated with the CMMFChallenge
283 * passed in is successful. Any other return value indicates an error
284 * while freeing the memory.
285 */
286 extern SECStatus CMMF_DestroyChallenge (CMMFChallenge *inChallenge);
288 /*
289 * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
290 * INPUTS:
291 * inDecKeyResp
292 * The CMMFPOPODecKeyRespContent structure to free.
293 * NOTES:
294 * This function frees up all the memory associate with the
295 * CMMFPOPODecKeyRespContent.
296 *
297 * RETURN:
298 * SECSuccess if freeint up all the memory associated with the
299 * CMMFPOPODecKeyRespContent structure is successful. Any other
300 * return value indicates an error while freeing the memory.
301 */
302 extern SECStatus
303 CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
305 /*
306 * FUNCTION: CMMF_ChallengeDecryptWitness
307 * INPUTS:
308 * inChallenge
309 * The CMMFChallenge to operate on.
310 * inPrivKey
311 * The private key to use to decrypt the witness field.
312 * NOTES:
313 * This function uses the private key to decrypt the challenge field
314 * contained in the CMMFChallenge. Make sure the private key matches the
315 * public key that was used to encrypt the witness. The creator of
316 * the challenge will most likely be an RA that has the public key
317 * from a Cert request. So the private key should be the private key
318 * associated with public key in that request. This function will also
319 * verify the witness field of the challenge.
320 *
321 * RETURN:
322 * SECSuccess if decrypting the witness field was successful. This does
323 * not indicate that the decrypted data is valid, since the private key
324 * passed in may not be the actual key needed to properly decrypt the
325 * witness field. Meaning that there is a decrypted structure now, but
326 * may be garbage because the private key was incorrect.
327 * Any other return value indicates the function could not complete the
328 * decryption process.
329 */
330 extern SECStatus CMMF_ChallengeDecryptWitness(CMMFChallenge *inChallenge,
331 SECKEYPrivateKey *inPrivKey);
333 /*
334 * FUNCTION: CMMF_ChallengeIsDecrypted
335 * INPUTS:
336 * inChallenge
337 * The CMMFChallenge to operate on.
338 * RETURN:
339 * This is a predicate function that returns PR_TRUE if the decryption
340 * process has already been performed. The function return PR_FALSE if
341 * the decryption process has not been performed yet.
342 */
343 extern PRBool CMMF_ChallengeIsDecrypted(CMMFChallenge *inChallenge);
345 /*
346 * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
347 * INPUTS:
348 * inDecKeyCont
349 * The CMMFPOPODecKeyChallContent to free
350 * NOTES:
351 * This function frees up all the memory associated with the
352 * CMMFPOPODecKeyChallContent
353 * RETURN:
354 * SECSuccess if freeing up all the memory associatd with the
355 * CMMFPOPODecKeyChallContent is successful. Any other return value
356 * indicates an error while freeing the memory.
357 *
358 */
359 extern SECStatus
360 CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
