mozilla-central/security/nss/lib/crmf/crmf.h (file symbol)

Source code

Revision control

Copy as Markdown

Other Tools

/* -*- 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_*/