Source code
Revision control
Copy as Markdown
Other Tools
/* -*- 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
#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_ */