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