summaryrefslogtreecommitdiffstats
path: root/security/nss/lib/crmf/cmmf.h
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /security/nss/lib/crmf/cmmf.h
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'security/nss/lib/crmf/cmmf.h')
-rw-r--r--security/nss/lib/crmf/cmmf.h1082
1 files changed, 1082 insertions, 0 deletions
diff --git a/security/nss/lib/crmf/cmmf.h b/security/nss/lib/crmf/cmmf.h
new file mode 100644
index 000000000..1e39a8d2d
--- /dev/null
+++ b/security/nss/lib/crmf/cmmf.h
@@ -0,0 +1,1082 @@
+/* -*- Mode: C; tab-width: 8 -*-*/
+/* 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/. */
+
+#ifndef _CMMF_H_
+#define _CMMF_H_
+/*
+ * These are the functions exported by the security library for
+ * implementing Certificate Management Message Formats (CMMF).
+ *
+ * This API is designed against July 1998 CMMF draft. Please read this
+ * draft before trying to use this API in an application that use CMMF.
+ */
+#include "seccomon.h"
+#include "cmmft.h"
+#include "crmf.h"
+
+SEC_BEGIN_PROTOS
+
+/******************* Creation Functions *************************/
+
+/*
+ * FUNCTION: CMMF_CreateCertRepContent
+ * INPUTS:
+ * NONE
+ * NOTES:
+ * This function will create an empty CMMFCertRepContent Structure.
+ * The client of the library must set the CMMFCertResponses.
+ * Call CMMF_CertRepContentSetCertResponse to accomplish this task.
+ * If the client of the library also wants to include the chain of
+ * CA certs required to make the certificates in CMMFCertResponse valid,
+ * then the user must also set the caPubs field of CMMFCertRepContent.
+ * Call CMMF_CertRepContentSetCAPubs to accomplish this. After setting
+ * the desired fields, the user can then call CMMF_EncodeCertRepContent
+ * to DER-encode the CertRepContent.
+ * RETURN:
+ * A pointer to the CMMFCertRepContent. A NULL return value indicates
+ * an error in allocating memory or failure to initialize the structure.
+ */
+extern CMMFCertRepContent *CMMF_CreateCertRepContent(void);
+
+/*
+ * FUNCTION: CMMF_CreateCertRepContentFromDER
+ * INPUTS
+ * db
+ * The certificate database where the certificates will be placed.
+ * The certificates will be placed in the temporary database associated
+ * with the handle.
+ * buf
+ * A buffer to the DER-encoded CMMFCertRepContent
+ * len
+ * The length in bytes of the buffer 'buf'
+ * NOTES:
+ * This function passes the buffer to the ASN1 decoder and creates a
+ * CMMFCertRepContent structure. The user must call
+ * CMMF_DestroyCertRepContent after the return value is no longer needed.
+ *
+ * RETURN:
+ * A pointer to the CMMFCertRepContent structure. A NULL return
+ * value indicates the library was unable to parse the DER.
+ */
+extern CMMFCertRepContent *
+CMMF_CreateCertRepContentFromDER(CERTCertDBHandle *db,
+ const char *buf,
+ long len);
+
+/*
+ * FUNCTION: CMMF_CreateCertResponse
+ * INPUTS:
+ * inCertReqId
+ * The Certificate Request Id this response is for.
+ * NOTES:
+ * This creates a CMMFCertResponse. This response should correspond
+ * to a request that was received via CRMF. From the CRMF message you
+ * can get the Request Id to pass in as inCertReqId, in essence binding
+ * a CMRFCertRequest message to the CMMFCertResponse created by this
+ * function. If no requuest id is associated with the response to create
+ * then the user should pass in -1 for 'inCertReqId'.
+ *
+ * RETURN:
+ * A pointer to the new CMMFCertResponse corresponding to the request id
+ * passed in. A NULL return value indicates an error while trying to
+ * create the CMMFCertResponse.
+ */
+extern CMMFCertResponse *CMMF_CreateCertResponse(long inCertReqId);
+
+/*
+ * FUNCTION: CMMF_CreateKeyRecRepContent
+ * INPUTS:
+ * NONE
+ * NOTES:
+ * This function creates a new empty CMMFKeyRecRepContent structure.
+ * At the very minimum, the user must call
+ * CMMF_KeyRecRepContentSetPKIStatusInfoStatus field to have an
+ * encodable structure. Depending on what the response is, the user may
+ * have to set other fields as well to properly build up the structure so
+ * that it can be encoded. Refer to the CMMF draft for how to properly
+ * set up a CMMFKeyRecRepContent. This is the structure that an RA returns
+ * to an end entity when doing key recovery.
+
+ * The user must call CMMF_DestroyKeyRecRepContent when the return value
+ * is no longer needed.
+ * RETURN:
+ * A pointer to the empty CMMFKeyRecRepContent. A return value of NULL
+ * indicates an error in allocating memory or initializing the structure.
+ */
+extern CMMFKeyRecRepContent *CMMF_CreateKeyRecRepContent(void);
+
+/*
+ * FUNCTION: CMMF_CreateKeyRecRepContentFromDER
+ * INPUTS:
+ * db
+ * The handle for the certificate database where the decoded
+ * certificates will be placed. The decoded certificates will
+ * be placed in the temporary database associated with the
+ * handle.
+ * buf
+ * A buffer contatining the DER-encoded CMMFKeyRecRepContent
+ * len
+ * The length in bytes of the buffer 'buf'
+ * NOTES
+ * This function passes the buffer to the ASN1 decoder and creates a
+ * CMMFKeyRecRepContent structure.
+ *
+ * RETURN:
+ * A pointer to the CMMFKeyRecRepContent structure. A NULL return
+ * value indicates the library was unable to parse the DER.
+ */
+extern CMMFKeyRecRepContent *
+CMMF_CreateKeyRecRepContentFromDER(CERTCertDBHandle *db,
+ const char *buf,
+ long len);
+
+/*
+ * FUNCTION: CMMF_CreatePOPODecKeyChallContent
+ * INPUTS:
+ * NONE
+ * NOTES:
+ * This function creates an empty CMMFPOPODecKeyChallContent. The user
+ * must add the challenges individually specifying the random number to
+ * be used and the public key to be used when creating each individual
+ * challenge. User can accomplish this by calling the function
+ * CMMF_POPODecKeyChallContentSetNextChallenge.
+ * RETURN:
+ * A pointer to a CMMFPOPODecKeyChallContent structure. Ther user can
+ * then call CMMF_EncodePOPODecKeyChallContent passing in the return
+ * value from this function after setting all of the challenges. A
+ * return value of NULL indicates an error while creating the
+ * CMMFPOPODecKeyChallContent structure.
+ */
+extern CMMFPOPODecKeyChallContent *
+CMMF_CreatePOPODecKeyChallContent(void);
+
+/*
+ * FUNCTION: CMMF_CreatePOPODecKeyChallContentFromDER
+ * INPUTS
+ * buf
+ * A buffer containing the DER-encoded CMMFPOPODecKeyChallContent
+ * len
+ * The length in bytes of the buffer 'buf'
+ * NOTES:
+ * This function passes the buffer to the ASN1 decoder and creates a
+ * CMMFPOPODecKeyChallContent structure.
+ *
+ * RETURN:
+ * A pointer to the CMMFPOPODecKeyChallContent structure. A NULL return
+ * value indicates the library was unable to parse the DER.
+ */
+extern CMMFPOPODecKeyChallContent *
+CMMF_CreatePOPODecKeyChallContentFromDER(const char *buf, long len);
+
+/*
+ * FUNCTION: CMMF_CreatePOPODecKeyRespContentFromDER
+ * INPUTS:
+ * buf
+ * A buffer contatining the DER-encoded CMMFPOPODecKeyRespContent
+ * len
+ * The length in bytes of the buffer 'buf'
+ * NOTES
+ * This function passes the buffer to the ASN1 decoder and creates a
+ * CMMFPOPODecKeyRespContent structure.
+ *
+ * RETURN:
+ * A pointer to the CMMFPOPODecKeyRespContent structure. A NULL return
+ * value indicates the library was unable to parse the DER.
+ */
+extern CMMFPOPODecKeyRespContent *
+CMMF_CreatePOPODecKeyRespContentFromDER(const char *buf, long len);
+
+/************************** Set Functions *************************/
+
+/*
+ * FUNCTION: CMMF_CertRepContentSetCertResponses
+ * INPUTS:
+ * inCertRepContent
+ * The CMMFCertRepContent to operate on.
+ * inCertResponses
+ * An array of pointers to CMMFCertResponse structures to
+ * add to the CMMFCertRepContent structure.
+ * inNumResponses
+ * The length of the array 'inCertResponses'
+ * NOTES:
+ * This function will add the CMMFCertResponse structure to the
+ * CMMFCertRepContent passed in. The CMMFCertResponse field of
+ * CMMFCertRepContent is required, so the client must call this function
+ * before calling CMMF_EncodeCertRepContent. If the user calls
+ * CMMF_EncodeCertRepContent before calling this function,
+ * CMMF_EncodeCertRepContent will fail.
+ *
+ * RETURN:
+ * SECSuccess if adding the CMMFCertResponses to the CMMFCertRepContent
+ * structure was successful. Any other return value indicates an error
+ * while trying to add the CMMFCertResponses.
+ */
+extern SECStatus
+CMMF_CertRepContentSetCertResponses(CMMFCertRepContent *inCertRepContent,
+ CMMFCertResponse **inCertResponses,
+ int inNumResponses);
+
+/*
+ * FUNCTION: CMMF_CertRepContentSetCAPubs
+ * INPUTS:
+ * inCertRepContent
+ * The CMMFCertRepContent to operate on.
+ * inCAPubs
+ * The certificate list which makes up the chain of CA certificates
+ * required to make the issued cert valid.
+ * NOTES:
+ * This function will set the the certificates in the CA chain as part
+ * of the CMMFCertRepContent. This field is an optional member of the
+ * CMMFCertRepContent structure, so the client is not required to call
+ * this function before calling CMMF_EncodeCertRepContent.
+ *
+ * RETURN:
+ * SECSuccess if adding the 'inCAPubs' to the CERTRepContent was successful.
+ * Any other return value indicates an error while adding 'inCAPubs' to the
+ * CMMFCertRepContent structure.
+ *
+ */
+extern SECStatus
+CMMF_CertRepContentSetCAPubs(CMMFCertRepContent *inCertRepContent,
+ CERTCertList *inCAPubs);
+
+/*
+ * FUNCTION: CMMF_CertResponseSetPKIStatusInfoStatus
+ * INPUTS:
+ * inCertResp
+ * The CMMFCertResponse to operate on.
+ * inPKIStatus
+ * The value to set for the PKIStatusInfo.status field.
+ * NOTES:
+ * This function will set the CertResponse.status.status field of
+ * the CMMFCertResponse structure. (View the definition of CertResponse
+ * in the CMMF draft to see exactly which value this talks about.) This
+ * field is a required member of the structure, so the user must call this
+ * function in order to have a CMMFCertResponse that can be encoded.
+ *
+ * RETURN:
+ * SECSuccess if setting the field with the passed in value was successful.
+ * Any other return value indicates an error while trying to set the field.
+ */
+extern SECStatus
+CMMF_CertResponseSetPKIStatusInfoStatus(CMMFCertResponse *inCertResp,
+ CMMFPKIStatus inPKIStatus);
+
+/*
+ * FUNCTION: CMMF_CertResponseSetCertificate
+ * INPUTS:
+ * inCertResp
+ * The CMMFCertResponse to operate on.
+ * inCertificate
+ * The certificate to add to the
+ * CertResponse.CertifiedKeyPair.certOrEncCert.certificate field.
+ * NOTES:
+ * This function will take the certificate and make it a member of the
+ * CMMFCertResponse. The certificate should be the actual certificate
+ * being issued via the response.
+ *
+ * RETURN:
+ * SECSuccess if adding the certificate to the response was successful.
+ * Any other return value indicates an error in adding the certificate to
+ * the CertResponse.
+ */
+extern SECStatus
+CMMF_CertResponseSetCertificate(CMMFCertResponse *inCertResp,
+ CERTCertificate *inCertificate);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentSetPKIStatusInfoStatus
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRecRepContent to operate on.
+ * inPKIStatus
+ * The value to set the PKIStatusInfo.status field to.
+ * NOTES:
+ * This function sets the only required field for the KeyRecRepContent.
+ * In most cases, the user will set this field and other fields of the
+ * structure to properly create the CMMFKeyRecRepContent structure.
+ * Refer to the CMMF draft to see which fields need to be set in order
+ * to create the desired CMMFKeyRecRepContent.
+ *
+ * RETURN:
+ * SECSuccess if setting the PKIStatusInfo.status field was successful.
+ * Any other return value indicates an error in setting the field.
+ */
+extern SECStatus
+CMMF_KeyRecRepContentSetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep,
+ CMMFPKIStatus inPKIStatus);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentSetNewSignCert
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRecRepContent to operate on.
+ * inNewSignCert
+ * The new signing cert to add to the CMMFKeyRecRepContent structure.
+ * NOTES:
+ * This function sets the new signeing cert in the CMMFKeyRecRepContent
+ * structure.
+ *
+ * RETURN:
+ * SECSuccess if setting the new signing cert was successful. Any other
+ * return value indicates an error occurred while trying to add the
+ * new signing certificate.
+ */
+extern SECStatus
+CMMF_KeyRecRepContentSetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep,
+ CERTCertificate *inNewSignCert);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentSetCACerts
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRecRepContent to operate on.
+ * inCACerts
+ * The list of CA certificates required to construct a valid
+ * certificate chain with the certificates that will be returned
+ * to the end user via this KeyRecRepContent.
+ * NOTES:
+ * This function sets the caCerts that are required to form a chain with the
+ * end entity certificates that are being re-issued in this
+ * CMMFKeyRecRepContent structure.
+ *
+ * RETURN:
+ * SECSuccess if adding the caCerts was successful. Any other return value
+ * indicates an error while tring to add the caCerts.
+ */
+extern SECStatus
+CMMF_KeyRecRepContentSetCACerts(CMMFKeyRecRepContent *inKeyRecRep,
+ CERTCertList *inCACerts);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentSetCertifiedKeyPair
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRecRepContent to operate on.
+ * inCert
+ * The certificate to add to the CMMFKeyRecRepContent structure.
+ * inPrivKey
+ * The private key associated with the certificate above passed in.
+ * inPubKey
+ * The public key to use for wrapping the private key.
+ * NOTES:
+ * This function adds another certificate-key pair to the
+ * CMMFKeyRecRepcontent structure. There may be more than one
+ * certificate-key pair in the structure, so the user must call this
+ * function multiple times to add more than one cert-key pair.
+ *
+ * RETURN:
+ * SECSuccess if adding the certified key pair was successful. Any other
+ * return value indicates an error in adding certified key pair to
+ * CMMFKeyRecRepContent structure.
+ */
+extern SECStatus
+CMMF_KeyRecRepContentSetCertifiedKeyPair(CMMFKeyRecRepContent *inKeyRecRep,
+ CERTCertificate *inCert,
+ SECKEYPrivateKey *inPrivKey,
+ SECKEYPublicKey *inPubKey);
+
+/*
+ * 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.
+ * passwdArg
+ * This value will be passed to the function used for getting a
+ * password. The password for getting a password should be registered
+ * by calling PK11_SetPasswordFunc before this function is called.
+ * If no password callback is registered and the library needs to
+ * authenticate to the slot for any reason, this function will fail.
+ * 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,
+ void *passwdArg);
+
+/************************** Encoding Functions *************************/
+
+/*
+ * FUNCTION: CMMF_EncodeCertRepContent
+ * INPUTS:
+ * inCertRepContent
+ * The CMMFCertRepContent to DER-encode.
+ * inCallback
+ * A callback function that the ASN1 encoder will call whenever it
+ * wants to write out DER-encoded bytes. Look at the defintion of
+ * CRMFEncoderOutputCallback in crmft.h for a description of the
+ * parameters to the function.
+ * inArg
+ * An opaque pointer to a user-supplied argument that will be passed
+ * to the callback funtion whenever the function is called.
+ * NOTES:
+ * The CMMF library will use the same DER-encoding scheme as the CRMF
+ * library. In other words, when reading CRMF comments that pertain to
+ * encoding, those comments apply to the CMMF libray as well.
+ * The callback function will be called multiple times, each time supplying
+ * the next chunk of DER-encoded bytes. The user must concatenate the
+ * output of each successive call to the callback in order to get the
+ * entire DER-encoded CMMFCertRepContent structure.
+ *
+ * RETURN:
+ * SECSuccess if encoding the CMMFCertRepContent was successful. Any
+ * other return value indicates an error while decoding the structure.
+ */
+extern SECStatus
+CMMF_EncodeCertRepContent(CMMFCertRepContent *inCertRepContent,
+ CRMFEncoderOutputCallback inCallback,
+ void *inArg);
+
+/*
+ * FUNCTION: CMMF_EncodeKeyRecRepContent
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRepContent to DER-encode.
+ * inCallback
+ * A callback function that the ASN1 encoder will call whenever it
+ * wants to write out DER-encoded bytes. Look at the defintion of
+ * CRMFEncoderOutputCallback in crmft.h for a description of the
+ * parameters to the function.
+ * inArg
+ * An opaque pointer to a user-supplied argument that will be passed
+ * to the callback funtion whenever the function is called.
+ * NOTES:
+ * The CMMF library will use the same DER-encoding scheme as the CRMF
+ * library. In other words, when reading CRMF comments that pertain to
+ * encoding, those comments apply to the CMMF libray as well.
+ * The callback function will be called multiple times, each time supplying
+ * the next chunk of DER-encoded bytes. The user must concatenate the
+ * output of each successive call to the callback in order to get the
+ * entire DER-encoded CMMFCertRepContent structure.
+ *
+ * RETURN:
+ * SECSuccess if encoding the CMMFKeyRecRepContent was successful. Any
+ * other return value indicates an error while decoding the structure.
+ */
+extern SECStatus
+CMMF_EncodeKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep,
+ CRMFEncoderOutputCallback inCallback,
+ void *inArg);
+
+/*
+ * FUNCTION: CMMF_EncodePOPODecKeyChallContent
+ * INPUTS:
+ * inDecKeyChall
+ * The CMMFDecKeyChallContent to operate on.
+ * inCallback
+ * A callback function that the ASN1 encoder will call whenever it
+ * wants to write out DER-encoded bytes. Look at the defintion of
+ * CRMFEncoderOutputCallback in crmft.h for a description of the
+ * parameters to the function.
+ * inArg
+ * An opaque pointer to a user-supplied argument that will be passed
+ * to the callback function whenever the function is called.
+ * NOTES:
+ * The CMMF library will use the same DER-encoding scheme as the CRMF
+ * library. In other words, when reading CRMF comments that pertain to
+ * encoding, those comments apply to the CMMF libray as well.
+ * The callback function will be called multiple times, each time supplying
+ * the next chunk of DER-encoded bytes. The user must concatenate the
+ * output of each successive call to the callback in order to get the
+ * entire DER-encoded CMMFCertRepContent structure.
+ * The DER will be an encoding of the type POPODecKeyChallContents, which
+ * is just a sequence of challenges.
+ *
+ * RETURN:
+ * SECSuccess if encoding was successful. Any other return value indicates
+ * an error in trying to encode the Challenges.
+ */
+extern SECStatus
+CMMF_EncodePOPODecKeyChallContent(CMMFPOPODecKeyChallContent *inDecKeyChall,
+ CRMFEncoderOutputCallback inCallback,
+ void *inArg);
+
+/*
+ * FUNCTION: CMMF_EncodePOPODecKeyRespContent
+ * INPUTS:
+ * inDecodedRand
+ * An array of integers to encode as the responses to
+ * CMMFPOPODecKeyChallContent. The integers must be in the same order
+ * as the challenges extracted from CMMFPOPODecKeyChallContent.
+ * inNumRand
+ * The number of random integers contained in the array 'inDecodedRand'
+ * inCallback
+ * A callback function that the ASN1 encoder will call whenever it
+ * wants to write out DER-encoded bytes. Look at the defintion of
+ * CRMFEncoderOutputCallback in crmft.h for a description of the
+ * parameters to the function.
+ * inArg
+ * An opaque pointer to a user-supplied argument that will be passed
+ * to the callback funtion whenever the function is called.
+ * NOTES:
+ * The CMMF library will use the same DER-encoding scheme as the CRMF
+ * library. In other words, when reading CRMF comments that pertain to
+ * encoding, those comments apply to the CMMF libray as well.
+ * The callback function will be called multiple times, each time supplying
+ * the next chunk of DER-encoded bytes. The user must concatenate the
+ * output of each successive call to the callback in order to get the
+ * entire DER-encoded POPODecKeyRespContent.
+ *
+ * RETURN:
+ * SECSuccess if encoding was successful. Any other return value indicates
+ * an error in trying to encode the Challenges.
+ */
+extern SECStatus
+CMMF_EncodePOPODecKeyRespContent(long *inDecodedRand,
+ int inNumRand,
+ CRMFEncoderOutputCallback inCallback,
+ void *inArg);
+
+/*************** Accessor function ***********************************/
+
+/*
+ * FUNCTION: CMMF_CertRepContentGetCAPubs
+ * INPUTS:
+ * inCertRepContent
+ * The CMMFCertRepContent to extract the caPubs from.
+ * NOTES:
+ * This function will return a copy of the list of certificates that
+ * make up the chain of CA's required to make the cert issued valid.
+ * The user must call CERT_DestroyCertList on the return value when
+ * done using the return value.
+ *
+ * Only call this function on a CertRepContent that has been decoded.
+ * The client must call CERT_DestroyCertList when the certificate list
+ * is no longer needed.
+ *
+ * The certs in the list will not be in the temporary database. In order
+ * to make these certificates a part of the permanent CA internal database,
+ * the user must collect the der for all of these certs and call
+ * CERT_ImportCAChain. Afterwards the certs will be part of the permanent
+ * database.
+ *
+ * RETURN:
+ * A pointer to the CERTCertList representing the CA chain associated
+ * with the issued cert. A NULL return value indicates that no CA Pubs
+ * were available in the CMMFCertRepContent structure.
+ */
+extern CERTCertList *
+CMMF_CertRepContentGetCAPubs(CMMFCertRepContent *inCertRepContent);
+
+/*
+ * FUNCTION: CMMF_CertRepContentGetNumResponses
+ * INPUTS:
+ * inCertRepContent
+ * The CMMFCertRepContent to operate on.
+ * NOTES:
+ * This function will return the number of CertResponses that are contained
+ * by the CMMFCertRepContent passed in.
+ *
+ * RETURN:
+ * The number of CMMFCertResponses contained in the structure passed in.
+ */
+extern int
+CMMF_CertRepContentGetNumResponses(CMMFCertRepContent *inCertRepContent);
+
+/*
+ * FUNCTION: CMMF_CertRepContentGetResponseAtIndex
+ * INPUTS:
+ * inCertRepContent
+ * The CMMFCertRepContent to operate on.
+ * inIndex
+ * The index of the CMMFCertResponse the user wants a copy of.
+ * NOTES:
+ * This function creates a copy of the CMMFCertResponse at the index
+ * corresponding to the parameter 'inIndex'. Indexing is done like a
+ * traditional C array, ie the valid indexes are (0...numResponses-1).
+ * The user must call CMMF_DestroyCertResponse after the return value is
+ * no longer needed.
+ *
+ * RETURN:
+ * A pointer to the CMMFCertResponse at the index corresponding to
+ * 'inIndex'. A return value of NULL indicates an error in copying
+ * the CMMFCertResponse.
+ */
+extern CMMFCertResponse *
+CMMF_CertRepContentGetResponseAtIndex(CMMFCertRepContent *inCertRepContent,
+ int inIndex);
+
+/*
+ * FUNCTION: CMMF_CertResponseGetCertReqId
+ * INPUTS:
+ * inCertResp
+ * The CMMFCertResponse to operate on.
+ * NOTES:
+ * This function returns the CertResponse.certReqId from the
+ * CMMFCertResponse structure passed in. If the return value is -1, that
+ * means there is no associated certificate request with the CertResponse.
+ * RETURN:
+ * A long representing the id of the certificate request this
+ * CMMFCertResponse corresponds to. A return value of -1 indicates an
+ * error in extracting the value of the integer.
+ */
+extern long CMMF_CertResponseGetCertReqId(CMMFCertResponse *inCertResp);
+
+/*
+ * FUNCTION: CMMF_CertResponseGetPKIStatusInfoStatus
+ * INPUTS:
+ * inCertResp
+ * The CMMFCertResponse to operate on.
+ * NOTES:
+ * This function returns the CertResponse.status.status field of the
+ * CMMFCertResponse structure.
+ *
+ * RETURN:
+ * The enumerated value corresponding to the PKIStatus defined in the CMMF
+ * draft. See the CMMF draft for the definition of PKIStatus. See crmft.h
+ * for the definition of CMMFPKIStatus.
+ */
+extern CMMFPKIStatus
+CMMF_CertResponseGetPKIStatusInfoStatus(CMMFCertResponse *inCertResp);
+
+/*
+ * FUNCTION: CMMF_CertResponseGetCertificate
+ * INPUTS:
+ * inCertResp
+ * The Certificate Response to operate on.
+ * inCertdb
+ * This is the certificate database where the function will place the
+ * newly issued certificate.
+ * NOTES:
+ * This function retrieves the CertResponse.certifiedKeyPair.certificate
+ * from the CMMFCertResponse. The user will get a copy of that certificate
+ * so the user must call CERT_DestroyCertificate when the return value is
+ * no longer needed. The certificate returned will be in the temporary
+ * certificate database.
+ *
+ * RETURN:
+ * A pointer to a copy of the certificate contained within the
+ * CMMFCertResponse. A return value of NULL indicates an error while trying
+ * to make a copy of the certificate.
+ */
+extern CERTCertificate *
+CMMF_CertResponseGetCertificate(CMMFCertResponse *inCertResp,
+ CERTCertDBHandle *inCertdb);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentGetPKIStatusInfoStatus
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRecRepContent structure to operate on.
+ * NOTES:
+ * This function retrieves the KeyRecRepContent.status.status field of
+ * the CMMFKeyRecRepContent structure.
+ * RETURN:
+ * The CMMFPKIStatus corresponding to the value held in the
+ * CMMFKeyRecRepContent structure.
+ */
+extern CMMFPKIStatus
+CMMF_KeyRecRepContentGetPKIStatusInfoStatus(CMMFKeyRecRepContent *inKeyRecRep);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentGetNewSignCert
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRecRepContent to operate on.
+ * NOTES:
+ * This function retrieves the KeyRecRepContent.newSignCert field of the
+ * CMMFKeyRecRepContent structure. The user must call
+ * CERT_DestroyCertificate when the return value is no longer needed. The
+ * returned certificate will be in the temporary database. The user
+ * must then place the certificate permanently in whatever token the
+ * user determines is the proper destination. A return value of NULL
+ * indicates the newSigCert field was not present.
+ */
+extern CERTCertificate *
+CMMF_KeyRecRepContentGetNewSignCert(CMMFKeyRecRepContent *inKeyRecRep);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentGetCACerts
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRecRepContent to operate on.
+ * NOTES:
+ * This function returns a CERTCertList which contains all of the
+ * certficates that are in the sequence KeyRecRepContent.caCerts
+ * User must call CERT_DestroyCertList when the return value is no longer
+ * needed. All of these certificates will be placed in the tempoaray
+ * database.
+ *
+ * RETURN:
+ * A pointer to the list of caCerts contained in the CMMFKeyRecRepContent
+ * structure. A return value of NULL indicates the library was not able to
+ * make a copy of the certifcates. This may be because there are no caCerts
+ * included in the CMMFKeyRecRepContent strucure or an internal error. Call
+ * CMMF_KeyRecRepContentHasCACerts to find out if there are any caCerts
+ * included in 'inKeyRecRep'.
+ */
+extern CERTCertList *
+CMMF_KeyRecRepContentGetCACerts(CMMFKeyRecRepContent *inKeyRecRep);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentGetNumKeyPairs
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRecRepContent to operate on.
+ * RETURN:
+ * This function returns the number of CMMFCertifiedKeyPair structures that
+ * that are stored in the KeyRecRepContent structure.
+ */
+extern int
+CMMF_KeyRecRepContentGetNumKeyPairs(CMMFKeyRecRepContent *inKeyRecRep);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentGetCertKeyAtIndex
+ * INPUTS:
+ * inKeyRecRepContent
+ * The CMMFKeyRecRepContent to operate on.
+ * inIndex
+ * The index of the desired CMMFCertifiedKeyPair
+ * NOTES:
+ * This function retrieves the CMMFCertifiedKeyPair structure at the index
+ * 'inIndex'. Valid indexes are 0...(numKeyPairs-1) The user must call
+ * CMMF_DestroyCertifiedKeyPair when the return value is no longer needed.
+ *
+ * RETURN:
+ * A pointer to the Certified Key Pair at the desired index. A return value
+ * of NULL indicates an error in extracting the Certified Key Pair at the
+ * desired index.
+ */
+extern CMMFCertifiedKeyPair *
+CMMF_KeyRecRepContentGetCertKeyAtIndex(CMMFKeyRecRepContent *inKeyRecRep,
+ int inIndex);
+
+/*
+ * FUNCTION: CMMF_CertifiedKeyPairGetCertificate
+ * INPUTS:
+ * inCertKeyPair
+ * The CMMFCertifiedKeyPair to operate on.
+ * inCertdb
+ * The database handle for the database you want this certificate
+ * to wind up in.
+ * NOTES:
+ * This function retrieves the certificate at
+ * CertifiedKeyPair.certOrEncCert.certificate
+ * The user must call CERT_DestroyCertificate when the return value is no
+ * longer needed. The user must import this certificate as a token object
+ * onto PKCS#11 slot in order to make it a permanent object. The returned
+ * certificate will be in the temporary database.
+ *
+ * RETURN:
+ * A pointer to the certificate contained within the certified key pair.
+ * A return value of NULL indicates an error in creating the copy of the
+ * certificate.
+ */
+extern CERTCertificate *
+CMMF_CertifiedKeyPairGetCertificate(CMMFCertifiedKeyPair *inCertKeyPair,
+ CERTCertDBHandle *inCertdb);
+
+/*
+ * 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_POPODecKeyChallContentGetPublicValue
+ * ---------------------------------------------------
+ * INPUTS:
+ * inKeyChallCont
+ * The CMMFPOPODecKeyChallContent to operate on.
+ * inIndex
+ * The index of the Challenge within inKeyChallCont to operate on.
+ * Indexes start from 0, ie the Nth Challenge corresponds to index
+ * N-1.
+ * NOTES:
+ * This function retrieves the public value stored away in the Challenge at
+ * index inIndex of inKeyChallCont.
+ * RETURN:
+ * A pointer to a SECItem containing the public value. User must call
+ * SECITEM_FreeItem on the return value when the value is no longer necessary.
+ * A return value of NULL indicates an error while retrieving the public value.
+ */
+extern SECItem *CMMF_POPODecKeyChallContentGetPublicValue(CMMFPOPODecKeyChallContent *inKeyChallCont,
+ int inIndex);
+
+/*
+ * FUNCTION: CMMF_POPODecKeyChallContentGetRandomNumber
+ * INPUTS:
+ * inChallContent
+ * The CMMFPOPODecKeyChallContent to operate on.
+ * inIndex
+ * The index of the challenge to look at. Valid indexes are 0 through
+ * (CMMF_POPODecKeyChallContentGetNumChallenges(inChallContent) - 1).
+ * 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_POPODecKeyChallContentDecryptChallenge 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_POPODecKeyChallContentGetRandomNumber(CMMFPOPODecKeyChallContent *inKeyChallCont,
+ int inIndex,
+ long *inDest);
+
+/*
+ * FUNCTION: CMMF_POPODecKeyRespContentGetNumResponses
+ * INPUTS:
+ * inRespCont
+ * The POPODecKeyRespContent to operate on.
+ * RETURN:
+ * This function returns the number of responses contained in inRespContent.
+ */
+extern int
+CMMF_POPODecKeyRespContentGetNumResponses(CMMFPOPODecKeyRespContent *inRespCont);
+
+/*
+ * FUNCTION: CMMF_POPODecKeyRespContentGetResponse
+ * INPUTS:
+ * inRespCont
+ * The POPODecKeyRespContent to operate on.
+ * inIndex
+ * The index of the response to retrieve.
+ * The Nth response is at index N-1, ie the 1st response is at index 0,
+ * the 2nd response is at index 1, and so on.
+ * inDest
+ * A pointer to a pre-allocated buffer where the library can put the
+ * value of the response located at inIndex.
+ * NOTES:
+ * The function returns the response contained at index inIndex.
+ * CMMFPOPODecKeyRespContent is a structure that the server will generally
+ * get in response to a CMMFPOPODecKeyChallContent. The server will expect
+ * to see the responses in the same order as it constructed them in
+ * the CMMFPOPODecKeyChallContent structure.
+ * RETURN:
+ * SECSuccess if getting the response at the desired index was successful. Any
+ * other return value indicates an errror.
+ */
+extern SECStatus
+CMMF_POPODecKeyRespContentGetResponse(CMMFPOPODecKeyRespContent *inRespCont,
+ int inIndex,
+ long *inDest);
+
+/************************* Destructor Functions ******************************/
+
+/*
+ * FUNCTION: CMMF_DestroyCertResponse
+ * INPUTS:
+ * inCertResp
+ * The CMMFCertResponse to destroy.
+ * NOTES:
+ * This function frees all the memory associated with the CMMFCertResponse
+ * passed in.
+ * RETURN:
+ * SECSuccess if freeing the memory was successful. Any other return value
+ * indicates an error while freeing the memory.
+ */
+extern SECStatus CMMF_DestroyCertResponse(CMMFCertResponse *inCertResp);
+
+/*
+ * FUNCTION: CMMF_DestroyCertRepContent
+ * INPUTS:
+ * inCertRepContent
+ * The CMMFCertRepContent to destroy
+ * NOTES:
+ * This function frees the memory associated with the CMMFCertRepContent
+ * passed in.
+ * RETURN:
+ * SECSuccess if freeing all the memory associated with the
+ * CMMFCertRepContent passed in is successful. Any other return value
+ * indicates an error while freeing the memory.
+ */
+extern SECStatus
+CMMF_DestroyCertRepContent(CMMFCertRepContent *inCertRepContent);
+
+/*
+ * FUNCTION: CMMF_DestroyKeyRecRepContent
+ * INPUTS:
+ * inKeyRecRep
+ * The CMMFKeyRecRepContent to destroy.
+ * NOTES:
+ * This function destroys all the memory associated with the
+ * CMMFKeyRecRepContent passed in.
+ *
+ * RETURN:
+ * SECSuccess if freeing all the memory is successful. Any other return
+ * value indicates an error in freeing the memory.
+ */
+extern SECStatus
+CMMF_DestroyKeyRecRepContent(CMMFKeyRecRepContent *inKeyRecRep);
+
+/*
+ * FUNCTION: CMMF_DestroyCertifiedKeyPair
+ * INPUTS:
+ * inCertKeyPair
+ * The CMMFCertifiedKeyPair to operate on.
+ * NOTES:
+ * This function frees up all the memory associated with 'inCertKeyPair'
+ *
+ * RETURN:
+ * SECSuccess if freeing all the memory associated with 'inCertKeyPair'
+ * is successful. Any other return value indicates an error while trying
+ * to free the memory.
+ */
+extern SECStatus
+CMMF_DestroyCertifiedKeyPair(CMMFCertifiedKeyPair *inCertKeyPair);
+
+/*
+ * 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 freeing 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);
+
+/************************** Miscellaneous Functions *************************/
+
+/*
+ * FUNCTION: CMMF_CertifiedKeyPairUnwrapPrivKey
+ * INPUTS:
+ * inCertKeyPair
+ * The CMMFCertifiedKeyPair to operate on.
+ * inPrivKey
+ * The private key to use to un-wrap the private key
+ * inNickName
+ * This is the nickname that will be associated with the private key
+ * to be unwrapped.
+ * inSlot
+ * The PKCS11 slot where the unwrapped private key should end up.
+ * inCertdb
+ * The Certificate database with which the new key will be associated.
+ * destPrivKey
+ * A pointer to memory where the library can place a pointer to the
+ * private key after importing the key onto the specified slot.
+ * wincx
+ * An opaque pointer that the library will use in a callback function
+ * to get the password if necessary.
+ *
+ * NOTES:
+ * This function uses the private key passed in to unwrap the private key
+ * contained within the CMMFCertifiedKeyPair structure. After this
+ * function successfully returns, the private key has been unwrapped and
+ * placed in the specified slot.
+ *
+ * RETURN:
+ * SECSuccess if unwrapping the private key was successful. Any other
+ * return value indicates an error while trying to un-wrap the private key.
+ */
+extern SECStatus
+CMMF_CertifiedKeyPairUnwrapPrivKey(CMMFCertifiedKeyPair *inKeyPair,
+ SECKEYPrivateKey *inPrivKey,
+ SECItem *inNickName,
+ PK11SlotInfo *inSlot,
+ CERTCertDBHandle *inCertdb,
+ SECKEYPrivateKey **destPrivKey,
+ void *wincx);
+
+/*
+ * FUNCTION: CMMF_KeyRecRepContentHasCACerts
+ * INPUTS:
+ * inKeyRecRecp
+ * The CMMFKeyRecRepContent to operate on.
+ * RETURN:
+ * This function returns PR_TRUE if there are one or more certificates in
+ * the sequence KeyRecRepContent.caCerts within the CMMFKeyRecRepContent
+ * structure. The function will return PR_FALSE if there are 0 certificate
+ * in the above mentioned sequence.
+ */
+extern PRBool
+CMMF_KeyRecRepContentHasCACerts(CMMFKeyRecRepContent *inKeyRecRep);
+
+/*
+ * FUNCTION: CMMF_POPODecKeyChallContDecryptChallenge
+ * INPUTS:
+ * inChalCont
+ * The CMMFPOPODecKeyChallContent to operate on.
+ * inIndex
+ * The index of the Challenge to operate on. The 1st Challenge is
+ * at index 0, the second at index 1 and so forth.
+ * 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 appropriate challenge. Make sure the private key matches
+ * the public key that was used to encrypt the witness. Use
+ * CMMF_POPODecKeyChallContentGetPublicValue to get the public value of
+ * the key used to encrypt the witness and then use that to determine the
+ * appropriate private key. This can be done by calling PK11_MakeIDFromPubKey
+ * and then passing that return value to PK11_FindKeyByKeyID. 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. This function also verifies
+ * that the sender and witness hashes match within 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_POPODecKeyChallContDecryptChallenge(CMMFPOPODecKeyChallContent *inChalCont,
+ int inIndex,
+ SECKEYPrivateKey *inPrivKey);
+
+/*
+ * 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);
+
+SEC_END_PROTOS
+#endif /* _CMMF_H_ */