diff options
Diffstat (limited to 'security/nss/lib/crmf/crmf.h')
| -rw-r--r-- | security/nss/lib/crmf/crmf.h | 1782 |
1 files changed, 0 insertions, 1782 deletions
diff --git a/security/nss/lib/crmf/crmf.h b/security/nss/lib/crmf/crmf.h deleted file mode 100644 index 315100702..000000000 --- a/security/nss/lib/crmf/crmf.h +++ /dev/null @@ -1,1782 +0,0 @@ -/* -*- Mode: C; tab-width: 8 -*-*/ -/* ***** BEGIN LICENSE BLOCK ***** - * Version: MPL 1.1/GPL 2.0/LGPL 2.1 - * - * 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 the Initial Developer are Copyright (C) 1994-2000 - * the Initial Developer. All Rights Reserved. - * - * Contributor(s): - * - * Alternatively, the contents of this file may be used under the terms of - * either the GNU General Public License Version 2 or later (the "GPL"), or - * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), - * in which case the provisions of the GPL or the LGPL are applicable instead - * of those above. If you wish to allow use of your version of this file only - * under the terms of either the GPL or the LGPL, and not to allow others to - * use your version of this file under the terms of the MPL, indicate your - * decision by deleting the provisions above and replace them with the notice - * and other provisions required by the GPL or the LGPL. If you do not delete - * the provisions above, a recipient may use your version of this file under - * the terms of any one of the MPL, the GPL or the LGPL. - * - * ***** END LICENSE BLOCK ***** */ - - -#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 (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 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_*/ - - |