summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/crmf/crmffut.h
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/lib/crmf/crmffut.h')
-rw-r--r--security/nss/lib/crmf/crmffut.h357
1 files changed, 357 insertions, 0 deletions
diff --git a/security/nss/lib/crmf/crmffut.h b/security/nss/lib/crmf/crmffut.h
new file mode 100644
index 000000000..d6f937438
--- /dev/null
+++ b/security/nss/lib/crmf/crmffut.h
@@ -0,0 +1,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);