crmffut.h (13218B)
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 /* 6 * These functions to be implemented in the future if the features 7 * which these functions would implement wind up being needed. 8 */ 9 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); 21 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); 30 31 /* 32 * Only call this function on a CRMFPublicationInfo that was created by 33 * CRMF_CreatePKIPublicationInfo that was passed in NULL for arena. 34 */ 35 36 extern SECStatus 37 CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo); 38 39 extern SECStatus CRMF_AddPubInfoControl(CRMFCertRequest *inCertReq, 40 CRMFPKIPublicationInfo *inPubInfo); 41 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); 48 49 extern SECStatus CRMF_DestroyCertID(CRMFCertID *certID); 50 51 extern SECStatus CRMF_AddCertIDControl(CRMFCertRequest *inCertReq, 52 CRMFCertID *certID); 53 54 extern SECStatus 55 CRMF_AddProtocolEncryptioKeyControl(CRMFCertRequest *inCertReq, 56 CERTSubjectPublicKeyInfo *spki); 57 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); 65 66 /* 67 * This takes a CertRequest and adds it to another CertRequest. 68 */ 69 extern SECStatus 70 CRMF_AddCertReqToRegInfo(CRMFCertRequest *certReqToAddTo, 71 CRMFCertRequest *certReqBeingAdded); 72 73 /* 74 * Returns which option was used for the authInfo field of POPOSigningKeyInput 75 */ 76 extern CRMFPOPOSkiInputAuthChoice 77 CRMF_GetSignKeyInputAuthChoice(CRMFPOPOSigningKeyInput *inKeyInput); 78 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); 95 96 /* 97 * Return the value for the PKIPublicationInfo Control. 98 * A return value of NULL indicates that the Control was 99 * not a PKIPublicationInfo Control. Call 100 * CRMF_DestroyPKIPublicationInfo on the return value when done 101 * using the pointer. 102 */ 103 extern CRMFPKIPublicationInfo *CRMF_GetPKIPubInfo(CRMFControl *inControl); 104 105 /* 106 * Free up a CRMFPKIPublicationInfo structure. 107 */ 108 extern SECStatus 109 CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo); 110 111 /* 112 * Get the choice used for action in this PKIPublicationInfo. 113 */ 114 extern CRMFPublicationAction 115 CRMF_GetPublicationAction(CRMFPKIPublicationInfo *inPubInfo); 116 117 /* 118 * Get the number of pubInfos are stored in the PKIPubicationInfo. 119 */ 120 extern int CRMF_GetNumPubInfos(CRMFPKIPublicationInfo *inPubInfo); 121 122 /* 123 * Get the pubInfo at index for the given PKIPubicationInfo. 124 * Indexing is done like a traditional C Array. (0 .. numElements-1) 125 */ 126 extern CRMFSinglePubInfo * 127 CRMF_GetPubInfoAtIndex(CRMFPKIPublicationInfo *inPubInfo, 128 int index); 129 130 /* 131 * Destroy the CRMFSinglePubInfo. 132 */ 133 extern SECStatus CRMF_DestroySinglePubInfo(CRMFSinglePubInfo *inPubInfo); 134 135 /* 136 * Get the pubMethod used by the SinglePubInfo. 137 */ 138 extern CRMFPublicationMethod 139 CRMF_GetPublicationMethod(CRMFSinglePubInfo *inPubInfo); 140 141 /* 142 * Get the pubLocation associated with the SinglePubInfo. 143 * A NULL return value indicates there was no pubLocation associated 144 * with the SinglePuInfo. 145 */ 146 extern CRMFGeneralName *CRMF_GetPubLocation(CRMFSinglePubInfo *inPubInfo); 147 148 /* 149 * Get the authInfo.sender field out of the POPOSigningKeyInput. 150 * If the POPOSigningKeyInput did not use the authInfo the function 151 * returns SECFailure and the value at *destName is unchanged. 152 * 153 * If the POPOSigningKeyInput did use authInfo.sender, the function returns 154 * SECSuccess and puts the authInfo.sender at *destName/ 155 */ 156 extern SECStatus CRMF_GetSignKeyInputSender(CRMFPOPOSigningKeyInput *keyInput, 157 CRMFGeneralName **destName); 158 159 /**************** CMMF Functions that need to be added. **********************/ 160 161 /* 162 * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge 163 * INPUTS: 164 * inDecKeyChall 165 * The CMMFPOPODecKeyChallContent to operate on. 166 * inRandom 167 * The random number to use when generating the challenge, 168 * inSender 169 * The GeneralName representation of the sender of the challenge. 170 * inPubKey 171 * The public key to use when encrypting the challenge. 172 * NOTES: 173 * This function adds a challenge to the end of the list of challenges 174 * contained by 'inDecKeyChall'. Refer to the CMMF draft on how the 175 * the random number passed in and the sender's GeneralName are used 176 * to generate the challenge and witness fields of the challenge. This 177 * library will use SHA1 as the one-way function for generating the 178 * witess field of the challenge. 179 * 180 * RETURN: 181 * SECSuccess if generating the challenge and adding to the end of list 182 * of challenges was successful. Any other return value indicates an error 183 * while trying to generate the challenge. 184 */ 185 extern SECStatus 186 CMMF_POPODecKeyChallContentSetNextChallenge(CMMFPOPODecKeyChallContent *inDecKeyChall, 187 long inRandom, 188 CERTGeneralName *inSender, 189 SECKEYPublicKey *inPubKey); 190 191 /* 192 * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges 193 * INPUTS: 194 * inKeyChallCont 195 * The CMMFPOPODecKeyChallContent to operate on. 196 * RETURN: 197 * This function returns the number of CMMFChallenges are contained in 198 * the CMMFPOPODecKeyChallContent structure. 199 */ 200 extern int CMMF_POPODecKeyChallContentGetNumChallenges(CMMFPOPODecKeyChallContent *inKeyChallCont); 201 202 /* 203 * FUNCTION: CMMF_ChallengeGetRandomNumber 204 * INPUTS: 205 * inChallenge 206 * The CMMFChallenge to operate on. 207 * inDest 208 * A pointer to a user supplied buffer where the library 209 * can place a copy of the random integer contatained in the 210 * challenge. 211 * NOTES: 212 * This function returns the value held in the decrypted Rand structure 213 * corresponding to the random integer. The user must call 214 * CMMF_ChallengeDecryptWitness before calling this function. Call 215 * CMMF_ChallengeIsDecrypted to find out if the challenge has been 216 * decrypted. 217 * 218 * RETURN: 219 * SECSuccess indicates the witness field has been previously decrypted 220 * and the value for the random integer was successfully placed at *inDest. 221 * Any other return value indicates an error and that the value at *inDest 222 * is not a valid value. 223 */ 224 extern SECStatus CMMF_ChallengeGetRandomNumber(CMMFChallenge *inChallenge, 225 long *inDest); 226 227 /* 228 * FUNCTION: CMMF_ChallengeGetSender 229 * INPUTS: 230 * inChallenge 231 * the CMMFChallenge to operate on. 232 * NOTES: 233 * This function returns the value held in the decrypted Rand structure 234 * corresponding to the sender. The user must call 235 * CMMF_ChallengeDecryptWitness before calling this function. Call 236 * CMMF_ChallengeIsDecrypted to find out if the witness field has been 237 * decrypted. The user must call CERT_DestroyGeneralName after the return 238 * value is no longer needed. 239 * 240 * RETURN: 241 * A pointer to a copy of the sender CERTGeneralName. A return value of 242 * NULL indicates an error in trying to copy the information or that the 243 * witness field has not been decrypted. 244 */ 245 extern CERTGeneralName *CMMF_ChallengeGetSender(CMMFChallenge *inChallenge); 246 247 /* 248 * FUNCTION: CMMF_ChallengeGetAlgId 249 * INPUTS: 250 * inChallenge 251 * The CMMFChallenge to operate on. 252 * inDestAlgId 253 * A pointer to memory where a pointer to a copy of the algorithm 254 * id can be placed. 255 * NOTES: 256 * This function retrieves the one way function algorithm identifier 257 * contained within the CMMFChallenge if the optional field is present. 258 * 259 * RETURN: 260 * SECSucces indicates the function was able to place a pointer to a copy of 261 * the alogrithm id at *inAlgId. If the value at *inDestAlgId is NULL, 262 * that means there was no algorithm identifier present in the 263 * CMMFChallenge. Any other return value indicates the function was not 264 * able to make a copy of the algorithm identifier. In this case the value 265 * at *inDestAlgId is not valid. 266 */ 267 extern SECStatus CMMF_ChallengeGetAlgId(CMMFChallenge *inChallenge, 268 SECAlgorithmID *inAlgId); 269 270 /* 271 * FUNCTION: CMMF_DestroyChallenge 272 * INPUTS: 273 * inChallenge 274 * The CMMFChallenge to free up. 275 * NOTES: 276 * This function frees up all the memory associated with the CMMFChallenge 277 * passed in. 278 * RETURN: 279 * SECSuccess if freeing all the memory associated with the CMMFChallenge 280 * passed in is successful. Any other return value indicates an error 281 * while freeing the memory. 282 */ 283 extern SECStatus CMMF_DestroyChallenge(CMMFChallenge *inChallenge); 284 285 /* 286 * FUNCTION: CMMF_DestroyPOPODecKeyRespContent 287 * INPUTS: 288 * inDecKeyResp 289 * The CMMFPOPODecKeyRespContent structure to free. 290 * NOTES: 291 * This function frees up all the memory associate with the 292 * CMMFPOPODecKeyRespContent. 293 * 294 * RETURN: 295 * SECSuccess if freeint up all the memory associated with the 296 * CMMFPOPODecKeyRespContent structure is successful. Any other 297 * return value indicates an error while freeing the memory. 298 */ 299 extern SECStatus 300 CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp); 301 302 /* 303 * FUNCTION: CMMF_ChallengeDecryptWitness 304 * INPUTS: 305 * inChallenge 306 * The CMMFChallenge to operate on. 307 * inPrivKey 308 * The private key to use to decrypt the witness field. 309 * NOTES: 310 * This function uses the private key to decrypt the challenge field 311 * contained in the CMMFChallenge. Make sure the private key matches the 312 * public key that was used to encrypt the witness. The creator of 313 * the challenge will most likely be an RA that has the public key 314 * from a Cert request. So the private key should be the private key 315 * associated with public key in that request. This function will also 316 * verify the witness field of the challenge. 317 * 318 * RETURN: 319 * SECSuccess if decrypting the witness field was successful. This does 320 * not indicate that the decrypted data is valid, since the private key 321 * passed in may not be the actual key needed to properly decrypt the 322 * witness field. Meaning that there is a decrypted structure now, but 323 * may be garbage because the private key was incorrect. 324 * Any other return value indicates the function could not complete the 325 * decryption process. 326 */ 327 extern SECStatus CMMF_ChallengeDecryptWitness(CMMFChallenge *inChallenge, 328 SECKEYPrivateKey *inPrivKey); 329 330 /* 331 * FUNCTION: CMMF_ChallengeIsDecrypted 332 * INPUTS: 333 * inChallenge 334 * The CMMFChallenge to operate on. 335 * RETURN: 336 * This is a predicate function that returns PR_TRUE if the decryption 337 * process has already been performed. The function return PR_FALSE if 338 * the decryption process has not been performed yet. 339 */ 340 extern PRBool CMMF_ChallengeIsDecrypted(CMMFChallenge *inChallenge); 341 342 /* 343 * FUNCTION: CMMF_DestroyPOPODecKeyChallContent 344 * INPUTS: 345 * inDecKeyCont 346 * The CMMFPOPODecKeyChallContent to free 347 * NOTES: 348 * This function frees up all the memory associated with the 349 * CMMFPOPODecKeyChallContent 350 * RETURN: 351 * SECSuccess if freeing up all the memory associatd with the 352 * CMMFPOPODecKeyChallContent is successful. Any other return value 353 * indicates an error while freeing the memory. 354 * 355 */ 356 extern SECStatus 357 CMMF_DestroyPOPODecKeyChallContent(CMMFPOPODecKeyChallContent *inDecKeyCont);