Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

MQe_MTrustAttribute.h File Reference

MQeMTrustAttribute object. More...


Functions

MQERETURN mqeMTrustAttribute_new (MQeExceptBlock *pErrStruct, MQeMTrustAttributeHndl *phAttribute, MQeAuthenticatorHndl hAuthenticator, MQeCryptorHndl hCryptor, MQeCompressorHndl hCompressor)
 This function constructs an MQeMTrustAttribute object.

MQERETURN mqeMTrustAttribute_free (MQeMTrustAttributeHndl hMTrustAttribute, MQeExceptBlock *pErrStruct)
 frees the MQeMTrustAttribute handle hMTrustAttribute

MQERETURN mqeMTrustAttribute_decodeData (MQeMTrustAttributeHndl hMTrustAttribute, MQeExceptBlock *pErrStruct, MQEBYTE *pBuffer, MQEINT32 *pBufLength, MQEBYTE *pData, MQEINT32 offset, MQEINT32 length)
 decrypts and/or decompresses the bytes referenced by pData, offset and for length length.

MQERETURN mqeMTrustAttribute_encodeData (MQeMTrustAttributeHndl hMTrustAttribute, MQeExceptBlock *pErrStruct, MQEBYTE *pBuffer, MQEINT32 *pBufLength, MQEBYTE *pData, MQEINT32 offset, MQEINT32 length)
 This function encrypts and/or compresses the bytes referenced by pData, offset and for length length.

MQERETURN mqeMTrustAttribute_setHomeServer (MQeMTrustAttributeHndl hMTrustAttribute, MQeExceptBlock *pErrStruct, MQECONST MQeStringHndl hHomeServer)
 This function sets the Home Server address and port for this attribute.

MQERETURN mqeMTrustAttribute_setPublicRegistry (MQeMTrustAttributeHndl hMTrustAttribute, MQeExceptBlock *pErrStruct, MQePublicRegistryHndl hPublicRegistry)
 This function sets the public registry for this attribute.

MQERETURN mqeMTrustAttribute_setPrivateRegistry (MQeMTrustAttributeHndl hMTrustAttribute, MQeExceptBlock *pErrStruct, MQePrivateRegistryHndl hPrivateRegistry)
 Sets the private registry for this attribute.

MQERETURN mqeMTrustAttribute_setTarget (MQeMTrustAttributeHndl hMTrustAttribute, MQeExceptBlock *pErrStruct, MQECONST MQeStringHndl hTarget)
 Adds the name of the intended recipient to the attribute. This is used to retrieve the recipient's public key, in order to encrypt the message.


Detailed Description

This object is used to create an attribute object enabling message-level protection of message objects in such a way that :


Function Documentation

MQERETURN mqeMTrustAttribute_new MQeExceptBlock   pErrStruct,
MQeMTrustAttributeHndl *    phAttribute,
MQeAuthenticatorHndl    hAuthenticator,
MQeCryptorHndl    hCryptor,
MQeCompressorHndl    hCompressor
 

Parameters:
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
phMTrustAttribute  [out] Pointer to handle for output
hAuthenticator  [in] Handle for an MQeAuthenticator object (or null) used to authenticate data access.
hCryptor  [in] Handle for an MQeCryptor object (or null) used to encrypt and decrypt data.
hCompressor  [in] Handle for an MQeCompressor object used to compress the data prior to encryption, or decompress after decryption.
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
phMTrustAttribute must not be NULL.
Returns :
output in (*phMTrustAttribute).
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_NOT_SUPPORTED  Invalid Cryptor
Warning:
Users are expected to use mqeMTrustAttribute_free() to free the object returned by this call when it is no longer needed. This enables reuse of system resources and can help to avoid system problems caused by shortage of resources.

MQERETURN mqeMTrustAttribute_free MQeMTrustAttributeHndl    hMTrustAttribute,
MQeExceptBlock   pErrStruct
 

Parameters:
hMTrustAttribute  [in] Handle for the MQeMTrustAttribute to be freed.
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
Precondition:
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully

MQERETURN mqeMTrustAttribute_decodeData MQeMTrustAttributeHndl    hMTrustAttribute,
MQeExceptBlock   pErrStruct,
MQEBYTE *    pBuffer,
MQEINT32 *    pBufLength,
MQEBYTE *    pData,
MQEINT32    offset,
MQEINT32    length
 

Parameters:
hMTrustAttribute  [in] Handle for the MQeMTrustAttribute to be operated on.
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
pBuffer  [out] Pointer to output buffer.
pBufLength  [out] Pointer to buffer ((*pBuffer) ) length variable.
pData  [in] Pointer to a byte array to be decypted and/or decompressed.
offset  [in] offset into the data array to start.
length  [in] number of bytes in the data array to be decoded.
Precondition:
hMTrustAttribute must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Returns :
pBuffer and pBufLength:
 * ---------------------- ---------------- -------------------------------- -------------------------
 * initial (*pBufLength)  initial pBuffer  returned (*pBufLength)           returned pBuffer
 * ---------------------- ---------------- -------------------------------- -------------------------
 * 0                      any              buffer size (in bytes) required  not defined
 * any                    NULL             ditto                            ditto
 * != 0                   != NULL          buffer space used (in bytes)     points to the result
 * 
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_S_REGISTRY_NOT_AVAILABLE  Security registry not available
MQERETURN_J_S_MINICERT_NOT_AVAILABLE  Mini security certificate server not available
MQERETURN_J_S_REGISTRY_NOT_AVAILABLE  Security registry not available
MQERETURN_J_S_BAD_INTEGRITY  Security integrity check failed
MQERETURN_J_S_INVALID_SIGNATURE  Invalid security signature

MQERETURN mqeMTrustAttribute_encodeData MQeMTrustAttributeHndl    hMTrustAttribute,
MQeExceptBlock   pErrStruct,
MQEBYTE *    pBuffer,
MQEINT32 *    pBufLength,
MQEBYTE *    pData,
MQEINT32    offset,
MQEINT32    length
 

Parameters:
hMTrustAttribute  [in] Handle for the MQeMTrustAttribute to be operated on.
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
pBuffer  [out] Pointer to output buffer.
pBufLength  [out] Pointer to buffer ((*pBuffer) ) length variable.
pData  [in] Pointer to a byte array to be encrypted and/or compressed.
offset  [in] offset into the data array to start.
length  [in] number of bytes in the data array to be encoded.
Precondition:
hMTrustAttribute must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Returns :
pBuffer and pBufLength:
 * ---------------------- ---------------- -------------------------------- -------------------------
 * initial (*pBufLength)  initial pBuffer  returned (*pBufLength)           returned pBuffer
 * ---------------------- ---------------- -------------------------------- -------------------------
 * 0                      any              buffer size (in bytes) required  not defined
 * any                    NULL             ditto                            ditto
 * != 0                   != NULL          buffer space used (in bytes)     points to the result
 * 
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_S_MINICERT_NOT_AVAILABLE  Mini security certificate server not available

MQERETURN mqeMTrustAttribute_setHomeServer MQeMTrustAttributeHndl    hMTrustAttribute,
MQeExceptBlock   pErrStruct,
MQECONST MQeStringHndl    hHomeServer
 

Called to set an MQeMTrustAttributes home-server address. When used to protect a message, encodeData attempts to get the intended recipient’s mini-certificate from its active public registry. If not found but the home-server address is set, it requests the mini-certificate from the home-server, and saves it for subsequent use in the active public registry. When used to recover a message, decodeData attempts to gets the initiator’s mini-certificate from its active public registry. If not found but the home-server address is set, it requests the mini-certificate from the home-server and saves it for subsequent use in its active public registry.

Parameters:
hMTrustAttribute  [in] Handle for the MQeMTrustAttribute to be operated on.
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
pHomeServer  [in] Pointer to the home server address and port.
Precondition:
hMTrustAttribute must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_NOT_ALLOWED  Illegal set public registry

MQERETURN mqeMTrustAttribute_setPublicRegistry MQeMTrustAttributeHndl    hMTrustAttribute,
MQeExceptBlock   pErrStruct,
MQePublicRegistryHndl    hPublicRegistry
 

Called to set an MQeMTrustAttribute’s active public registry. When used to protect a message this is a public registry that has (or gets) the mini-certificate of the intended recipient, and when recovering a message this is a public registry that has (or gets) the mini-certificate of the sender.

Parameters:
hMTrustAttribute  [Handle for the MQeMTrustAttribute to be operated on.
pErrStruct  Pointer to a pre-allocated MQeExceptBlock structure.
hPublicRegistry  Handle for the public registry.
Precondition:
hMTrustAttribute must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_NOT_ALLOWED  Illegal set public registry

MQERETURN mqeMTrustAttribute_setPrivateRegistry MQeMTrustAttributeHndl    hMTrustAttribute,
MQeExceptBlock   pErrStruct,
MQePrivateRegistryHndl    hPrivateRegistry
 

Called to set an MQeMTrustAttribute’s active private registry. When used to protect a message this is the private registry of the sender and when recovering a message this is the private registry of the recipient.

Parameters:
hMTrustAttribute  [in] Handle for the MQeMTrustAttribute to be operated on.
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
hPrivateRegistry  [in] Handle for the private registry.
Precondition:
hMTrustAttribute must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_NOT_ALLOWED  Illegal set public registry

MQERETURN mqeMTrustAttribute_setTarget MQeMTrustAttributeHndl    hMTrustAttribute,
MQeExceptBlock   pErrStruct,
MQECONST MQeStringHndl    hTarget
 

This method adds the name of the intended recipient to the attribute. This is used to retrieve the recipient’s public key, in order to encrypt the message. It is also added to the message and used at the destination to retrieve the recipient’s private registry, to enable decryption of the message.

This should be used in preference to the method setTargetRegistryName() in the class MQePrivateRegistry. If both setTarget() and setTargetRegistryName() are called, the name specified in setTarget() is used.

Parameters:
hMTrustAttribute  [in] Handle for the MQeMTrustAttribute to be operated on.
pErrStruct  [in/out] Pointer to a pre-allocated MQeExceptBlock structure.
pTarget  [in] points to the target's name.
Precondition:
hMTrustAttribute must not be NULL.
pErrStruct points to a pre-allocated MQeExceptBlock structure (no error information is returned if pErrStruct is null).
Return values:
MQERETURN_OK  Completed Successfully
MQERETURN_J_NOT_ALLOWED  Illegal set public registry


Generated Thu Aug 11 23:41:21 2005 for Websphere MQ Everyplace for Multiplatforms C Bindings Reference