/* -*- 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_ */