# Password re-stashing

## About

SSL key stores used by IBM HTTP Server and the WebSphere WebServer Plug-in
can be accompanied by a `stash file` that allows the key store to be used
without interactively supplying a password. This stash file is an obfuscated
password. Over time, the strength of the obfuscated password has changed, but
to get the benefits, the key store password must be "re-stashed".

## How to re-stash an IHS keystore password

### Identify all key stores in use
- The key store used by IHS is identified by the `KeyFile` directive in the IHS configuration
(usually `httpd.conf`, but additional files can be included).  

The key store will normally have the extension ".kdb" but may (rarely) be a PKCS12 file with ".p12" or ".pfx".  If you do not interactively enter a password to start IHS, then you will likely find that the key store is accompanied by a "\*.sth". This is the stash file.

- The key stores used by the WAS WebServer Plug-in are identified by plugin-cfg.xml. In common configurations, key stores are maintained
by the deployment manager and periodically propagated to the webserver.

### Confirm software levels
Before re-stashing your password, you must confirm that all users of a given key store support the same stash file format
and revision.
 
 - IBM Global Security Kit (GSKit) 8.0.50.69, provided by PI66931 in 8.0.0.13, 8.5.5.11, and 9.0.0.2, supports version 2 stash files.
    - IBM Global Security Kit (GSKit) 8.0.50.88 and later, provided by PI94222, provide stronger obfuscation of version 2 stash files.
 - Any IBM Java maintenance level from 2016 or later supports version 2 stash files.
    - The following java minimums provide stronger obfuscation of version 2 stash files: 8.0.5.10, 7.1.4.20, 7.0.10.20, 6.1.8.60, 6.0.16.60 
       - These were first provided in the following WASSDK fixes for embedded java: PI93094, PI93096, PI93098, PI93099, PI93102

### Re-stash IHS keystores

1. Make a temporary backup of your key store and stash file. This backup should be treated as highly confidential.
1. Confirm that you know the current password by opening the keystore with Ikeyman, gskcapicmd, or gskcmd
1. Delete the stash file 
1. Re-stash the password
  - Using Ikeyman
    1. Launch Ikeyman (from the bin/ directory of the IHS installation root)
    1. Open the key store
    1. From the `Key Database File` menu, select `Stash Password` or `Change Password`.
  - Using native command-line certificate management (gskcapicmd)
    1. Example: `/opt/IBM/IHS/bin/gskcapicmd -keydb -stashpw -db /path/to/key.kdb -stashed`
       - Note: In version 7, the utility is named `gsk7capicmd`
  - Using java command-line certificate management (gskcmd/ikeycmd)
    1. Example: `/opt/IBM/IHS/bin/gskcmd -keydb -stashpw -db /path/to/key.kdb -stashed`
       - Note: In version 7, the utility is named `gsk7cmd`
    1. Enter the password interactively


If you are re-stashing your password to _downgrade_ the stash file format because IHS is out of date,
you will not be able to sue the `-stashed` flag. You'll have to omit it and type your password interactively,
or pass "-pw <newpass>" to specify it on the command-line.

After re-stashing the password as described above:
1. Confirm each key store can still be used by the IHS runtime by restarting IHS.
1. Discard or securely archive the backups created.

### Re-stash WebSphere WebServer Plug-in keystores

1. Make a temporary backup of your key store and stash file on the webserver system. This backup should be treated as highly confidential.
1. For WebSphere Application Server traditional, find each CMS key store in
   'Security > SSL certificate and key management > Key stores and certificates' and change
   the password via the UI.
1. Find the WebServer definition in the WAS admin console, select `Plugin Properties`. Click the `Copy to webserver key store directory`.
1. Confirm the plugin-key.kdb and plugin-key.sth have changed on-disk on the webserver system. If not, follow the instructions
   for IHS keystores in the preceding section.

After re-stashing the password as described above:
1. Restart the webserver and confirm things are still operational
1. Discard or securely archive the backups created.