diff options
Diffstat (limited to 'security/nss/lib/crmf/cmmf.h')
| -rw-r--r-- | security/nss/lib/crmf/cmmf.h | 1119 |
1 files changed, 1119 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..a10220429 --- /dev/null +++ b/security/nss/lib/crmf/cmmf.h @@ -0,0 +1,1119 @@ +/* -*- Mode: C; tab-width: 8 -*-*/ +/* + * The contents of this file are subject to the Mozilla Public + * License Version 1.1 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.mozilla.org/MPL/ + * + * Software distributed under the License is distributed on an "AS + * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or + * implied. See the License for the specific language governing + * rights and limitations under the License. + * + * The Original Code is the Netscape security libraries. + * + * The Initial Developer of the Original Code is Netscape + * Communications Corporation. Portions created by Netscape are + * Copyright (C) 1994-2000 Netscape Communications Corporation. All + * Rights Reserved. + * + * Contributor(s): + * + * Alternatively, the contents of this file may be used under the + * terms of the GNU General Public License Version 2 or later (the + * "GPL"), in which case the provisions of the GPL are applicable + * instead of those above. If you wish to allow use of your + * version of this file only under the terms of the GPL and not to + * allow others to use your version of this file under the MPL, + * indicate your decision by deleting the provisions above and + * replace them with the notice and other provisions required by + * the GPL. If you do not delete the provisions above, a recipient + * may use your version of this file under either the MPL or the + * GPL. + */ + +#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 funciton 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_ */ |