/* -*- 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 _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 CRMFEncoderOuputCallback type is * defined for information on proper behavior of the funciton fn. * RETURN: * SECSuccess if encoding was successful. Any other return value * indicates an error occured 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 CRMFEncoderOuputCallback type is * defined for information on proper behavior of the funciton 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 (long 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 funciton 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 funciton looks at the the inKeyChoice parameter and interprets it in * in the following manner. * * If a parameter is not mentioned under interpretation, the funciton 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 funciton looks at the the inKeyChoice parameter and interprets it in * in the following manner. * * If a parameter is not mentioned under interpretation, the funciton 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 funciton 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 funciton 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_*/