Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 11 Password Encryption API : Encryption API for Open Systems

Encryption API for Open Systems
Location of the API
The external security API is defined in hrncrypt.h, located in the install_path/src/encrypt directory. Default and sample versions of the encryption loadable modules are shipped with TIBCO Object Service Broker. The default version performs no encryption and the sample version performs a simple encryption algorithm.
Location of the Loadable Modules
The following table lists the location required for the loadable modules after they are modified and re-compiled:
Required Compilers
The following table lists the compilers you must use to re-compile the hrncrypt module after you make changes to it:
Sample
The install_path/src/encrypt directory contains a sample implementation of the encryption exit, in the file called sample.c.
Supported Functions
The encryption API supports the following functions:
For the syntax of these functions, see the sections below or refer to install_path/src/encrypt/hrncrypt.h file.
hrnEncryptInitialize
Performs any necessary initialization when the TIBCO Object Service Broker session is initialized. Returns an address to a working storage memory block for use by subsequent encryption functions.

 
int hrnEncryptInitialize(
void** pStorage /* OUT: Password encryption work area */
);

 
Parameters:
 
Address of a pointer. This function uses this pointer to return the address of a work area to be passed in subsequent calls to hrnEncrypt, hrnDecrypt, hrnVersionMismatch, and hrnEncryptTerminate.
Return Values:
hrnEncryptTerminate
Cleans up, as necessary, any resources associated with the password encryption work area set up as a result of initialization. Also releases the storage for the area, if required, when the TIBCO Object Service Broker session terminates.

 
void hrnEncryptTerminate(
void* pStorage /* IN: Password encryption work area */
);

 
Parameters:
 
hrnEncrypt
Encrypts a clear text password that is supplied when a user logs in to the system. This encrypted password is compared to the value stored in the MetaStor. If the value is the same, the user can log in. If the value is different, the hrnVersionMismatch function is invoked.
The encryption algorithm is at your discretionary control and can be one-way or two-way. The encrypted output must have a minimum length equal to the clear text input. The maximum encrypted length is specified by an input parameter.

 
int hrnEncrypt(
void* pStorage                 /* IN: Password encryption work area */
encrypt_byte_t* pClearText,       /* IN: Clear text password */
encrypt_size_t wClearTextLen,     /* IN: Actual clear text password length */
encrypt_byte_t* pEncrypted,       /* OUT: Encrypted text */
encrypt_size_t* pwEncryptedLen,   /* IN/OUT: Length of encrypted text*/
encrypt_size_t* pwDummy            /* N/A */
);

 
Parameters:
 
In: The length of the area for the encrypted password.
Out: The length of the resulting encrypted password.
Return Values:
hrnDecrypt
Decrypts a given encrypted password. You must use this function for @SCHEDULEMODEL access.
If you chose to implement a one-way encryption algorithm, hrnDecrypt always fails with a 0x04 return code.

 
int hrnDecrypt(
void* pStorage                 /* IN: Password encryption work area */
encrypt_byte_t* pEncrypted,       /* IN: Encrypted password text */
encrypt_size_t wEncryptedLen,     /* IN: Esncrypted password text length */
encrypt_byte_t* pClearText,       /* OUT: Clear text password */
encrypt_size_t* pwClearTextLen    /* IN/OUT: Length of clear text password*/
);

 
Parameters:
 
In: The length of the area for the clear text password.
Out: The length of the resulting clear text password.
Return Values:
hrnVersionMismatch
Encrypts a clear text password using the previously supported algorithm. Compares this encrypted value to the previous value stored in the MetaStor for this user. If the two values are the same, the password in the MetaStor is updated with the value returned from the hrnEncrypt function.
If the default encryption loadable module supplied with TIBCO Object Service Broker is replaced by a customer encryption loadable module, in the hrnVersionMismatch function you must support clear text as the back-level encryption algorithm.

 
int hrnVersionMismatch(
void* pStorage                 /* IN: Password encryption work area */
encrypt_byte_t* pClearText,       /* IN: Clear text password */
encrypt_size_t wClearTextLen,     /* IN: Actual clear text password length */
encrypt_byte_t* pEncrypted,       /* OUT: Encrypted text */
encrypt_size_t* pwEncryptedLen,   /* IN/OUT: Length of encrypted text*/
encrypt_size_t* pwDummy           /* N/A */
);

 
Parameters:
 
In: The length of the area for the encrypted password.
Out: The length of the resulting encrypted password.
Return Values:

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved