diff options
Diffstat (limited to 'security/nss/lib/crmf/crmf.h')
| -rw-r--r-- | security/nss/lib/crmf/crmf.h | 1741 |
1 files changed, 1741 insertions, 0 deletions
diff --git a/security/nss/lib/crmf/crmf.h b/security/nss/lib/crmf/crmf.h new file mode 100644 index 000000000..c56e28913 --- /dev/null +++ b/security/nss/lib/crmf/crmf.h @@ -0,0 +1,1741 @@ +/* -*- 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 _CRMF_H_ +#define _CRMF_H_ + +#include "seccomon.h" +#include "cert.h" +#include "crmft.h" +#include "secoid.h" +#include "secpkcs7.h" + +SEC_BEGIN_PROTOS + +/* + * FUNCTION: CRMF_EncodeCertReqMsg + * INPUTS: + * inCertReqMsg + * The Certificate Request Message to be encoded. + * fn + * A Callback function that the ASN1 encoder calls whenever + * the encoder wants to write out some DER encoded bytes. + * arg + * An opaque pointer that gets passed to the function fn + * OUTPUT: + * The function fn will be called multiple times. Look at the + * comments in crmft.h where the CRMFEncoderOutputCallback type is + * defined for information on proper behavior of the function fn. + * RETURN: + * SECSuccess if encoding was successful. Any other return value + * indicates an error occurred during encoding. + */ +extern SECStatus +CRMF_EncodeCertReqMsg(CRMFCertReqMsg *inCertReqMsg, + CRMFEncoderOutputCallback fn, + void *arg); + +/* + * FUNCTION: CRMF_EncoderCertRequest + * INPUTS: + * inCertReq + * The Certificate Request to be encoded. + * fn + * A Callback function that the ASN1 encoder calls whenever + * the encoder wants to write out some DER encoded bytes. + * arg + * An opaque pointer that gets passed to the function fn. + * OUTPUT: + * The function fn will be called, probably multiple times whenever + * the ASN1 encoder wants to write out DER-encoded bytes. Look at the + * comments in crmft.h where the CRMFEncoderOutputCallback type is + * defined for information on proper behavior of the function fn. + * RETURN: + * SECSuccess if encoding was successful. Any other return value + * indicates an error occurred during encoding. + */ +extern SECStatus CRMF_EncodeCertRequest(CRMFCertRequest *inCertReq, + CRMFEncoderOutputCallback fn, + void *arg); +/* + * FUNCTION: CRMF_EncodeCertReqMessages + * INPUTS: + * inCertReqMsgs + * An array of pointers to the Certificate Request Messages + * to encode. The user must place a NULL pointer in the index + * after the last message to be encoded. When the library runs + * into the NULL pointer, the library assumes there are no more + * messages to encode. + * fn + * A Callback function that the ASN1 encoder calls whenever + * the encoder wants to write out some DER encoded byts. + * arg + * An opaque pointer that gets passed to the function fn. + * + * NOTES: + * The parameter inCertReqMsgs needs to be an array with a NULL pointer + * to signal the end of messages. An array in the form of + * {m1, m2, m3, NULL, m4, ...} will only encode the messages m1, m2, and + * m3. All messages from m4 on will not be looked at by the library. + * + * OUTPUT: + * The function fn will be called, probably multiple times. Look at the + * comments in crmft.h where the CRMFEncoderOutputCallback type is + * defined for information on proper behavior of the function fn. + * + * RETURN: + * SECSuccess if encoding the Certificate Request Messages was successful. + * Any other return value indicates an error occurred while encoding the + * certificate request messages. + */ +extern SECStatus +CRMF_EncodeCertReqMessages(CRMFCertReqMsg **inCertReqMsgs, + CRMFEncoderOutputCallback fn, + void *arg); + +/* + * FUNCTION: CRMF_CreateCertReqMsg + * INPUTS: + * NONE + * OUTPUT: + * An empty CRMF Certificate Request Message. + * Before encoding this message, the user must set + * the ProofOfPossession field and the certificate + * request which are necessary for the full message. + * After the user no longer needs this CertReqMsg, + * the user must call CRMF_DestroyCertReqMsg to free + * all memory associated with the Certificate Request + * Message. + * RETURN: + * A pointer to a Certificate Request Message. The user + * must pass the return value of this function to + * CRMF_DestroyCertReqMsg after the Certificate Request + * Message is no longer necessary. + */ +extern CRMFCertReqMsg *CRMF_CreateCertReqMsg(void); + +/* + * FUNCTION: CRMF_DestroyCertReqMsg + * INPUTS: + * inCertReqMsg + * The Certificate Request Message to destroy. + * NOTES: + * This function frees all the memory used for the Certificate + * Request Message and all the memory used in making copies of + * fields of elelments of the message, eg. the Proof Of Possession + * filed and the Cetificate Request. + * RETURN: + * SECSuccess if destruction was successful. Any other return value + * indicates an error while trying to free the memory associated + * with inCertReqMsg. + * + */ +extern SECStatus CRMF_DestroyCertReqMsg(CRMFCertReqMsg *inCertReqMsg); + +/* + * FUNCTION: CRMF_CertReqMsgSetCertRequest + * INPUTS: + * inCertReqMsg + * The Certificate Request Message that the function will set + * the certificate request for. + * inCertReq + * The Certificate Request that will be added to the Certificate + * Request Message. + * NOTES: + * This function will make a copy of the Certificate Request passed in + * and store it as part of the Certificate Request Message. Therefore, + * the user must not call this function until the Certificate Request + * has been fully built and is ready to be encoded. + * RETURN: + * SECSuccess + * If copying the Certificate as a member of the Certificate + * request message was successful. + * Any other return value indicates a failure to copy the Certificate + * Request and make it a part of the Certificate Request Message. + */ +extern SECStatus CRMF_CertReqMsgSetCertRequest(CRMFCertReqMsg *inCertReqMsg, + CRMFCertRequest *inCertReq); + +/* + * FUNCTION: CRMF_CreateCertRequest + * INPUTS: + * inRequestID + * The ID that will be associated with this certificate request. + * OUTPUTS: + * A certificate request which only has the requestID set. + * NOTES: + * The user must call the function CRMF_DestroyCertRequest when + * the returned value is no longer needed. This is usually the + * case after fully constructing the Certificate Request and then + * calling the function CRMF_CertReqMsgSetCertRequest. + * RETURN: + * A pointer to the new Certificate Request. A NULL return value + * indicates an error in creating the Certificate Request. + */ +extern CRMFCertRequest *CRMF_CreateCertRequest(PRUint32 inRequestID); + +/* + * FUNCTION: CRMF_DestroyCertRequest + * INPUTS: + * inCertReq + * The Certificate Request that will be destroyed. + * RETURN: + * SECSuccess + * If freeing the memory associated with the certificate request + * was successful. + * Any other return value indicates an error while trying to free the + * memory. + */ +extern SECStatus CRMF_DestroyCertRequest(CRMFCertRequest *inCertReq); + +/* + * FUNCTION: CRMF_CreateCertExtension + * INPUTS: + * id + * The SECOidTag to associate with this CertExtension. This must + * correspond to a valid Certificate Extension, if not the function + * will fail. + * isCritical + * A boolean value stating if the extension value is crtical. PR_TRUE + * means the value is crtical. PR_FALSE indicates the value is not + * critical. + * data + * This is the data associated with the extension. The user of the + * library is responsible for making sure the value passed in is a + * valid interpretation of the certificate extension. + * NOTES: + * Use this function to create CRMFCertExtension Structures which will + * then be passed to CRMF_AddFieldToCertTemplate as part of the + * CRMFCertCreationInfo.extensions The user must call + * CRMF_DestroyCertExtension after the extension has been added to a certifcate + * and the extension is no longer needed. + * + * RETURN: + * A pointer to a newly created CertExtension. A return value of NULL + * indicates the id passed in was an invalid certificate extension. + */ +extern CRMFCertExtension *CRMF_CreateCertExtension(SECOidTag id, + PRBool isCritical, + SECItem *data); + +/* + * FUNCTION: CMRF_DestroyCertExtension + * INPUTS: + * inExtension + * The Cert Extension to destroy + * NOTES: + * Destroy a structure allocated by CRMF_CreateCertExtension. + * + * RETURN: + * SECSuccess if freeing the memory associated with the certificate extension + * was successful. Any other error indicates an error while freeing the + * memory. + */ +extern SECStatus CRMF_DestroyCertExtension(CRMFCertExtension *inExtension); + +/* + * FUNCTION: CRMF_CertRequestSetTemplateField + * INPUTS: + * inCertReq + * The Certificate Request to operate on. + * inTemplateField + * An enumeration that indicates which field of the Certificate + * template to add. + * data + * A generic pointer that will be type cast according to the + * table under NOTES and used as the key for adding to the + * certificate template; + * NOTES: + * + * Below is a table that tells what type to pass in as data + * depending on the template field one wants to set. + * + * Look in crmft.h for the definition of CRMFCertTemplateField. + * + * In all cases, the library makes copies of the data passed in. + * + * CRMFCertTemplateField Type of data What data means + * --------------------- ------------ --------------- + * crmfVersion long * The version of + * the certificate + * to be created. + * + * crmfSerialNumber long * The serial number + * for the cert to be + * created. + * + * crmfSigningAlg SECAlgorithm * The ASN.1 object ID for + * the algorithm used in encoding + * the certificate. + * + * crmfIssuer CERTName * Certificate Library + * representation of the ASN1 type + * Name from X.509 + * + * crmfValidity CRMFValidityCreationInfo * At least one of the two + * fields in the structure must + * be present. A NULL pointer + * in the structure indicates + * that member should not be + * added. + * + * crmfSubject CERTName * Certificate Library + * representation of the ASN1 type + * Name from X.509 + * + * crmfPublicKey CERTSubjectPublicKeyInfo * The public key info for the + * certificate being requested. + * + * crmfIssuerUID SECItem * A bit string representation + * of the issuer UID. NOTE: The + * length is the number of bits + * and not the number of bytes. + * + * crmfSubjectUID SECItem* A bit string representation + * of the subject UID. NOTE: The + * length is the number of bits + * and not the number of bytes. + * + * crmfExtension CRMFCertExtCreationInfo * A pointer to the structure + * populated with an array of + * of certificate extensions + * and an integer that tells + * how many elements are in the + * array. Look in crmft.h for + * the definition of + * CRMFCertExtCreationInfo + * RETURN: + * SECSuccess if adding the desired field to the template was successful. + * Any other return value indicates failure when trying to add the field + * to the template. + * + */ +extern SECStatus +CRMF_CertRequestSetTemplateField(CRMFCertRequest *inCertReq, + CRMFCertTemplateField inTemplateField, + void *data); + +/* + * FUNCTION: CRMF_CertRequestIsFieldPresent + * INPUTS: + * inCertReq + * The certificate request to operate on. + * inTemplateField + * The enumeration for the template field the user wants to query + * about. + * NOTES: + * This function checks to see if the the field associated with inTemplateField + * enumeration is already present in the certificate request passed in. + * + * RETURN: + * The function returns PR_TRUE if the field associated with inTemplateField + * is already present in the certificate request. If the field is not present + * the function returns PR_FALSE. + */ +extern PRBool +CRMF_CertRequestIsFieldPresent(CRMFCertRequest *inCertReq, + CRMFCertTemplateField inTemplateField); + +/* + * FUNCTION: CRMF_CertRequestIsControlPresent + * INPUTS: + * inCertReq + * The certificate request to operate on. + * inControlType + * The type of control to look for. + * NOTES: + * This function looks at the control present in the certificate request + * and returns PR_TRUE iff a control of type inControlType already exists. + * The CRMF draft does not explicitly state that two controls of the same + * type can not exist within the same request. So the library will not + * cause an error if you try to add a control and one of the same type + * already exists. It is up to the application to ensure that multiple + * controls of the same type do not exist, if that is the desired behavior + * by the application. + * + * RETURN: + * The function returns PR_TRUE if a control of type inControlType already + * exists in the certificate request. If a control of type inControlType + * does not exist, the function will return PR_FALSE. + */ +extern PRBool +CRMF_CertRequestIsControlPresent(CRMFCertRequest *inCertReq, + CRMFControlType inControlType); + +/* + * FUNCTION: CRMF_CertRequestSetRegTokenControl + * INPUTS: + * inCertReq + * The Certificate Request to operate on. + * value + * The UTF8 value which will be the Registration Token Control + * for this Certificate Request. + * NOTES: + * The library does no verification that the value passed in is + * a valid UTF8 value. The caller must make sure of this in order + * to get an encoding that is valid. The library will ultimately + * encode this value as it was passed in. + * RETURN: + * SECSucces on successful addition of the Registration Token Control. + * Any other return value indicates an unsuccessful attempt to add the + * control. + * + */ +extern SECStatus CRMF_CertRequestSetRegTokenControl(CRMFCertRequest *inCertReq, + SECItem *value); + +/* + * FUNCTION: CRMF_CertRequestSetAuthenticatorControl + * INPUTS: + * inCertReq + * The Certificate Request to operate on. + * value + * The UTF8 value that will become the Authenticator Control + * for the passed in Certificate Request. + * NOTES: + * The library does no verification that the value passed in is + * a valid UTF8 value. The caller must make sure of this in order + * to get an encoding that is valid. The library will ultimately + * encode this value as it was passed in. + * RETURN: + * SECSucces on successful addition of the Authenticator Control. + * Any other return value indicates an unsuccessful attempt to add the + * control. + */ +extern SECStatus +CRMF_CertRequestSetAuthenticatorControl(CRMFCertRequest *inCertReq, + SECItem *value); + +/* + * FUNCTION: CRMF_CreateEncryptedKeyWithencryptedValue + * INPUTS: + * inPrivKey + * This is the private key associated with a certificate that is + * being requested. This structure will eventually wind up as + * a part of the PKIArchiveOptions Control. + * inCACert + * This is the certificate for the CA that will be receiving the + * certificate request for the private key passed in. + * OUTPUT: + * A CRMFEncryptedKey that can ultimately be used as part of the + * PKIArchiveOptions Control. + * + * RETURN: + * A pointer to a CRMFEncyptedKey. A NULL return value indicates an erro + * during the creation of the encrypted key. + */ +extern CRMFEncryptedKey * +CRMF_CreateEncryptedKeyWithEncryptedValue(SECKEYPrivateKey *inPrivKey, + CERTCertificate *inCACert); + +/* + * FUNCTION: CRMF_DestroyEncryptedKey + * INPUTS: + * inEncrKey + * The CRMFEncryptedKey to be destroyed. + * NOTES: + * Frees all memory associated with the CRMFEncryptedKey passed in. + * RETURN: + * SECSuccess if freeing the memory was successful. Any other return + * value indicates an error while freeig the memroy. + */ +extern SECStatus CRMF_DestroyEncryptedKey(CRMFEncryptedKey *inEncrKey); + +/* + * FUNCTION: CRMF_CreatePKIArchiveOptions + * INPUTS: + * inType + * An enumeration value indicating which option for + * PKIArchiveOptions to use. + * data + * A pointer that will be type-cast and de-referenced according + * to the table under NOTES. + * NOTES: + * A table listing what should be passed in as data + * ------------------------------------------------ + * + * inType data + * ------ ---- + * crmfEncryptedPrivateKey CRMFEncryptedKey* + * crmfKeyGenParameters SECItem*(This needs to be an octet string) + * crmfArchiveRemGenPrivKey PRBool* + * + * RETURN: + * A pointer the a CRMFPKIArchiveOptions that can be added to a Certificate + * Request. A NULL pointer indicates an error occurred while creating + * the CRMFPKIArchiveOptions Structure. + */ +extern CRMFPKIArchiveOptions * +CRMF_CreatePKIArchiveOptions(CRMFPKIArchiveOptionsType inType, + void *data); +/* + * FUNCTION: CRMF_DestroyPKIArchiveOptions + * INPUTS: + * inArchOpt + * A pointer to the CRMFPKIArchiveOptions structure to free. + * NOTES: + * Will free all memory associated with 'inArchOpt'. + * RETURN: + * SECSuccess if successful in freeing the memory used by 'inArchOpt' + * Any other return value indicates an error while freeing the memory. + */ +extern SECStatus +CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inArchOpt); + +/* + * FUNCTION: CRMF_CertRequestSetPKIArchiveOptions + * INPUTS: + * inCertReq + * The Certificate Request to add the the options to. + * inOptions + * The Archive Options to add to the Certificate Request. + * NOTES: + * Adds the PKIArchiveOption to the Certificate Request. This is what + * enables Key Escrow to take place through CRMF. The library makes + * its own copy of the information. + * RETURN: + * SECSuccess if successful in adding the ArchiveOptions to the Certificate + * request. Any other return value indicates an error when trying to add + * the Archive Options to the Certificate Request. + */ +extern SECStatus +CRMF_CertRequestSetPKIArchiveOptions(CRMFCertRequest *inCertReq, + CRMFPKIArchiveOptions *inOptions); + +/* + * FUNCTION: CRMF_CertReqMsgGetPOPType + * INPUTS: + * inCertReqMsg + * The Certificate Request Message to operate on. + * NOTES: + * Returns an enumeration value indicating the method of Proof + * of Possession that was used for the passed in Certificate Request + * Message. + * RETURN: + * An enumeration indicating what method for Proof Of Possession is + * being used in this Certificate Request Message. Look in the file + * crmft.h for the definition of CRMFPOPChoice for the possible return + * values. + */ +extern CRMFPOPChoice CRMF_CertReqMsgGetPOPType(CRMFCertReqMsg *inCertReqMsg); + +/* + * FUNCTION: CRMF_CertReqMsgSetRAVerifiedPOP + * INPUT: + * InCertReqMsg + * The Certificate Request Message to operate on. + * NOTES: + * This function will set the method of Proof Of Possession to + * crmfRAVerified which means the RA has already verified the + * requester does possess the private key. + * RETURN: + * SECSuccess if adding RAVerified to the message is successful. + * Any other message indicates an error while trying to add RAVerified + * as the Proof of Possession. + */ +extern SECStatus CRMF_CertReqMsgSetRAVerifiedPOP(CRMFCertReqMsg *inCertReqMsg); + +/* + * FUNCTION: CRMF_CertReqMsgSetSignaturePOP + * INPUT: + * inCertReqMsg + * The Certificate Request Message to add the SignaturePOP to. + * inPrivKey + * The Private Key which corresponds to the the Certificate Request + * Message. + * inPubKey + * The Public Key which corresponds to the Private Key passed in. + * inCertForInput + * A Certificate that in the future may be used to create + * POPOSigningKeyInput. + * fn + * A callback for retrieving a password which may be used in the + * future to generate POPOSigningKeyInput. + * arg + * An opaque pointer that would be passed to fn whenever it is + * called. + * NOTES: + * Adds Proof Of Possession to the CertRequest using the signature field + * of the ProofOfPossession field. NOTE: In order to use this option, + * the certificate template must contain the publicKey at the very minimum. + * + * If you don't want the function to generate POPOSigningKeyInput, then + * make sure the cert template already contains the subject and public key + * values. Currently creating POPOSigningKeyInput is not supported, so + * a Message passed to this function must have the publicKey and the subject + * as part of the template + * + * This will take care of creating the entire POPOSigningKey structure + * that will become part of the message. + * + * inPrivKey is the key to be used in the signing operation when creating + * POPOSigningKey structure. This should be the key corresponding to + * the certificate being requested. + * + * inCertForInput will be used if POPOSigningKeyInput needs to be generated. + * It will be used in generating the authInfo.sender field. If the parameter + * is not passed in then authInfo.publicKeyMAC will be generated instead. + * If passed in, this certificate needs to be a valid certificate. + * + * The last 3 arguments are for future compatibility in case we ever want to + * support generating POPOSigningKeyInput. Pass in NULL for all 3 if you + * definitely don't want the function to even try to generate + * POPOSigningKeyInput. If you try to use POPOSigningKeyInput, the function + * will fail. + * + * RETURN: + * SECSuccess if adding the Signature Proof Of Possession worked. + * Any other return value indicates an error in trying to add + * the Signature Proof Of Possession. + */ +extern SECStatus +CRMF_CertReqMsgSetSignaturePOP(CRMFCertReqMsg *inCertReqMsg, + SECKEYPrivateKey *inPrivKey, + SECKEYPublicKey *inPubKey, + CERTCertificate *inCertForInput, + CRMFMACPasswordCallback fn, + void *arg); + +/* + * FUNCTION: CRMF_CertReqMsgSetKeyEnciphermentPOP + * INPUTS: + * inCertReqMsg + * The Certificate Request Message to operate on. + * inKeyChoice + * An enumeration indicating which POPOPrivKey Choice to use + * in constructing the KeyEnciphermentPOP. + * subseqMess + * This parameter must be provided iff inKeyChoice is + * crmfSubsequentMessage. This details how the RA is to respond + * in order to perform Proof Of Possession. Look in crmft.h under + * the definition of CRMFSubseqMessOptions for possible values. + * encPrivKey + * This parameter only needs to be provided if inKeyChoice is + * crmfThisMessage. The item should contain the encrypted private + * key. + * + * NOTES: + * Adds Proof Of Possession using the keyEncipherment field of + * ProofOfPossession. + * + * The function looks at the the inKeyChoice parameter and interprets it in + * in the following manner. + * + * If a parameter is not mentioned under interpretation, the function will not + * look at its value when implementing that case. + * + * inKeyChoice Interpretation + * ----------- -------------- + * crmfThisMessage This options requires that the encrypted private key + * be included in the thisMessage field of POPOPrivKey. + * We don't support this yet, so any clients who want + * to use this feature have to implement a wrapping + * function and agree with the server on how to properly + * wrap the key. That encrypted key must be passed in + * as the encPrivKey parameter. + * + * crmfSubequentMessage Must pass in a value for subseqMess. The value must + * be either CRMFEncrCert or CRMFChallengeResp. The + * parameter encPrivKey will not be looked at in this + * case. + * + * crmfDHMAC This is not a valid option for this function. Passing + * in this value will result in the function returning + * SECFailure. + * RETURN: + * SECSuccess if adding KeyEnciphermentPOP was successful. Any other return + * value indicates an error in adding KeyEnciphermentPOP. + */ +extern SECStatus +CRMF_CertReqMsgSetKeyEnciphermentPOP(CRMFCertReqMsg *inCertReqMsg, + CRMFPOPOPrivKeyChoice inKeyChoice, + CRMFSubseqMessOptions subseqMess, + SECItem *encPrivKey); + +/* + * FUNCTION: CRMF_CertReqMsgSetKeyAgreementPOP + * INPUTS: + * inCertReqMsg + * The Certificate Request Message to operate on. + * inKeyChoice + * An enumeration indicating which POPOPrivKey Choice to use + * in constructing the KeyAgreementPOP. + * subseqMess + * This parameter must be provided iff inKeyChoice is + * crmfSubsequentMessage. This details how the RA is to respond + * in order to perform Proof Of Possession. Look in crmft.h under + * the definition of CRMFSubseqMessOptions for possible values. + * encPrivKey + * This parameter only needs to be provided if inKeyChoice is + * crmfThisMessage. The item should contain the encrypted private + * key. + * Adds Proof Of Possession using the keyAgreement field of + * ProofOfPossession. + * + * The function looks at the the inKeyChoice parameter and interprets it in + * in the following manner. + * + * If a parameter is not mentioned under interpretation, the function will not + * look at its value when implementing that case. + * + * inKeyChoice Interpretation + * ----------- -------------- + * crmfThisMessage This options requires that the encrypted private key + * be included in the thisMessage field of POPOPrivKey. + * We don't support this yet, so any clients who want + * to use this feature have to implement a wrapping + * function and agree with the server on how to properly + * wrap the key. That encrypted key must be passed in + * as the encPrivKey parameter. + * + * crmfSubequentMessage Must pass in a value for subseqMess. The value must + * be either crmfEncrCert or crmfChallengeResp. The + * parameter encPrivKey will not be looked at in this + * case. + * + * crmfDHMAC This option is not supported. + */ +extern SECStatus +CRMF_CertReqMsgSetKeyAgreementPOP(CRMFCertReqMsg *inCertReqMsg, + CRMFPOPOPrivKeyChoice inKeyChoice, + CRMFSubseqMessOptions subseqMess, + SECItem *encPrivKey); + +/* + * FUNCTION: CRMF_CreateCertReqMsgFromDER + * INPUTS: + * buf + * A buffer to the DER-encoded Certificate Request Message. + * len + * The length in bytes of the buffer 'buf' + * NOTES: + * This function passes the buffer to the ASN1 decoder and creates a + * CRMFCertReqMsg structure. Do not try adding any fields to a message + * returned from this function. Specifically adding more Controls or + * Extensions may cause your program to crash. + * + * RETURN: + * A pointer to the Certificate Request Message structure. A NULL return + * value indicates the library was unable to parse the DER. + */ +extern CRMFCertReqMsg *CRMF_CreateCertReqMsgFromDER(const char *buf, long len); + +/* + * FUNCTION: CRMF_CreateCertReqMessagesFromDER + * INPUTS: + * buf + * A buffer to the DER-encoded Certificate Request Messages. + * len + * The length in bytes of buf + * NOTES: + * This function passes the buffer to the ASN1 decoder and creates a + * CRMFCertReqMessages structure. Do not try adding any fields to a message + * derived from this function. Specifically adding more Controls or + * Extensions may cause your program to crash. + * The user must call CRMF_DestroyCertReqMessages after the return value is + * no longer needed, ie when all individual messages have been extracted. + * + * RETURN: + * A pointer to the Certificate Request Messages structure. A NULL return + * value indicates the library was unable to parse the DER. + */ +extern CRMFCertReqMessages * +CRMF_CreateCertReqMessagesFromDER(const char *buf, long len); + +/* + * FUNCTION: CRMF_DestroyCertReqMessages + * INPUTS + * inCertReqMsgs + * The Messages to destroy. + * RETURN: + * SECSuccess if freeing the memory was done successfully. Any other + * return value indicates an error in freeing up memory. + */ +extern SECStatus +CRMF_DestroyCertReqMessages(CRMFCertReqMessages *inCertReqMsgs); + +/* + * FUNCTION: CRMF_CertReqMessagesGetNumMessages + * INPUTS: + * inCertReqMsgs + * The Request Messages to operate on. + * RETURN: + * The number of messages contained in the in the Request Messages + * strucure. + */ +extern int +CRMF_CertReqMessagesGetNumMessages(CRMFCertReqMessages *inCertReqMsgs); + +/* + * FUNCTION: CRMF_CertReqMessagesGetCertReqMsgAtIndex + * INPUTS: + * inReqMsgs + * The Certificate Request Messages to operate on. + * index + * The index of the single message the user wants a copy of. + * NOTES: + * This function returns a copy of the request messages stored at the + * index corresponding to the parameter 'index'. Indexing of the messages + * is done in the same manner as a C array. Meaning the valid index are + * 0...numMessages-1. User must call CRMF_DestroyCertReqMsg when done using + * the return value of this function. + * + * RETURN: + * SECSuccess if copying the message at the requested index was successful. + * Any other return value indicates an invalid index or error while copying + * the single request message. + */ +extern CRMFCertReqMsg * +CRMF_CertReqMessagesGetCertReqMsgAtIndex(CRMFCertReqMessages *inReqMsgs, + int index); + +/* + * FUNCTION: CRMF_CertReqMsgGetID + * INPUTS: + * inCertReqMsg + * The Certificate Request Message to get the ID from. + * destID + * A pointer to where the library can place the ID of the Message. + * RETURN: + * SECSuccess if the function was able to retrieve the ID and place it + * at *destID. Any other return value indicates an error meaning the value + * in *destId is un-reliable and should not be used by the caller of this + * function. + * + */ +extern SECStatus CRMF_CertReqMsgGetID(CRMFCertReqMsg *inCertReqMsg, + long *destID); + +/* + * FUNCTION: CRMF_DoesRequestHaveField + * INPUTS: + * inCertReq + * The Certificate Request to operate on. + * inField + * An enumeration indicating which filed of the certificate template + * to look for. + * NOTES: + * All the fields in a certificate template are optional. This function + * checks to see if the requested field is present. Look in crmft.h at the + * definition of CRMFCertTemplateField for possible values for possible + * querying. + * + * RETURN: + * PR_TRUE iff the field corresponding to 'inField' has been specified as part + * of 'inCertReq' + * PR_FALSE iff the field corresponding to 'inField' has not been speicified + * as part of 'inCertReq' + * + */ +extern PRBool CRMF_DoesRequestHaveField(CRMFCertRequest *inCertReq, + CRMFCertTemplateField inField); + +/* + * FUNCTION: CRMF_CertReqMsgGetCertRequest + * INPUTS: + * inCertReqMsg + * The Certificate Request Message to operate on. + * NOTES: + * This function returns a copy of the Certificate Request to the user. + * The user can keep adding to this request and then making it a part + * of another message. After the user no longer wants to use the + * returned request, the user must call CRMF_DestroyCertRequest and + * pass it the request returned by this function. + * RETURN: + * A pointer to a copy of the certificate request contained by the message. + * A NULL return value indicates an error occurred while copying the + * certificate request. + */ +extern CRMFCertRequest * +CRMF_CertReqMsgGetCertRequest(CRMFCertReqMsg *inCertReqMsg); + +/* + * FUNCTION: CRMF_CertRequestGetCertTemplateVersion + * INPUTS: + * inCertReq + * The Certificate Request to operate on. + * version + * A pointer to where the library can store the version contatined + * in the certificate template within the certifcate request. + * RETURN: + * SECSuccess if the Certificate template contains the version field. In + * this case, *version will hold the value of the certificate template + * version. + * SECFailure indicates that version field was not present as part of + * of the certificate template. + */ +extern SECStatus +CRMF_CertRequestGetCertTemplateVersion(CRMFCertRequest *inCertReq, + long *version); + +/* + * FUNCTION: CRMF_CertRequestGetCertTemplateSerialNumber + * INPUTS: + * inCertReq + * The certificate request to operate on. + * serialNumber + * A pointer where the library can put the serial number contained + * in the certificate request's certificate template. + * RETURN: + * If a serial number exists in the CertTemplate of the request, the function + * returns SECSuccess and the value at *serialNumber contains the serial + * number. + * If no serial number is present, then the function returns SECFailure and + * the value at *serialNumber is un-changed. + */ +extern SECStatus +CRMF_CertRequestGetCertTemplateSerialNumber(CRMFCertRequest *inCertReq, + long *serialNumber); + +/* + * FUNCTION: CRMF_CertRequestGetCertTemplateSigningAlg + * INPUT: + * inCertReq + * The Certificate Request to operate on. + * destAlg + * A Pointer to where the library can place a copy of the signing alg + * used in the cert request's cert template. + * RETURN: + * If the signingAlg is present in the CertRequest's CertTemplate, then + * the function returns SECSuccess and places a copy of sigingAlg in + * *destAlg. + * If no signingAlg is present, then the function returns SECFailure and + * the value at *destAlg is un-changed + */ +extern SECStatus +CRMF_CertRequestGetCertTemplateSigningAlg(CRMFCertRequest *inCertReq, + SECAlgorithmID *destAlg); +/* + * FUNCTION: CRMF_CertRequestGetCertTemplateIssuer + * INPUTS: + * inCertReq + * The Certificate Request to operate on. + * destIssuer + * A pointer to where the library can place a copy of the cert + * request's cert template issuer field. + * RETURN: + * If the issuer is present in the cert request cert template, the function + * returns SECSuccess and places a copy of the issuer in *destIssuer. + * If there is no issuer present, the function returns SECFailure and the + * value at *destIssuer is unchanged. + */ +extern SECStatus +CRMF_CertRequestGetCertTemplateIssuer(CRMFCertRequest *inCertReq, + CERTName *destIssuer); + +/* + * FUNCTION: CRMF_CertRequestGetCertTemplateValidity + * INPUTS: + * inCertReq + * The Certificate Request to operate on. + * destValdity + * A pointer to where the library can place a copy of the validity + * info in the cert request cert template. + * NOTES: + * Pass the pointer to + * RETURN: + * If there is an OptionalValidity field, the function will return SECSuccess + * and place the appropriate values in *destValidity->notBefore and + * *destValidity->notAfter. (Each field is optional, but at least one will + * be present if the function returns SECSuccess) + * + * If there is no OptionalValidity field, the function will return SECFailure + * and the values at *destValidity will be un-changed. + */ +extern SECStatus +CRMF_CertRequestGetCertTemplateValidity(CRMFCertRequest *inCertReq, + CRMFGetValidity *destValidity); +/* + * FUNCTION: CRMF_DestroyGetValidity + * INPUTS: + * inValidity + * A pointer to the memroy to be freed. + * NOTES: + * The function will free the memory allocated by the function + * CRMF_CertRequestGetCertTemplateValidity. That means only memory pointed + * to within the CRMFGetValidity structure. Since + * CRMF_CertRequestGetCertTemplateValidity does not allocate memory for the + * structure passed into it, it will not free it. Meaning this function will + * free the memory at inValidity->notBefore and inValidity->notAfter, but not + * the memory directly at inValdity. + * + * RETURN: + * SECSuccess if freeing the memory was successful. Any other return value + * indicates an error while freeing the memory. + */ +extern SECStatus +CRMF_DestroyGetValidity(CRMFGetValidity *inValidity); + +/* + * FUNCTION: CRMF_CertRequestGetCertTemplateSubject + * INPUTS: + * inCertReq + * The Certificate Request to operate on. + * destSubject + * A pointer to where the library can place a copy of the subject + * contained in the request's cert template. + * RETURN: + * If there is a subject in the CertTemplate, then the function returns + * SECSuccess and a copy of the subject is placed in *destSubject. + * + * If there is no subject, the function returns SECFailure and the values at + * *destSubject is unchanged. + */ +extern SECStatus +CRMF_CertRequestGetCertTemplateSubject(CRMFCertRequest *inCertReq, + CERTName *destSubject); + +/* + * FUNCTION: CRMF_CertRequestGetCertTemplatePublicKey + * INPUTS: + * inCertReq + * The Cert request to operate on. + * destPublicKey + * A pointer to where the library can place a copy of the request's + * cert template public key. + * RETURN: + * If there is a publicKey parameter in the CertRequest, the function returns + * SECSuccess, and places a copy of the publicKey in *destPublicKey. + * + * If there is no publicKey, the function returns SECFailure and the value + * at *destPublicKey is un-changed. + */ +extern SECStatus +CRMF_CertRequestGetCertTemplatePublicKey(CRMFCertRequest *inCertReq, + CERTSubjectPublicKeyInfo *destPublicKey); + +/* + * FUNCTION: CRMF_CertRequestGetCertTemplateIssuerUID + * INPUTS: + * inCertReq + * The Cert request to operate on. + * destIssuerUID + * A pointer to where the library can store a copy of the request's + * cert template destIssuerUID. + * + * NOTES: + * destIssuerUID is a bit string and will be returned in a SECItem as + * a bit string. Meaning the len field contains the number of valid bits as + * opposed to the number of bytes allocated. + * + * RETURN: + * If the CertTemplate has an issuerUID, the function returns SECSuccess and + * places a copy of the issuerUID in *destIssuerUID. + * + * If there is no issuerUID, the function returns SECFailure and the value + * *destIssuerUID is unchanged. + */ +extern SECStatus +CRMF_CertRequestGetCertTemplateIssuerUID(CRMFCertRequest *inCertReq, + SECItem *destIssuerUID); + +/* + * FUNCTION: CRMF_CertRequestGetCertTemplateSubjectUID + * inCertReq + * The Cert request to operate on. + * destSubjectUID + * A pointer to where the library can store a copy of the request's + * cert template destIssuerUID. + * + * NOTES: + * destSubjectUID is a bit string and will be returned in a SECItem as + * a bit string. Meaning the len field contains the number of valid bits as + * opposed to the number of bytes allocated. + * + * RETURN: + * If the CertTemplate has an issuerUID, the function returns SECSuccess and + * places a copy of the issuerUID in *destIssuerUID. + * + * If there is no issuerUID, the function returns SECSuccess and the value + * *destIssuerUID is unchanged. + */ +extern SECStatus CRMF_GetCertTemplateSubjectUID(CRMFCertRequest *inCertReq, + SECItem *destSubjectUID); + +/* + * FUNCTION: CRMF_CertRequestGetNumberOfExtensions + * INPUTS: + * inCertReq + * The cert request to operate on. + * RETURN: + * Returns the number of extensions contained by the Cert Request. + */ +extern int CRMF_CertRequestGetNumberOfExtensions(CRMFCertRequest *inCertReq); + +/* + * FUNCTION: CRMF_CertRequestGetExtensionAtIndex + * INPUTS: + * inCertReq + * The Certificate request to operate on. + * index + * The index of the extension array whihc the user wants to access. + * NOTES: + * This function retrieves the extension at the index corresponding to the + * parameter "index" indicates. Indexing is done like a C array. + * (0 ... numElements-1) + * + * Call CRMF_DestroyCertExtension when done using the return value. + * + * RETURN: + * A pointer to a copy of the extension at the desired index. A NULL + * return value indicates an invalid index or an error while copying + * the extension. + */ +extern CRMFCertExtension * +CRMF_CertRequestGetExtensionAtIndex(CRMFCertRequest *inCertReq, + int index); +/* + * FUNCTION: CRMF_CertExtensionGetOidTag + * INPUTS: + * inExtension + + * The extension to operate on. + * RETURN: + * Returns the SECOidTag associated with the cert extension passed in. + */ +extern SECOidTag CRMF_CertExtensionGetOidTag(CRMFCertExtension *inExtension); + +/* + * FUNCTION: CRMF_CertExtensionGetIsCritical + * INPUT: + * inExt + * The cert extension to operate on. + * + * RETURN: + * PR_TRUE if the extension is critical. + * PR_FALSE if the extension is not critical. + */ +extern PRBool CRMF_CertExtensionGetIsCritical(CRMFCertExtension *inExt); + +/* + * FUNCTION: CRMF_CertExtensionGetValue + * INPUT: + * inExtension + * The extension to operate on. + * NOTES: + * Caller is responsible for freeing the memory associated with the return + * value. Call SECITEM_FreeItem(retVal, PR_TRUE) when done using the return + * value. + * + * RETURN: + * A pointer to an item containig the value for the certificate extension. + * A NULL return value indicates an error in copying the information. + */ +extern SECItem *CRMF_CertExtensionGetValue(CRMFCertExtension *inExtension); + +/* + * FUNCTION: CRMF_CertReqMsgGetPOPOSigningKey + * INPUTS: + * inCertReqMsg + * The certificate request message to operate on. + * destKey + * A pointer to where the library can place a pointer to + * a copy of the Proof Of Possession Signing Key used + * by the message. + * + * RETURN: + * Get the POPOSigningKey associated with this CRMFCertReqMsg. + * If the CertReqMsg does not have a pop, the function returns + * SECFailure and the value at *destKey is un-changed.. + * + * If the CertReqMsg does have a pop, then the CertReqMsg's + * POPOSigningKey will be placed at *destKey. + */ +extern SECStatus +CRMF_CertReqMsgGetPOPOSigningKey(CRMFCertReqMsg *inCertReqMsg, + CRMFPOPOSigningKey **destKey); + +/* + * FUNCTION: CRMF_DestroyPOPOSigningKey + * INPUTS: + * inKey + * The signing key to free. + * + * RETURN: + * SECSuccess if freeing the memory was successful. Any other return value + * indicates an error while freeing memory. + */ +extern SECStatus CRMF_DestroyPOPOSigningKey(CRMFPOPOSigningKey *inKey); + +/* + * FUNCTION: CRMF_POPOSigningKeyGetAlgID + * INPUTS: + * inSignKey + * The Signing Key to operate on. + * RETURN: + * Return the algorithmID used by the CRMFPOPOSigningKey. User must + * call SECOID_DestroyAlgorithmID(destID, PR_TRUE) when done using the + * return value. + */ +extern SECAlgorithmID * +CRMF_POPOSigningKeyGetAlgID(CRMFPOPOSigningKey *inSignKey); + +/* + * FUNCTION: CRMF_POPOSigningKeyGetSignature + * INPUTS: + * inSignKey + * The Signing Key to operate on. + * + * RETURN: + * Get the actual signature stored away in the CRMFPOPOSigningKey. SECItem + * returned is a BIT STRING, so the len field is the number of bits as opposed + * to the total number of bytes allocatd. User must call + * SECITEM_FreeItem(retVal,PR_TRUE) when done using the return value. + */ +extern SECItem *CRMF_POPOSigningKeyGetSignature(CRMFPOPOSigningKey *inSignKey); + +/* + * FUNCTION: CRMF_POPOSigningKeyGetInput + * INPUTS: + * inSignKey + * The Signing Key to operate on. + * NOTES: + * This function will return the der encoded input that was read in while + * decoding. The API does not support this option when creating, so you + * cannot add this field. + * + * RETURN: + * Get the poposkInput that is part of the of the POPOSigningKey. If the + * optional field is not part of the POPOSigningKey, the function returns + * NULL. + * + * If the optional field is part of the POPOSingingKey, the function will + * return a copy of the der encoded poposkInput. + */ +extern SECItem *CRMF_POPOSigningKeyGetInput(CRMFPOPOSigningKey *inSignKey); + +/* + * FUNCTION: CRMF_CertReqMsgGetPOPKeyEncipherment + * INPUTS: + * inCertReqMsg + * The certificate request message to operate on. + * destKey + * A pointer to where the library can place a pointer to a + * copy of the POPOPrivKey representing Key Encipherment + * Proof of Possession. + *NOTES: + * This function gets the POPOPrivKey associated with this CRMFCertReqMsg + * for Key Encipherment. + * + * RETURN: + * If the CertReqMsg did not use Key Encipherment for Proof Of Possession, the + * function returns SECFailure and the value at *destKey is un-changed. + * + * If the CertReqMsg did use Key Encipherment for ProofOfPossession, the + * function returns SECSuccess and places the POPOPrivKey representing the + * Key Encipherment Proof Of Possessin at *destKey. + */ +extern SECStatus +CRMF_CertReqMsgGetPOPKeyEncipherment(CRMFCertReqMsg *inCertReqMsg, + CRMFPOPOPrivKey **destKey); + +/* + * FUNCTION: CRMF_CertReqMsgGetPOPKeyAgreement + * INPUTS: + * inCertReqMsg + * The certificate request message to operate on. + * destKey + * A pointer to where the library can place a pointer to a + * copy of the POPOPrivKey representing Key Agreement + * Proof of Possession. + * NOTES: + * This function gets the POPOPrivKey associated with this CRMFCertReqMsg for + * Key Agreement. + * + * RETURN: + * If the CertReqMsg used Key Agreement for Proof Of Possession, the + * function returns SECSuccess and the POPOPrivKey for Key Agreement + * is placed at *destKey. + * + * If the CertReqMsg did not use Key Agreement for Proof Of Possession, the + * function return SECFailure and the value at *destKey is unchanged. + */ +extern SECStatus +CRMF_CertReqMsgGetPOPKeyAgreement(CRMFCertReqMsg *inCertReqMsg, + CRMFPOPOPrivKey **destKey); + +/* + * FUNCTION: CRMF_DestroyPOPOPrivKey + * INPUTS: + * inPrivKey + * The POPOPrivKey to destroy. + * NOTES: + * Destroy a structure allocated by CRMF_GetPOPKeyEncipherment or + * CRMF_GetPOPKeyAgreement. + * + * RETURN: + * SECSuccess on successful destruction of the POPOPrivKey. + * Any other return value indicates an error in freeing the + * memory. + */ +extern SECStatus CRMF_DestroyPOPOPrivKey(CRMFPOPOPrivKey *inPrivKey); + +/* + * FUNCTION: CRMF_POPOPrivKeyGetChoice + * INPUT: + * inKey + * The POPOPrivKey to operate on. + * RETURN: + * Returns which choice was used in constructing the POPPOPrivKey. Look at + * the definition of CRMFPOPOPrivKeyChoice in crmft.h for the possible return + * values. + */ +extern CRMFPOPOPrivKeyChoice CRMF_POPOPrivKeyGetChoice(CRMFPOPOPrivKey *inKey); + +/* + * FUNCTION: CRMF_POPOPrivKeyGetThisMessage + * INPUTS: + * inKey + * The POPOPrivKey to operate on. + * destString + * A pointer to where the library can place a copy of the This Message + * field stored in the POPOPrivKey + * + * RETURN: + * Returns the field thisMessage from the POPOPrivKey. + * If the POPOPrivKey did not use the field thisMessage, the function + * returns SECFailure and the value at *destString is unchanged. + * + * If the POPOPrivKey did use the field thisMessage, the function returns + * SECSuccess and the BIT STRING representing thisMessage is placed + * at *destString. BIT STRING representation means the len field is the + * number of valid bits as opposed to the total number of bytes. + */ +extern SECStatus CRMF_POPOPrivKeyGetThisMessage(CRMFPOPOPrivKey *inKey, + SECItem *destString); + +/* + * FUNCTION: CRMF_POPOPrivKeyGetSubseqMess + * INPUTS: + * inKey + * The POPOPrivKey to operate on. + * destOpt + * A pointer to where the library can place the value of the + * Subsequent Message option used by POPOPrivKey. + * + * RETURN: + * Retrieves the field subsequentMessage from the POPOPrivKey. + * If the POPOPrivKey used the subsequentMessage option, the function + * returns SECSuccess and places the appropriate enumerated value at + * *destMessageOption. + * + * If the POPOPrivKey did not use the subsequenMessage option, the function + * returns SECFailure and the value at *destOpt is un-changed. + */ +extern SECStatus CRMF_POPOPrivKeyGetSubseqMess(CRMFPOPOPrivKey *inKey, + CRMFSubseqMessOptions *destOpt); + +/* + * FUNCTION: CRMF_POPOPrivKeyGetDHMAC + * INPUTS: + * inKey + * The POPOPrivKey to operate on. + * destMAC + * A pointer to where the library can place a copy of the dhMAC + * field of the POPOPrivKey. + * + * NOTES: + * Returns the field dhMAC from the POPOPrivKey. The populated SECItem + * is in BIT STRING format. + * + * RETURN: + * If the POPOPrivKey used the dhMAC option, the function returns SECSuccess + * and the BIT STRING for dhMAC will be placed at *destMAC. The len field in + * destMAC (ie destMAC->len) will be the valid number of bits as opposed to + * the number of allocated bytes. + * + * If the POPOPrivKey did not use the dhMAC option, the function returns + * SECFailure and the value at *destMAC is unchanged. + * + */ +extern SECStatus CRMF_POPOPrivKeyGetDHMAC(CRMFPOPOPrivKey *inKey, + SECItem *destMAC); + +/* + * FUNCTION: CRMF_CertRequestGetNumControls + * INPUTS: + * inCertReq + * The Certificate Request to operate on. + * RETURN: + * Returns the number of Controls registered with this CertRequest. + */ +extern int CRMF_CertRequestGetNumControls(CRMFCertRequest *inCertReq); + +/* + * FUNCTION: CRMF_CertRequestGetControlAtIndex + * INPUTS: + * inCertReq + * The certificate request to operate on. + * index + * The index of the control the user wants a copy of. + * NOTES: + * Function retrieves the Control at located at index. The Controls + * are numbered like a traditional C array (0 ... numElements-1) + * + * RETURN: + * Returns a copy of the control at the index specified. This is a copy + * so the user must call CRMF_DestroyControl after the return value is no + * longer needed. A return value of NULL indicates an error while copying + * the control or that the index was invalid. + */ +extern CRMFControl * +CRMF_CertRequestGetControlAtIndex(CRMFCertRequest *inCertReq, + int index); + +/* + * FUNCTION: CRMF_DestroyControl + * INPUTS: + * inControl + * The Control to destroy. + * NOTES: + * Destroy a CRMFControl allocated by CRMF_GetControlAtIndex. + * + * RETURN: + * SECSuccess if freeing the memory was successful. Any other return + * value indicates an error while freeing the memory. + */ +extern SECStatus CRMF_DestroyControl(CRMFControl *inControl); + +/* + * FUNCTION: CRMF_ControlGetControlType + * INPUTS: + * inControl + * The control to operate on. + * NOTES: + * The function returns an enumertion which indicates the type of control + * 'inControl'. + * + * RETURN: + * Look in crmft.h at the definition of the enumerated type CRMFControlType + * for the possible return values. + */ +extern CRMFControlType CRMF_ControlGetControlType(CRMFControl *inControl); + +/* + * FUNCTION: CRMF_ControlGetRegTokenControlValue + * INPUTS: + * inControl + * The Control to operate on. + * NOTES: + * The user must call SECITEM_FreeItem passing in the return value + * after the returnvalue is no longer needed. + + * RETURN: + * Return the value for a Registration Token Control. + * The SECItem returned should be in UTF8 format. A NULL + * return value indicates there was no Registration Control associated + * with the Control. + * (This library will not verify format. It assumes the client properly + * formatted the strings when adding it or the message decoded was properly + * formatted. The library will just give back the bytes it was given.) + */ +extern SECItem *CRMF_ControlGetRegTokenControlValue(CRMFControl *inControl); + +/* + * FUNCTION: CRMF_ControlGetAuthenticatorControlValue + * INPUTS: + * inControl + * The Control to operate on. + * NOTES: + * The user must call SECITEM_FreeItem passing in the return value + * after the returnvalue is no longer needed. + * + * RETURN: + * Return the value for the Authenticator Control. + * The SECItem returned should be in UTF8 format. A NULL + * return value indicates there was no Authenticator Control associated + * with the CRMFControl.. + * (This library will not verify format. It assumes the client properly + * formatted the strings when adding it or the message decoded was properly + * formatted. The library will just give back the bytes it was given.) + */ +extern SECItem *CRMF_ControlGetAuthicatorControlValue(CRMFControl *inControl); + +/* + * FUNCTION: CRMF_ControlGetPKIArchiveOptions + * INPUTS:inControl + * The Control tooperate on. + * NOTES: + * This function returns a copy of the PKIArchiveOptions. The user must call + * the function CRMF_DestroyPKIArchiveOptions when the return value is no + * longer needed. + * + * RETURN: + * Get the PKIArchiveOptions associated with the Control. A return + * value of NULL indicates the Control was not a PKIArchiveOptions + * Control. + */ +extern CRMFPKIArchiveOptions * +CRMF_ControlGetPKIArchiveOptions(CRMFControl *inControl); + +/* + * FUNCTION: CMRF_DestroyPKIArchiveOptions + * INPUTS: + * inOptions + * The ArchiveOptions to destroy. + * NOTE: + * Destroy the CRMFPKIArchiveOptions structure. + * + * RETURN: + * SECSuccess if successful in freeing all the memory associated with + * the PKIArchiveOptions. Any other return value indicates an error while + * freeing the PKIArchiveOptions. + */ +extern SECStatus +CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inOptions); + +/* + * FUNCTION: CRMF_PKIArchiveOptionsGetOptionType + * INPUTS: + * inOptions + * The PKIArchiveOptions to operate on. + * RETURN: + * Returns the choice used for the PKIArchiveOptions. Look at the definition + * of CRMFPKIArchiveOptionsType in crmft.h for possible return values. + */ +extern CRMFPKIArchiveOptionsType +CRMF_PKIArchiveOptionsGetOptionType(CRMFPKIArchiveOptions *inOptions); + +/* + * FUNCTION: CRMF_PKIArchiveOptionsGetEncryptedPrivKey + * INPUTS: + * inOpts + * The PKIArchiveOptions to operate on. + * + * NOTES: + * The user must call CRMF_DestroyEncryptedKey when done using this return + * value. + * + * RETURN: + * Get the encryptedPrivKey field of the PKIArchiveOptions structure. + * A return value of NULL indicates that encryptedPrivKey was not used as + * the choice for this PKIArchiveOptions. + */ +extern CRMFEncryptedKey * +CRMF_PKIArchiveOptionsGetEncryptedPrivKey(CRMFPKIArchiveOptions *inOpts); + +/* + * FUNCTION: CRMF_EncryptedKeyGetChoice + * INPUTS: + * inEncrKey + * The EncryptedKey to operate on. + * + * NOTES: + * Get the choice used for representing the EncryptedKey. + * + * RETURN: + * Returns the Choice used in representing the EncryptedKey. Look in + * crmft.h at the definition of CRMFEncryptedKeyChoice for possible return + * values. + */ +extern CRMFEncryptedKeyChoice +CRMF_EncryptedKeyGetChoice(CRMFEncryptedKey *inEncrKey); + +/* + * FUNCTION: CRMF_EncryptedKeyGetEncryptedValue + * INPUTS: + * inKey + * The EncryptedKey to operate on. + * + * NOTES: + * The user must call CRMF_DestroyEncryptedValue passing in + * CRMF_GetEncryptedValue's return value. + * + * RETURN: + * A pointer to a copy of the EncryptedValue contained as a member of + * the EncryptedKey. + */ +extern CRMFEncryptedValue * +CRMF_EncryptedKeyGetEncryptedValue(CRMFEncryptedKey *inKey); + +/* + * FUNCTION: CRMF_DestroyEncryptedValue + * INPUTS: + * inEncrValue + * The EncryptedValue to destroy. + * + * NOTES: + * Free up all memory associated with 'inEncrValue'. + * + * RETURN: + * SECSuccess if freeing up the memory associated with the EncryptedValue + * is successful. Any other return value indicates an error while freeing the + * memory. + */ +extern SECStatus CRMF_DestroyEncryptedValue(CRMFEncryptedValue *inEncrValue); + +/* + * FUNCTION: CRMF_EncryptedValueGetEncValue + * INPUTS: + * inEncValue + * The EncryptedValue to operate on. + * NOTES: + * Function retrieves the encValue from an EncryptedValue structure. + * + * RETURN: + * A poiner to a SECItem containing the encValue of the EncryptedValue + * structure. The return value is in BIT STRING format, meaning the + * len field of the return structure represents the number of valid bits + * as opposed to the allocated number of bytes. + * ANULL return value indicates an error in copying the encValue field. + */ +extern SECItem *CRMF_EncryptedValueGetEncValue(CRMFEncryptedValue *inEncValue); + +/* + * FUNCTION: CRMF_EncryptedValueGetIntendedAlg + * INPUTS + * inEncValue + * The EncryptedValue to operate on. + * NOTES: + * Retrieve the IntendedAlg field from the EncryptedValue structure. + * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using + * the return value. When present, this alogorithm is the alogrithm for + * which the private key will be used. + * + * RETURN: + * A Copy of the intendedAlg field. A NULL return value indicates the + * optional field was not present in the structure. + */ +extern SECAlgorithmID * +CRMF_EncryptedValueGetIntendedAlg(CRMFEncryptedValue *inEncValue); + +/* + * FUNCTION: CRMF_EncryptedValueGetSymmAlg + * INPUTS + * inEncValue + * The EncryptedValue to operate on. + * NOTES: + * Retrieve the symmAlg field from the EncryptedValue structure. + * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using + * the return value. When present, this is algorithm used to + * encrypt the encValue of the EncryptedValue. + * + * RETURN: + * A Copy of the symmAlg field. A NULL return value indicates the + * optional field was not present in the structure. + */ +extern SECAlgorithmID * +CRMF_EncryptedValueGetSymmAlg(CRMFEncryptedValue *inEncValue); + +/* + * FUNCTION: CRMF_EncryptedValueGetKeyAlg + * INPUTS + * inEncValue + * The EncryptedValue to operate on. + * NOTES: + * Retrieve the keyAlg field from the EncryptedValue structure. + * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using + * the return value. When present, this is the algorithm used to encrypt + * the symmetric key in the encSymmKey field of the EncryptedValue structure. + * + * RETURN: + * A Copy of the keyAlg field. A NULL return value indicates the + * optional field was not present in the structure. + */ +extern SECAlgorithmID * +CRMF_EncryptedValueGetKeyAlg(CRMFEncryptedValue *inEncValue); + +/* + * FUNCTION: CRMF_EncryptedValueGetValueHint + * INPUTS: + * inEncValue + * The EncryptedValue to operate on. + * + * NOTES: + * Return a copy of the der-encoded value hint. + * User must call SECITEM_FreeItem(retVal, PR_TRUE) when done using the + * return value. When, present, this is a value that the client which + * originally issued a certificate request can use to reproduce any data + * it wants. The RA does not know how to interpret this data. + * + * RETURN: + * A copy of the valueHint field of the EncryptedValue. A NULL return + * value indicates the optional valueHint field is not present in the + * EncryptedValue. + */ +extern SECItem * +CRMF_EncryptedValueGetValueHint(CRMFEncryptedValue *inEncValue); + +/* + * FUNCTION: CRMF_EncrypteValueGetEncSymmKey + * INPUTS: + * inEncValue + * The EncryptedValue to operate on. + * + * NOTES: + * Return a copy of the encSymmKey field. This field is the encrypted + * symmetric key that the client uses in doing Public Key wrap of a private + * key. When present, this is the symmetric key that was used to wrap the + * private key. (The encrypted private key will be stored in encValue + * of the same EncryptedValue structure.) The user must call + * SECITEM_FreeItem(retVal, PR_TRUE) when the return value is no longer + * needed. + * + * RETURN: + * A copy of the optional encSymmKey field of the EncryptedValue structure. + * The return value will be in BIT STRING format, meaning the len field will + * be the number of valid bits as opposed to the number of bytes. A return + * value of NULL means the optional encSymmKey field was not present in + * the EncryptedValue structure. + */ +extern SECItem * +CRMF_EncryptedValueGetEncSymmKey(CRMFEncryptedValue *inEncValue); + +/* + * FUNCTION: CRMF_PKIArchiveOptionsGetKeyGenParameters + * INPUTS: + * inOptions + * The PKiArchiveOptions to operate on. + * + * NOTES: + * User must call SECITEM_FreeItem(retVal, PR_TRUE) after the return + * value is no longer needed. + * + * RETURN: + * Get the keyGenParameters field of the PKIArchiveOptions. + * A NULL return value indicates that keyGenParameters was not + * used as the choice for this PKIArchiveOptions. + * + * The SECItem returned is in BIT STRING format (ie, the len field indicates + * number of valid bits as opposed to allocated number of bytes.) + */ +extern SECItem * +CRMF_PKIArchiveOptionsGetKeyGenParameters(CRMFPKIArchiveOptions *inOptions); + +/* + * FUNCTION: CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey + * INPUTS: + * inOpt + * The PKIArchiveOptions to operate on. + * destVal + * A pointer to where the library can place the value for + * arciveRemGenPrivKey + * RETURN: + * If the PKIArchiveOptions used the archiveRemGenPrivKey field, the + * function returns SECSuccess and fills the value at *destValue with either + * PR_TRUE or PR_FALSE, depending on what the PKIArchiveOptions has as a + * value. + * + * If the PKIArchiveOptions does not use the archiveRemGenPrivKey field, the + * function returns SECFailure and the value at *destValue is unchanged. + */ +extern SECStatus +CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey(CRMFPKIArchiveOptions *inOpt, + PRBool *destVal); + +/* Helper functions that can be used by other libraries. */ +/* + * A quick helper function to get the best wrap mechanism. + */ +extern CK_MECHANISM_TYPE CRMF_GetBestWrapPadMechanism(PK11SlotInfo *slot); + +/* + * A helper function to get a randomly generated IV from a mechanism + * type. + */ +extern SECItem *CRMF_GetIVFromMechanism(CK_MECHANISM_TYPE mechType); + +SEC_END_PROTOS +#endif /*_CRMF_H_*/ |