Playing with KAES256.ser file

Body

ITM uses GSKit for Secure Socket layer and low level cryptographic functions.
Most of you for sure already dealt with certificates and encryption keys, so you know that into folder <itmhome>/keyfiles you will find some files like keyfile.kdb, keyfile.rdb
and KAES256.ser.
Unless the other files, KAES256.ser is used only for locally encrypted configuration data or to decrypt credentials passed through remote deploy functions, but it is not used for communication encryption.

KAES256.ser contains the encryption key that is provided when you first install the ITMHOME on the system.
The installer suggests a default key, but of course you are free to provide your own.

It is important to consider that this encryption key must be the same within the whole ITM environment in case you are expected to run remote commands that requires
to pass encrypted credentials.
If the encryption key stored into KAES256.ser on HTEMS is different than the key contained into the same file on a target agent node, running a tacmd executecommand will result in an error message "KUIEXC509E: Security token expired", as described in this technote:

/support/pages/node/509647

So it is always better you follow the suggestion provided in this technote when deploying new system nodes in case you are not using the default encryption key on TEMS.

But it can happen you forget to do it when manually installing a new ITM agent node and just accept the proposed encryption key during the installation process.
Nothing too bad, you can still copy the KAES256.ser from HTEMS and replace the one in the target agent node.

This will fix issue with remote commands like the one highlighted in the above technote.

What happen if you have installed and configured on the target node an agent that saves encrypted passwords in its config file, like the Oracle Extended agent, and the configuration has been done BEFORE replacing the original KAES256.ser with the one copied from HTEMS ?

Well, it will simply stop working.
When the agent starts, it tries to decrypt the password string found into the config file using the current KAES256.ser, that is different than the one used to encrypt the password, and of course it will fail.
The error message will be something like:

(5894878D.8CED-1:kglcry.c,2225,"readKeyFile") Cannot read keyfile /opt/IBM/ITM/keyfiles/KAES256.ser
(5894878D.8CEE-1:kglcry.c,3501,"CRY_Decrypt") Function failed with error code 24
(5894878D.8CEF-1:krzconfig.cpp,69,"KrzConfigFile::KrzConfigFileGetEntry" ) Error at decrypt, encrypted string
is:{AES256:keyfile:***********************, returned pointer is:0,return code is:24

Then, for Oracle Extended agent you will also see:

Error code iis:1005, error message is:ORA-01005: null password given;logon denied

because the password it used to try connecting Oracle server is actually null (it failed to decrypt and passed a null string).

All depends on the mismatching KAES256.ser, but you cannot copy back the original ser file because otherwise you will fall again in the issue with remote commands.
What to do ?

Can this be fixed by reconfiguring the agent, so that it will encrypt the password using the new KAES256.ser file ?
It is a good idea, but it does not work.
If you try to reconfigure the agent with the current KAES256.ser, you will get an error like this during configuration:

candle.kjr.util.CryptoFailedException: KJRITM035E The cipher-text byte
array cannot be decrypted.
        at candle.kjr.util.CRYPTO.decrypt(CRYPTO.java:427)
        at
com.ibm.tivoli.monitoring.install.cmdline.PropertyNode.<init>(PropertyNo
de.java:69).......

So, what to do, do we need to remove the agent and reinstall ?
This can be an option if you have a single node to be fixed, but if you have lot of nodes with the wrong KAES256.ser, I suggest you to consider instead the following two options:

1) Try removing the instances instead of uninstalling the whole agent (use tacmd removeSystem) and then just recreate the instance.
This way, it will use the current KAES256.ser (that is the same as HTEMS) to encrypt credentials and so the agent will be able to decrypt it as well, and you will also able to run tacmd executecommand successfully.

2) If you must correct the credentials for the same agent type (es:RZ) on different nodes, and the credentials are the same for all of them, you can do as follow:

a) Choose a clean system or use a separate ITMHOME to do a fresh install of the agent (es:RZ)
b) Replace the KAES256.ser file with the HTEMS one.
c) Create a new agent instance and configure it with the needed credentials.
d) Copy the password from the config file (for RZ agent it is KRZ_CONN_PASSWORD into the .cfg file) and replace the same keyword on the failing servers with this one.

Since the credentials are the same for all nodes, this will allow the agent to decrypt successfully the password string using the KAES256.ser copied from HTEMS and to start data collection.

Thanks for reading

Subscribe and follow us for all the latest information directly on your social feeds: