1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/crmf/crmffut.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,361 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +/*
1.9 + * These functions to be implemented in the future if the features
1.10 + * which these functions would implement wind up being needed.
1.11 + */
1.12 +
1.13 +/*
1.14 + * Use this function to create the CRMFSinglePubInfo* variables that will
1.15 + * populate the inPubInfoArray parameter for the function
1.16 + * CRMF_CreatePKIPublicationInfo.
1.17 + *
1.18 + * "inPubMethod" specifies which publication method will be used
1.19 + * "pubLocation" is a representation of the location where
1.20 + */
1.21 +extern CRMFSinglePubInfo*
1.22 + CRMF_CreateSinglePubInfo(CRMFPublicationMethod inPubMethod,
1.23 + CRMFGeneralName *pubLocation);
1.24 +
1.25 +/*
1.26 + * Create a PKIPublicationInfo that can later be passed to the function
1.27 + * CRMFAddPubInfoControl.
1.28 + */
1.29 +extern CRMFPKIPublicationInfo *
1.30 + CRMF_CreatePKIPublicationInfo(CRMFPublicationAction inAction,
1.31 + CRMFSinglePubInfo **inPubInfoArray,
1.32 + int numPubInfo);
1.33 +
1.34 +/*
1.35 + * Only call this function on a CRMFPublicationInfo that was created by
1.36 + * CRMF_CreatePKIPublicationInfo that was passed in NULL for arena.
1.37 + */
1.38 +
1.39 +extern SECStatus
1.40 + CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
1.41 +
1.42 +extern SECStatus CRMF_AddPubInfoControl(CRMFCertRequest *inCertReq,
1.43 + CRMFPKIPublicationInfo *inPubInfo);
1.44 +
1.45 +/*
1.46 + * This is to create a Cert ID Control which can later be added to
1.47 + * a certificate request.
1.48 + */
1.49 +extern CRMFCertID* CRMF_CreateCertID(CRMFGeneralName *issuer,
1.50 + long serialNumber);
1.51 +
1.52 +extern SECStatus CRMF_DestroyCertID(CRMFCertID* certID);
1.53 +
1.54 +extern SECStatus CRMF_AddCertIDControl(CRMFCertRequest *inCertReq,
1.55 + CRMFCertID *certID);
1.56 +
1.57 +extern SECStatus
1.58 + CRMF_AddProtocolEncryptioKeyControl(CRMFCertRequest *inCertReq,
1.59 + CERTSubjectPublicKeyInfo *spki);
1.60 +
1.61 +/*
1.62 + * Add the ASCII Pairs Registration Info to the Certificate Request.
1.63 + * The SECItem must be an OCTET string representation.
1.64 + */
1.65 +extern SECStatus
1.66 + CRMF_AddUTF8PairsRegInfo(CRMFCertRequest *inCertReq,
1.67 + SECItem *asciiPairs);
1.68 +
1.69 +/*
1.70 + * This takes a CertRequest and adds it to another CertRequest.
1.71 + */
1.72 +extern SECStatus
1.73 + CRMF_AddCertReqToRegInfo(CRMFCertRequest *certReqToAddTo,
1.74 + CRMFCertRequest *certReqBeingAdded);
1.75 +
1.76 +/*
1.77 + * Returns which option was used for the authInfo field of POPOSigningKeyInput
1.78 + */
1.79 +extern CRMFPOPOSkiInputAuthChoice
1.80 + CRMF_GetSignKeyInputAuthChoice(CRMFPOPOSigningKeyInput *inKeyInput);
1.81 +
1.82 +/*
1.83 + * Gets the PKMACValue associated with the POPOSigningKeyInput.
1.84 + * If the POPOSigningKeyInput did not use authInfo.publicKeyMAC
1.85 + * the function returns SECFailure and the value at *destValue is unchanged.
1.86 + *
1.87 + * If the POPOSigningKeyInput did use authInfo.publicKeyMAC, the function
1.88 + * returns SECSuccess and places the PKMACValue at *destValue.
1.89 + */
1.90 +extern SECStatus
1.91 + CRMF_GetSignKeyInputPKMACValue(CRMFPOPOSigningKeyInput *inKeyInput,
1.92 + CRMFPKMACValue **destValue);
1.93 +/*
1.94 + * Gets the SubjectPublicKeyInfo from the POPOSigningKeyInput
1.95 + */
1.96 +extern CERTSubjectPublicKeyInfo *
1.97 + CRMF_GetSignKeyInputPublicKey(CRMFPOPOSigningKeyInput *inKeyInput);
1.98 +
1.99 +
1.100 +/*
1.101 + * Return the value for the PKIPublicationInfo Control.
1.102 + * A return value of NULL indicates that the Control was
1.103 + * not a PKIPublicationInfo Control. Call
1.104 + * CRMF_DestroyPKIPublicationInfo on the return value when done
1.105 + * using the pointer.
1.106 + */
1.107 +extern CRMFPKIPublicationInfo* CRMF_GetPKIPubInfo(CRMFControl *inControl);
1.108 +
1.109 +/*
1.110 + * Free up a CRMFPKIPublicationInfo structure.
1.111 + */
1.112 +extern SECStatus
1.113 + CRMF_DestroyPKIPublicationInfo(CRMFPKIPublicationInfo *inPubInfo);
1.114 +
1.115 +/*
1.116 + * Get the choice used for action in this PKIPublicationInfo.
1.117 + */
1.118 +extern CRMFPublicationAction
1.119 + CRMF_GetPublicationAction(CRMFPKIPublicationInfo *inPubInfo);
1.120 +
1.121 +/*
1.122 + * Get the number of pubInfos are stored in the PKIPubicationInfo.
1.123 + */
1.124 +extern int CRMF_GetNumPubInfos(CRMFPKIPublicationInfo *inPubInfo);
1.125 +
1.126 +/*
1.127 + * Get the pubInfo at index for the given PKIPubicationInfo.
1.128 + * Indexing is done like a traditional C Array. (0 .. numElements-1)
1.129 + */
1.130 +extern CRMFSinglePubInfo*
1.131 + CRMF_GetPubInfoAtIndex(CRMFPKIPublicationInfo *inPubInfo,
1.132 + int index);
1.133 +
1.134 +/*
1.135 + * Destroy the CRMFSinglePubInfo.
1.136 + */
1.137 +extern SECStatus CRMF_DestroySinglePubInfo(CRMFSinglePubInfo *inPubInfo);
1.138 +
1.139 +/*
1.140 + * Get the pubMethod used by the SinglePubInfo.
1.141 + */
1.142 +extern CRMFPublicationMethod
1.143 + CRMF_GetPublicationMethod(CRMFSinglePubInfo *inPubInfo);
1.144 +
1.145 +/*
1.146 + * Get the pubLocation associated with the SinglePubInfo.
1.147 + * A NULL return value indicates there was no pubLocation associated
1.148 + * with the SinglePuInfo.
1.149 + */
1.150 +extern CRMFGeneralName* CRMF_GetPubLocation(CRMFSinglePubInfo *inPubInfo);
1.151 +
1.152 +/*
1.153 + * Get the authInfo.sender field out of the POPOSigningKeyInput.
1.154 + * If the POPOSigningKeyInput did not use the authInfo the function
1.155 + * returns SECFailure and the value at *destName is unchanged.
1.156 + *
1.157 + * If the POPOSigningKeyInput did use authInfo.sender, the function returns
1.158 + * SECSuccess and puts the authInfo.sender at *destName/
1.159 + */
1.160 +extern SECStatus CRMF_GetSignKeyInputSender(CRMFPOPOSigningKeyInput *keyInput,
1.161 + CRMFGeneralName **destName);
1.162 +
1.163 +/**************** CMMF Functions that need to be added. **********************/
1.164 +
1.165 +/*
1.166 + * FUNCTION: CMMF_POPODecKeyChallContentSetNextChallenge
1.167 + * INPUTS:
1.168 + * inDecKeyChall
1.169 + * The CMMFPOPODecKeyChallContent to operate on.
1.170 + * inRandom
1.171 + * The random number to use when generating the challenge,
1.172 + * inSender
1.173 + * The GeneralName representation of the sender of the challenge.
1.174 + * inPubKey
1.175 + * The public key to use when encrypting the challenge.
1.176 + * NOTES:
1.177 + * This function adds a challenge to the end of the list of challenges
1.178 + * contained by 'inDecKeyChall'. Refer to the CMMF draft on how the
1.179 + * the random number passed in and the sender's GeneralName are used
1.180 + * to generate the challenge and witness fields of the challenge. This
1.181 + * library will use SHA1 as the one-way function for generating the
1.182 + * witess field of the challenge.
1.183 + *
1.184 + * RETURN:
1.185 + * SECSuccess if generating the challenge and adding to the end of list
1.186 + * of challenges was successful. Any other return value indicates an error
1.187 + * while trying to generate the challenge.
1.188 + */
1.189 +extern SECStatus
1.190 +CMMF_POPODecKeyChallContentSetNextChallenge
1.191 + (CMMFPOPODecKeyChallContent *inDecKeyChall,
1.192 + long inRandom,
1.193 + CERTGeneralName *inSender,
1.194 + SECKEYPublicKey *inPubKey);
1.195 +
1.196 +/*
1.197 + * FUNCTION: CMMF_POPODecKeyChallContentGetNumChallenges
1.198 + * INPUTS:
1.199 + * inKeyChallCont
1.200 + * The CMMFPOPODecKeyChallContent to operate on.
1.201 + * RETURN:
1.202 + * This function returns the number of CMMFChallenges are contained in
1.203 + * the CMMFPOPODecKeyChallContent structure.
1.204 + */
1.205 +extern int CMMF_POPODecKeyChallContentGetNumChallenges
1.206 + (CMMFPOPODecKeyChallContent *inKeyChallCont);
1.207 +
1.208 +/*
1.209 + * FUNCTION: CMMF_ChallengeGetRandomNumber
1.210 + * INPUTS:
1.211 + * inChallenge
1.212 + * The CMMFChallenge to operate on.
1.213 + * inDest
1.214 + * A pointer to a user supplied buffer where the library
1.215 + * can place a copy of the random integer contatained in the
1.216 + * challenge.
1.217 + * NOTES:
1.218 + * This function returns the value held in the decrypted Rand structure
1.219 + * corresponding to the random integer. The user must call
1.220 + * CMMF_ChallengeDecryptWitness before calling this function. Call
1.221 + * CMMF_ChallengeIsDecrypted to find out if the challenge has been
1.222 + * decrypted.
1.223 + *
1.224 + * RETURN:
1.225 + * SECSuccess indicates the witness field has been previously decrypted
1.226 + * and the value for the random integer was successfully placed at *inDest.
1.227 + * Any other return value indicates an error and that the value at *inDest
1.228 + * is not a valid value.
1.229 + */
1.230 +extern SECStatus CMMF_ChallengeGetRandomNumber(CMMFChallenge *inChallenge,
1.231 + long *inDest);
1.232 +
1.233 +/*
1.234 + * FUNCTION: CMMF_ChallengeGetSender
1.235 + * INPUTS:
1.236 + * inChallenge
1.237 + * the CMMFChallenge to operate on.
1.238 + * NOTES:
1.239 + * This function returns the value held in the decrypted Rand structure
1.240 + * corresponding to the sender. The user must call
1.241 + * CMMF_ChallengeDecryptWitness before calling this function. Call
1.242 + * CMMF_ChallengeIsDecrypted to find out if the witness field has been
1.243 + * decrypted. The user must call CERT_DestroyGeneralName after the return
1.244 + * value is no longer needed.
1.245 + *
1.246 + * RETURN:
1.247 + * A pointer to a copy of the sender CERTGeneralName. A return value of
1.248 + * NULL indicates an error in trying to copy the information or that the
1.249 + * witness field has not been decrypted.
1.250 + */
1.251 +extern CERTGeneralName* CMMF_ChallengeGetSender(CMMFChallenge *inChallenge);
1.252 +
1.253 +/*
1.254 + * FUNCTION: CMMF_ChallengeGetAlgId
1.255 + * INPUTS:
1.256 + * inChallenge
1.257 + * The CMMFChallenge to operate on.
1.258 + * inDestAlgId
1.259 + * A pointer to memory where a pointer to a copy of the algorithm
1.260 + * id can be placed.
1.261 + * NOTES:
1.262 + * This function retrieves the one way function algorithm identifier
1.263 + * contained within the CMMFChallenge if the optional field is present.
1.264 + *
1.265 + * RETURN:
1.266 + * SECSucces indicates the function was able to place a pointer to a copy of
1.267 + * the alogrithm id at *inAlgId. If the value at *inDestAlgId is NULL,
1.268 + * that means there was no algorithm identifier present in the
1.269 + * CMMFChallenge. Any other return value indicates the function was not
1.270 + * able to make a copy of the algorithm identifier. In this case the value
1.271 + * at *inDestAlgId is not valid.
1.272 + */
1.273 +extern SECStatus CMMF_ChallengeGetAlgId(CMMFChallenge *inChallenge,
1.274 + SECAlgorithmID *inAlgId);
1.275 +
1.276 +/*
1.277 + * FUNCTION: CMMF_DestroyChallenge
1.278 + * INPUTS:
1.279 + * inChallenge
1.280 + * The CMMFChallenge to free up.
1.281 + * NOTES:
1.282 + * This function frees up all the memory associated with the CMMFChallenge
1.283 + * passed in.
1.284 + * RETURN:
1.285 + * SECSuccess if freeing all the memory associated with the CMMFChallenge
1.286 + * passed in is successful. Any other return value indicates an error
1.287 + * while freeing the memory.
1.288 + */
1.289 +extern SECStatus CMMF_DestroyChallenge (CMMFChallenge *inChallenge);
1.290 +
1.291 +/*
1.292 + * FUNCTION: CMMF_DestroyPOPODecKeyRespContent
1.293 + * INPUTS:
1.294 + * inDecKeyResp
1.295 + * The CMMFPOPODecKeyRespContent structure to free.
1.296 + * NOTES:
1.297 + * This function frees up all the memory associate with the
1.298 + * CMMFPOPODecKeyRespContent.
1.299 + *
1.300 + * RETURN:
1.301 + * SECSuccess if freeint up all the memory associated with the
1.302 + * CMMFPOPODecKeyRespContent structure is successful. Any other
1.303 + * return value indicates an error while freeing the memory.
1.304 + */
1.305 +extern SECStatus
1.306 + CMMF_DestroyPOPODecKeyRespContent(CMMFPOPODecKeyRespContent *inDecKeyResp);
1.307 +
1.308 +/*
1.309 + * FUNCTION: CMMF_ChallengeDecryptWitness
1.310 + * INPUTS:
1.311 + * inChallenge
1.312 + * The CMMFChallenge to operate on.
1.313 + * inPrivKey
1.314 + * The private key to use to decrypt the witness field.
1.315 + * NOTES:
1.316 + * This function uses the private key to decrypt the challenge field
1.317 + * contained in the CMMFChallenge. Make sure the private key matches the
1.318 + * public key that was used to encrypt the witness. The creator of
1.319 + * the challenge will most likely be an RA that has the public key
1.320 + * from a Cert request. So the private key should be the private key
1.321 + * associated with public key in that request. This function will also
1.322 + * verify the witness field of the challenge.
1.323 + *
1.324 + * RETURN:
1.325 + * SECSuccess if decrypting the witness field was successful. This does
1.326 + * not indicate that the decrypted data is valid, since the private key
1.327 + * passed in may not be the actual key needed to properly decrypt the
1.328 + * witness field. Meaning that there is a decrypted structure now, but
1.329 + * may be garbage because the private key was incorrect.
1.330 + * Any other return value indicates the function could not complete the
1.331 + * decryption process.
1.332 + */
1.333 +extern SECStatus CMMF_ChallengeDecryptWitness(CMMFChallenge *inChallenge,
1.334 + SECKEYPrivateKey *inPrivKey);
1.335 +
1.336 +/*
1.337 + * FUNCTION: CMMF_ChallengeIsDecrypted
1.338 + * INPUTS:
1.339 + * inChallenge
1.340 + * The CMMFChallenge to operate on.
1.341 + * RETURN:
1.342 + * This is a predicate function that returns PR_TRUE if the decryption
1.343 + * process has already been performed. The function return PR_FALSE if
1.344 + * the decryption process has not been performed yet.
1.345 + */
1.346 +extern PRBool CMMF_ChallengeIsDecrypted(CMMFChallenge *inChallenge);
1.347 +
1.348 +/*
1.349 + * FUNCTION: CMMF_DestroyPOPODecKeyChallContent
1.350 + * INPUTS:
1.351 + * inDecKeyCont
1.352 + * The CMMFPOPODecKeyChallContent to free
1.353 + * NOTES:
1.354 + * This function frees up all the memory associated with the
1.355 + * CMMFPOPODecKeyChallContent
1.356 + * RETURN:
1.357 + * SECSuccess if freeing up all the memory associatd with the
1.358 + * CMMFPOPODecKeyChallContent is successful. Any other return value
1.359 + * indicates an error while freeing the memory.
1.360 + *
1.361 + */
1.362 +extern SECStatus
1.363 + CMMF_DestroyPOPODecKeyChallContent (CMMFPOPODecKeyChallContent *inDecKeyCont);
1.364 +
