CPKIFEnvelopedData Class Reference

#include <EnvelopedData.h>

Inheritance diagram for CPKIFEnvelopedData:

Inheritance graph
[legend]
Collaboration diagram for CPKIFEnvelopedData:

Collaboration graph
[legend]

List of all members.

Detailed Description

This class supports creation of enveloped messages using the CMS EnvelopedData format. EnvelopedData messages are used to convey encrypted content along with information about the key material used to perform the encryption. Typically, a randomly generated symmetric key is used to encrypt the content then encrypted using the public key of each recipient. The encrypted symmetric key is included in the EnvelopedData message for use by the recipient when decrypting the content.

This class requires access to a mediator/colleague collection for cryptographic and path processing functionality. The following interfaces are required based on the types of operations that can be performed using this class:

TSP-enforcing: Yes

Definition at line 56 of file EnvelopedData.h.


Public Types

enum  CMSVersion {
  CMSv0 = 0, CMSv1 = 1, CMSv2 = 2, CMSv3 = 3,
  CMSv4 = 4
}

Public Member Functions

 CPKIFEnvelopedData ()
virtual ~CPKIFEnvelopedData ()
CMSVersion GetVersion () const
void AddOriginatorCertificate (CPKIFCertificatePtr &cert)
void AddOriginatorCRL (CPKIFCRLPtr &crl)
void SetOriginatorCredential (CPKIFCredentialPtr &cred)
void GetOriginatorCertificates (CPKIFCertificateList &certs)
void GetOriginatorCRLs (CPKIFCRLList &crls)
void GetRecipientInfos (CPKIFRecipientInfoList &recipInfos) const
void AddRecipient (CPKIFCertificatePtr &cert, CMSPathValidationStatus minStatus=PVS_REV_STATUS_VERIFIED)
void AddRecipient (CPKIFCertificatePtr &cert, CPKIFCertificatePathPtr &path, CPKIFPathValidationResultsPtr &valResults, CMSPathValidationStatus minStatus=PVS_REV_STATUS_VERIFIED)
void AddRecipient (CPKIFKEKRecipInfoDetailsPtr &kek)
void SetDataToEncrypt (CPKIFEncryptedContentInfoPtr &buf)
CPKIFEncryptedContentInfoPtr GetEncryptedData () const
void AddUnprotectedAttribute (CPKIFAttributePtr &attr)
void GetUnprotectedAttributes (CPKIFAttributeList &ual)
void GetEncodedUnprotectedAttributes (CPKIFBufferPtr &buf)
void _GetUnprotectedAttributes (std::vector< CPKIFAttributePtr > attrVector)
template<class T>
boost::shared_ptr< T > GetUnprotectedAttribute ()
void ClearContent ()
void SetAlgorithmAndMode (PKIFCRYPTO::SYMKEY_ALG alg, PKIFCRYPTO::SYMKEY_MODE mode)
PKIFCRYPTO::SYMKEY_ALG GetAlgorithm () const
PKIFCRYPTO::SYMKEY_MODE GetMode () const
CPKIFBufferPtr Encode ()
void Decode (CPKIFBufferPtr &buf)
void SetPathSettings (CPKIFPathSettingsPtr &settings)
CPKIFBufferPtr Decrypt (CPKIFCredentialPtr &cred)
CPKIFBufferPtr Decrypt (CPKIFKEKRecipInfoDetailsPtr &kek)
void GetAddedUnprotectedAttributes (std::vector< CPKIFAttributePtr > &attr)
void SetMediator (IPKIFMediatorPtr &m)
IPKIFMediatorPtr GetMediator ()

Friends

struct CPKIFEnvelopedDataImpl

Member Enumeration Documentation

enum CPKIFEnvelopedData::CMSVersion

Enumerator:
CMSv0 
CMSv1 
CMSv2 
CMSv3 
CMSv4 

Definition at line 62 of file EnvelopedData.h.

Constructor & Destructor Documentation

CPKIFEnvelopedData::CPKIFEnvelopedData (  ) 

Interface: External

CPKIFEnvelopedData has one default constructor. Following construction, it is necessary to associate a mediator object via a call to AddMediator prior to performing any security-related operations. The following default values are initialized in this constructor:

  • Version: CMSv0
  • Algorithm: TDES
  • Mode: CBC

Returns:
None

Definition at line 144 of file EnvelopedData.cpp.

References PKIFCRYPTO::CBC, CMSv0, g_envelopedData, LOG_STRING_DEBUG, CPKIFContentType::SetContentType(), PKIFCRYPTO::TDES, and TOOLKIT_CRYPTO_MISC.

CPKIFEnvelopedData::~CPKIFEnvelopedData (  )  [virtual]

Interface: External

This function destroys an instance of CPKIFEnvelopedData.

Returns:
None

Definition at line 165 of file EnvelopedData.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

Member Function Documentation

CPKIFEnvelopedData::CMSVersion CPKIFEnvelopedData::GetVersion (  )  const

Interface: External

This function returns the version number of the associated EnvelopedData object. See RFC3369 for the information regarding the meaning of the version number. The Version property is set to CMSv0 by the constructor and by ClearContent. Other values may be set when Decode is invoked.

typedef enum 
{
	CMSv0 = 0,
	CMSv1 = 1,
	CMSv2 = 2,
	CMSv3 = 3,
	CMSv4 = 4
} CMSVersion;

Returns:
The version number of the associated EnvelopedData object.

Definition at line 304 of file EnvelopedData.cpp.

void CPKIFEnvelopedData::AddOriginatorCertificate ( CPKIFCertificatePtr &  cert  ) 

Interface: External

This functions are used to add a certificate to the set of originator certificates associated with a message . No validation of certificates is performed. The certificate(s) will simply be added to the set.

Returns:
None
Exceptions:
CPKIFMessageException(COMMON_INVALID_INPUT) 
Parameters:
cert  [in] Reference to a smart pointer to a CPKIFCertificate object containing a certificate to add to the set of originator certificates included in the EnvelopedData message

Definition at line 449 of file EnvelopedData.cpp.

References COMMON_INVALID_INPUT, GetOriginatorCertificates(), LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

void CPKIFEnvelopedData::AddOriginatorCRL ( CPKIFCRLPtr &  crl  ) 

Interface: External

Theis function is used to add a CRL to the set of originator CRL(s) associated with a message.

Returns:
None
Exceptions:
CPKIFMessageException(COMMON_INVALID_INPUT) 
Parameters:
crl  [in] Reference to a smart pointer to a CPKIFCRL object to add to the collection of originator CRLs included in an EnvelopedData message

Definition at line 547 of file EnvelopedData.cpp.

References COMMON_INVALID_INPUT, GetOriginatorCRLs(), LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

void CPKIFEnvelopedData::SetOriginatorCredential ( CPKIFCredentialPtr &  cred  ) 

Interface: External

This function is used to set a credential for the originator, for key agreement schemes that require use of a private key. Even if the credential has an associated certificate, this will not automatically add it to the cert bag. The caller must also call AddOriginatorCertificate() to add that if it's desirable.

If this credential is to be used with a key agreement scheme, it must have appropriate parameters associated with it. These will not be checked until encode time.

Returns:
None
Exceptions:
CPKIFMessageException(COMMON_INVALID_INPUT) 

Definition at line 587 of file EnvelopedData.cpp.

void CPKIFEnvelopedData::GetOriginatorCertificates ( CPKIFCertificateList &  certs  ) 

Interface: External

This function is used to retrieve the set of originator certificates associated with a message. No validation of certificates is performed. The certificate(s) will simply be retrieved.

Returns:
None
Parameters:
certs  [out] Reference to a CPKIFCertificateList object to receive the set of originator certificates included in the EnvelopedData message

Definition at line 482 of file EnvelopedData.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

Referenced by AddOriginatorCertificate().

void CPKIFEnvelopedData::GetOriginatorCRLs ( CPKIFCRLList &  crls  ) 

Interface: External

This function is used to retrieve the set of CRLs associated with a message.

Returns:
None
Parameters:
crls  [out] Reference to a CPKIFCRLList object to receive the set of originator CRLs included in an EnvelopedData message

Definition at line 599 of file EnvelopedData.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

Referenced by AddOriginatorCRL().

void CPKIFEnvelopedData::GetRecipientInfos ( CPKIFRecipientInfoList &  recipInfos  )  const

Interface: External

This function is used to populate a list with the recipient info objects that are held by the enveloped data object instance. The list is cleared prior to being populated.

Returns:
None
Parameters:
recipInfos  [out] Reference to a CPKIFRecipientInfoList object to receive the set of recipients included in an EnvelopedData message

Definition at line 951 of file EnvelopedData.cpp.

References CACASNWRAPPER_CREATE, data, LOG_STRING_DEBUG, m_impl, and TOOLKIT_CRYPTO_MISC.

void CPKIFEnvelopedData::AddRecipient ( CPKIFCertificatePtr &  cert,
CMSPathValidationStatus  minStatus = PVS_REV_STATUS_VERIFIED 
)

Interface: External

This function is used to add recipients (i.e. entities for which the message is to be encrypted) to a message. Recipient information can be specified via a CPKIFCertificate object. A CPKIFCertificate object is used when the public key of a recipient is used to encrypt the content encryption key.

When using a certificate, a certification path can be constructed and validated (including enforcement of key encipherment key usage) when this function is called. The two-parameter version of this function can be used when the results of the path building and validation operation need not be inspected. The four-parameter version can be used to retrieve the path and validation results from the path building and validation operation. The minStatus parameter can be used to turn off path validation of the recipient (e.g., by passing PVS_NOT_VALIDATED) or to control the minimum acceptable level of validation, for example, to permit addition recipients for which revocation information is not available. If path processing is attempted but the minimum acceptable status is not met, this function will generate an exception indicating MSG_INVALID_RECIP.

If the cert parameter is NULL (or empty), an exception indicating COMMON_INVALID_INPUT will be thrown. Where path processing is performed, the IPKIFPathBuild and IPKIFPathValidate interfaces must be available. The mediator object providing access to these interfaces must be specified via a call to AddMediator prior to invoking this function. If the necessary interfaces are not available, an exception indicating COMMON_MEDIATOR_MISSING will be thrown. If the certificate in the cert parameter is not an encryption certificate, an exception indicating MSG_INVALID_RECIP will be thrown.

Returns:
None
Exceptions:
CPKIFMessageException(COMMON_INVALID_INPUT) 
CPKIFMessageException(COMMON_MEDIATOR_MISSING) 
CPKIFMessageException(MSG_INVALID_RECIP) 
CPKIFCryptoException(PKIFCAPI_VERIFY_FAILED) 
CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED) 
CPKIFCryptoException(COMMON_INVALID_INPUT) 
CPKIFPathException(COMMON_MEDIATOR_MISSING) 
CPKIFPathException(COMMON_INVALID_INPUT) 
CPKIFPathException(COMMON_UNSUPPORTED_ALG) 
CPKIFCacheException(CACHE_LDAP_ERROR) 
CPKIFCacheException(CACHE_PARSE_ERROR) 
CPKIFCacheException(CACHE_UPDATE_FAILED) 
CPKIFCacheException(COMMON_NOT_INITIALIZED) 
CPKIFCacheException(CACHE_CERT_STORE_OPEN_FAILED) 
CPKIFCacheException(CACHE_PARSE_ERROR) 
CPKIFException(COMMON_INVALID_INPUT) 
CPKIFException(COMMON_NOT_IMPLEMENTED) 
Parameters:
cert  [in] Reference to a smart pointer to a CPKIFCertificate object containing the certificate of an intended recipient of the EnvelopedData message. If the object passed via this parameter is NULL or empty, a CPKIFMessageException is thrown indicating COMMON_INVALID_INPUT.
minStatus  [in] CMSPathValidationStatus value representing the minimum acceptable path validation result that must be achieved to accept the recipient certificate passed via the cert parameter as a recipient. If PVS_NOT_VALIDATED is passed via this parameter, the certificate is simply added as a recipient without performing path processing. If the minimum status is not met, an exception indicating MSG_INVALID_RECIP is thrown and the recipient is not added to the list of recipients.

Definition at line 702 of file EnvelopedData.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

void CPKIFEnvelopedData::AddRecipient ( CPKIFCertificatePtr &  cert,
CPKIFCertificatePathPtr &  path,
CPKIFPathValidationResultsPtr &  valResults,
CMSPathValidationStatus  minStatus = PVS_REV_STATUS_VERIFIED 
)

Interface: External

This function is used to add recipients (i.e. entities for which the message is to be encrypted) to a message. Recipient information can be specified via CPKIFKARIDetails object. A CPKIFKARIDetails object is used when a key agreement scheme should be used to determine a shared secret which will be used to encrypt the CEK for one or more recipients.

Returns:
None
Exceptions:
CPKIFMessageException(COMMON_INVALID_INPUT) Interface: External
This function is used to add recipients (i.e. entities for which the message is to be encrypted) to a message. Recipient information can be specified via a CPKIFCertificate object. A CPKIFCertificate object is used when the public key of a recipient is used to encrypt the content encryption key.

When using a certificate, a certification path can be constructed and validated (including enforcement of key encipherment key usage) when this function is called. The two-parameter version of this function can be used when the results of the path building and validation operation need not be inspected. The four-parameter version can be used to retrieve the path and validation results from the path building and validation operation. The minStatus parameter can be used to turn off path validation of the recipient (e.g., by passing PVS_NOT_VALIDATED) or to control the minimum acceptable level of validation, for example, to permit addition recipients for which revocation information is not available. If path processing is attempted but the minimum acceptable status is not met, this function will generate an exception indicating MSG_INVALID_RECIP.

If the cert parameter is NULL (or empty), an exception indicating COMMON_INVALID_INPUT will be thrown. Where path processing is performed, the IPKIFPathBuild and IPKIFPathValidate interfaces must be available. The mediator object providing access to these interfaces must be specified via a call to AddMediator prior to invoking this function. If the necessary interfaces are not available, an exception indicating COMMON_MEDIATOR_MISSING will be thrown. If the certificate in the cert parameter is not an encryption certificate, an exception indicating MSG_INVALID_RECIP will be thrown.

Returns:
None
Exceptions:
CPKIFMessageException(MSG_INVALID_RECIP) 
CPKIFMessageException(COMMON_INVALID_INPUT) 
CPKIFMessageException(COMMON_MEDIATOR_MISSING) 
Parameters:
cert  [in] Reference to a smart pointer to a CPKIFCertificate object containing the certificate of an intended recipient of the EnvelopedData message. If the object passed via this parameter is NULL or empty, a CPKIFMessageException is thrown indicating COMMON_INVALID_INPUT.
path  [out] Reference to a smart pointer to a CPKIFCertificatePath object to receive the certification path constructed and validated to the recipient certificate passed via the cert parameter. The object returned via this parameter is complete only if no exception is thrown and if minStatus is not PVS_NOT_VALIDATED. If an exception is thrown, the object may be useful for diagnostic purposes, e.g. to review path building statistics, but may be incomplete.
valResults  [out] Reference to a smart pointer to a CPKIFPathValidationResults object to receive the path validation results associated with the path returned via the path parameter. The object returned via this parameter is valid only path validation was attempted (i.e., minStatus is not PVS_NOT_VALIDATED and the m_nReturnedPaths member of the CPKIFBuilderStatistics object is not 0). If an exception is thrown, the object may be useful for diagnostic purposes, e.g. if one or more paths were found but failed validation. If no paths could be developed from the recipient’s certificate to a trust anchor and validation was not attempted, the object returned via valResult will simply contain default values.
minStatus  [in] CMSPathValidationStatus value representing the minimum acceptable path validation result that must be achieved to accept the recipient certificate passed via the cert parameter as a recipient. If PVS_NOT_VALIDATED is passed via this parameter, the certificate is simply added as a recipient without performing path processing. If the minimum status is not met, an exception indicating MSG_INVALID_RECIP is thrown and the recipient is not added to the list of recipients.

Definition at line 806 of file EnvelopedData.cpp.

References IPKIFPathBuild::BuildPath(), COMMON_INVALID_INPUT, COMMON_MEDIATOR_MISSING, keyUsageChecker_Encryption(), LOG_STRING_DEBUG, MSG_INVALID_RECIP, NOT_REVOKED, CPKIFException::push_info(), PVS_CERT_PATH_VERIFIED, PVS_NOT_VALIDATED, PVS_REV_STATUS_VERIFIED, TOOLKIT_CRYPTO_MISC, and IPKIFPathValidate::ValidatePath().

void CPKIFEnvelopedData::AddRecipient ( CPKIFKEKRecipInfoDetailsPtr &  kek  ) 

Interface: External

This function is used to add recipients (i.e. entities for which the message is to be encrypted) to a message. Recipient information can be specified via CPKIFKEKRecipInfoDetails object. A CPKIFKEKRecipInfoDetails object is used when the recipient possesses a symmetric key that can be used to encrypt the content encryption key.

Returns:
None
Exceptions:
CPKIFMessageException(COMMON_INVALID_INPUT) 
Parameters:
kek  A smart poiter to CPKIFKEKRecipInfoDetails object which contains a symmetric key that can be used to encrypt the content encryption key.

Definition at line 736 of file EnvelopedData.cpp.

References COMMON_INVALID_INPUT, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

void CPKIFEnvelopedData::SetDataToEncrypt ( CPKIFEncryptedContentInfoPtr &  buf  ) 

Interface: External

This function is used to specify the data to be encrypted and included in an EnvelopedData message. If the object passed via buf contains a NULL pointer, the internal member variable pointing to the data to encrypt, will be set to point to NULL. If buf is non-NULL, the object must contain a content type OID and content, otherwise an exception indicating COMMON_INVALID_INPUT will be thrown.

Returns:
None
Exceptions:
CPKIFMessageException(COMMON_INVALID_INPUT) 
Parameters:
buf  [in] Reference to a smart pointer to a CPKIFEncryptedContentInfo object containing the data to encrypt

Definition at line 320 of file EnvelopedData.cpp.

References COMMON_INVALID_INPUT, LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

CPKIFEncryptedContentInfoPtr CPKIFEnvelopedData::GetEncryptedData (  )  const

Interface: External

This function retrives encrypted content info from encrypted data object

Returns:
A smart pointer to CPKIFEncryptedContentInfo obejct.

Definition at line 2381 of file EnvelopedData.cpp.

References m_impl.

void CPKIFEnvelopedData::AddUnprotectedAttribute ( CPKIFAttributePtr &  attr  ) 

Interface: External

This function is used to add an attribute to the set of unprotected attributes included in an EnvelopedData message.

Returns:
None
Exceptions:
CPKIFMessageException(COMMON_INVALID_INPUT) 
Parameters:
attr  [in] Reference to a smart pointer to a CPKIFAttribute object to add to the set of unprotected attributes included in an EnvelopedData message

Definition at line 350 of file EnvelopedData.cpp.

References COMMON_INVALID_INPUT, GetUnprotectedAttributes(), LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

void CPKIFEnvelopedData::GetUnprotectedAttributes ( CPKIFAttributeList &  ual  ) 

Interface: External

This function adds the attributes from the unprotected attributes collection associated with an EnvelopedData object to the list passed via the ual parameter.

Returns:
None
Parameters:
ual  [out] Reference to a CPKIFAttributeList object to receive the set of unprotected attributes included in an EnvelopedData message

Definition at line 380 of file EnvelopedData.cpp.

References LOG_STRING_DEBUG, and TOOLKIT_CRYPTO_MISC.

Referenced by AddUnprotectedAttribute(), and Encode().

void CPKIFEnvelopedData::GetEncodedUnprotectedAttributes ( CPKIFBufferPtr &  buf  )  [virtual]

Interface: External

This function retrives a list of DER encoded unprotected CMS attributes

Returns:
None
Parameters:
buf  [out] A reference to a smart pointer to CPKIFBuffer containing the list of CMS attributes

Reimplemented from IPKIFHasAttributes.

Definition at line 2319 of file EnvelopedData.cpp.

References CACASNWRAPPER_CREATE, and data.

void CPKIFEnvelopedData::_GetUnprotectedAttributes ( std::vector< CPKIFAttributePtr >  attrVector  ) 

Interface: Subsystem

This function retrives a list unprotected CMS attributes

Returns:
None
Parameters:
attrVector  [out] Vector of CPKIFAttribute obejcts

Definition at line 2349 of file EnvelopedData.cpp.

References CPKIFCMSAttributeMediator2::GetInstance(), and IPKIFHasAttributes::GetUnprotectedAttributes().

template<class T>
boost::shared_ptr< T > CPKIFEnvelopedData::GetUnprotectedAttribute (  )  [inline]

Interface: External

This function is used to retrieve all attributes from the set of unprotected attributes included in an EnvelopedData.

Returns:
None

Definition at line 196 of file EnvelopedData.h.

void CPKIFEnvelopedData::ClearContent (  ) 

Interface: External

This function will clear all member variables and reset the state of the object such that a new message can be created for encryption or an existing message can be decoded for decryption.

Returns:
None

Definition at line 404 of file EnvelopedData.cpp.

References PKIFCRYPTO::CBC, CMSv0, LOG_STRING_DEBUG, PKIFCRYPTO::TDES, and TOOLKIT_CRYPTO_MISC.

void CPKIFEnvelopedData::SetAlgorithmAndMode ( PKIFCRYPTO::SYMKEY_ALG  alg,
PKIFCRYPTO::SYMKEY_MODE  mode 
)

Interface: External

This function is used to specify the content encryption algorithm and mode to use when encrypting a message.

Returns:
None
Parameters:
alg  [in] SYMKEY_ALG value identifying the algorithm to use when encrypting the data to encrypt of an EnvelopedData message
mode  [in] SYMKEY_MODE value identifying the mode of operation to use when encrypting the data to encrypt of an EnvelopedData message

Definition at line 249 of file EnvelopedData.cpp.

PKIFCRYPTO::SYMKEY_ALG CPKIFEnvelopedData::GetAlgorithm (  )  const

Interface: External

This function returns the symmetric content encryption algorithm

Returns:
The algorithm value represented by SYMKEY_ALG enum

Definition at line 267 of file EnvelopedData.cpp.

PKIFCRYPTO::SYMKEY_MODE CPKIFEnvelopedData::GetMode (  )  const

Interface: External

This function returns the mode used by the current symmetric content encryption algorithm

Returns:
The mode value represented by SYMKEY_MODE enum

Definition at line 278 of file EnvelopedData.cpp.

CPKIFBufferPtr CPKIFEnvelopedData::Encode (  )  [virtual]

Interface: External

This function is used to generate a message after all desired parts of the message have been assembled, i.e. recipients, originator information, data to encrypt, etc. This function will encrypt the specified data using Triple DES CBC and encrypt the symmetric key for each recipient. The resulting encoded blob should be wrapped in a content info layer to produce a CMS message (i.e., create a CPKIFContentInfo object, set the content type to g_envelopedData, set the content to the buffer returned by this function and call Encode to produce an encoded ContentInfo message).

A random symmetric key, and IV if necessary, are generated and used to encrypt the specified data. The symmetric key is then encrypted for each recipient and the message encoded and returned in a CPKIFBuffer object.

This function requires access to the following interfaces: IPKIFCryptoMisc and IPKIFCryptoRawOperations.

Returns:
If the function is successful, a smart pointer to a CPKIFBuffer object containing the encoded EnvelopedData message will be returned. If the function is not successful, an exception is throw.
Exceptions:
CPKIFCacheException(CACHE_CERT_STORE_OPEN_FAILED) 
CPKIFMessageException(COMMON_INVALID_INPUT) 
CPKIFMessageException(COMMON_MEDIATOR_MISSING) 
CPKIFMessageException(COMMON_UNSUPPORTED_ALG) 
CPKIFCryptoException(COMMON_INVALID_INPUT) 
CPKIFMessageException(COMMON_OPERATION_NOT_HANDLED) 
CPKIFException(COMMON_INVALID_INPUT) 

Implements CPKIFContentType.

Definition at line 1046 of file EnvelopedData.cpp.

References CACASNWRAPPER_CREATE, COMMON_INVALID_INPUT, CopyOID(), GetUnprotectedAttributes(), LOG_STRING_DEBUG, PKIFCMSMessageMemoryHelper::pEnvelopedData, SetupAttributesInObjectiveStructure(), and TOOLKIT_CRYPTO_MISC.

void CPKIFEnvelopedData::Decode ( CPKIFBufferPtr &  buf  )  [virtual]

Interface: External

This function is used to decode an encoded enveloped data message, i.e. the content from a Content Info message with an enveloped data payload. This function does not decrypt the contents of the message.

If buf is NULL an exception indicating COMMON_INVALID_INPUT will be thrown. If decode operation was unsuccessful an exception indicating MSG_DECODE_FAILED will be thrown. Following successful decoding of a message, the fields of the message can be reviewed by invoking various retrieval methods on the object, e.g., GetVersion or GetOriginatorCertificates. The encrypted data payload can be decrypted by calling the Decrypt function.

Returns:
None
Exceptions:
CPKIFMessageException (MSG_DECODE_FAILED)
CPKIFMessageException(COMMON_INVALID_INPUT) 
Parameters:
buf  [in] Reference to a smart pointer to a CPKIFBuffer object containing an encoded EnvelopedData message to decode

Implements CPKIFContentType.

Definition at line 1190 of file EnvelopedData.cpp.

References CMSv0, CMSv2, COMMON_INVALID_INPUT, LOG_STRING_DEBUG, MSG_DECODE_FAILED, PEMDecode(), CPKIFException::push_info(), and TOOLKIT_CRYPTO_MISC.

void CPKIFEnvelopedData::SetPathSettings ( CPKIFPathSettingsPtr &  settings  ) 

Interface: External

This function is used to specify the path settings to use when building and validating certificate paths for recipients. The object passed to this function will be used by subsequent path processing operations on the same CPKIFEnvelopedData object, e.g. adding multiple recipients. If the object passed via settings points to NULL, a default CPKIFPathSettings object will be created if path processing is performed. See CPKIFPathSettings for details regarding the specific settings that may be specified and default values on newly created.

Returns:
None
Parameters:
settings  [in] Reference to a smart pointer to a CPKIFPathSettings object containing the path processing settings to use when performing path building and validation operations prior to accepting a recipient certificate. May point to NULL if default path settings should be used.

Definition at line 1004 of file EnvelopedData.cpp.

CPKIFBufferPtr CPKIFEnvelopedData::Decrypt ( CPKIFCredentialPtr &  cred  ) 

Interface: External

This function will decrypt the contents of a decoded message using the credential information passed via the cred parameter.

For the version that takes a CPKIFCredentialPtr&, if the cred parameter is not set, an attempt will be made to discover a correct decryption key automatically. The following credential locations will be tried, in order: cred parameter, default decryption key available via the IPKIFDefaultKeyManagement interface, automatic discovery using the IPKIFCryptoKeyIDOperations interface. If no credential is specified and none can be found, a CPKIFMessageException indicating COMMON_INVALID_INPUT will be thrown. If the credential used for decryption fails to decrypt the symmetric key, a CPKIFMessageException indicating MSG_SYMKEY_DECRYPT_FAILED will be thrown. If content decryption fails, a CPKIFCryptoException indicating CRYPTO_DECRYPT_FAILED will be thrown.

Thisfunction require access to the IPKIFCryptoKeyIDOperations and IPKIFCryptoRawOperations interfaces. If default credentials are used, the IPKIFDefaultKeyManagement must also be available. The mediator object providing access to these interfaces must be specified via a call to AddMediator prior to invoking this function. If the necessary interfaces are not available, an exception indicating COMMON_MEDIATOR_MISSING will be thrown.

Returns:
None
Exceptions:
CPKIFMessageException (MSG_DECODE_FAILED)
CPKIFMessageException (MSG_MISSING_PARAMS)
CPKIFMessageException(COMMON_MEDIATOR_MISSING) 
CPKIFMessageException(COMMON_UNSUPPORTED_ALG) 
CPKIFMessageException(COMMON_INVALID_INPUT) 
CPKIFMessageException(ASN1_DECODE_ERROR) 
CPKIFMessageException(MSG_SYMKEY_DECRYPT_FAILED) 
CPKIFMessageException(PKIFCAPI_DECRYPT_FAILED) 
CPKIFCryptoException(COMMON_OPERATION_NOT_HANDLED) 
CPKIFCryptoException(COMMON_INVALID_INPUT) 
Parameters:
cred  [in] Reference to a smart pointer to a CPKIFCredential object to use when decrypting the encrypted data associated with an EnvelopedData message.

Definition at line 1452 of file EnvelopedData.cpp.

References ASN1_DECODE_ERROR, AutoDiscoverDecryptionKey(), COMMON_INVALID_INPUT, COMMON_MEDIATOR_MISSING, COMMON_UNSUPPORTED_ALG, IPKIFCryptoRawOperations::Decrypt(), PKIFCRYPTO::DECRYPTION, GetCACSymAlg(), IPKIFDefaultKeyManagement::GetDefaultKey(), GetMediator(), GetSymmetricKey(), LOG_STRING_DEBUG, MSG_MISSING_PARAMS, MSG_SYMKEY_DECRYPT_FAILED, CPKIFAlgorithm::NeedsIV(), CPKIFException::push_info(), CPKIFAlgorithm::SymkeyAlg(), CPKIFAlgorithm::SymkeyMode(), TOOLKIT_CRYPTO_MISC, and TOOLKIT_MESSAGE_ASN.

CPKIFBufferPtr CPKIFEnvelopedData::Decrypt ( CPKIFKEKRecipInfoDetailsPtr &  kek  ) 

Interface: External

This function will decrypt the contents of a decoded message using the recipient information passed via the kek parameter.

This function require access to the IPKIFCryptoKeyIDOperations and IPKIFCryptoRawOperations interfaces. The mediator object providing access to these interfaces must be specified via a call to AddMediator prior to invoking this function. If the necessary interfaces are not available, an exception indicating COMMON_MEDIATOR_MISSING will be thrown.

Returns:
None
Exceptions:
CPKIFMessageException(ASN1_DECODE_ERROR) 
CPKIFMessageException(COMMON_MEDIATOR_MISSING) 
CPKIFMessageException(COMMON_INVALID_INPUT) 
CPKIFMessageException(MSG_SYMKEY_DECRYPT_FAILED) 
CPKIFMessageException(COMMON_UNSUPPORTED_ALG) 
CPKIFMessageException(MSG_MISSING_PARAMS) 
Parameters:
kek  [in] Reference to a smart pointer to a CPKIFKEKRecipInfoDetails object to use when decrypting the encrypted data associated with an EnvelopedData message

Definition at line 1279 of file EnvelopedData.cpp.

References ASN1_DECODE_ERROR, COMMON_INVALID_INPUT, COMMON_MEDIATOR_MISSING, COMMON_UNSUPPORTED_ALG, IPKIFCryptoRawOperations::Decrypt(), GetCACSymAlg(), GetMediator(), GetSymmetricKey(), LOG_STRING_DEBUG, MSG_MISSING_PARAMS, MSG_SYMKEY_DECRYPT_FAILED, CPKIFAlgorithm::NeedsIV(), CPKIFAlgorithm::SymkeyAlg(), CPKIFAlgorithm::SymkeyMode(), TOOLKIT_CRYPTO_MISC, and TOOLKIT_MESSAGE_ASN.

void CPKIFEnvelopedData::GetAddedUnprotectedAttributes ( std::vector< CPKIFAttributePtr > &  attr  )  [virtual]

Interface: External

This function retrives a list of added unprotected CMS attributes

Returns:
None
Parameters:
attr  [out] Vector of CPKIFAttribute obejcts

Reimplemented from IPKIFHasAttributes.

Definition at line 2363 of file EnvelopedData.cpp.

void CPKIFEnvelopedData::SetMediator ( IPKIFMediatorPtr &  m  ) 

Interface: External

Establishes the mediator set that will be used by this instance.

Returns:
None
Parameters:
m  [in] Smart Pointer to a mediator obejct

Definition at line 185 of file EnvelopedData.cpp.

IPKIFMediatorPtr CPKIFEnvelopedData::GetMediator (  ) 

Interface: External

This function returns the Mediator object stored in CPKIFEnvelopedData

Returns:
None

Definition at line 198 of file EnvelopedData.cpp.

Referenced by Decrypt().

Friends And Related Function Documentation

friend struct CPKIFEnvelopedDataImpl [friend]

Definition at line 58 of file EnvelopedData.h.

The documentation for this class was generated from the following files:
Generated on Mon Nov 15 11:20:15 2010 for PublicKeyInfrastructureFramework(PKIF) by  doxygen 1.5.6