Clear Master Key (CLRMSTKEY)
| Where allowed to run: All environments (*ALL) Threadsafe: Yes |
Parameters Examples Error messages |
The Clear Master Key (CLRMSTKEY) command clears the specified master key version. For all master keys except the Save/Restore Master Key, the key value and key verification value (KVV) are set to null (binary zeroes). Clearing the Save/Restore Master Key sets the key value for the specified version to the default value with a KVV of hexadecimal '16C1D3E3C073E77DB28F33E81EC165313318CE54'.
For more information on master keys, refer to the Cryptographic services key management section of the Security category in the IBM Systems Information Center at http://www.ibm.com/systems/infocenter/.
Restrictions:
- You must have all object (*ALLOBJ) and security administrator (*SECADM) special authorities to run this command.
| Top |
Parameters
| Keyword | Description | Choices | Notes |
|---|---|---|---|
| MSTKEY | Master key | 1-8, *ASP, *SAVRST | Required, Positional 1 |
| VERSION | Master key version | *NEW, *CURRENT, *OLD, *PENDING | Required, Positional 2 |
| Top |
Master key (MSTKEY)
Specifies the master key on which to perform the action.
This is a required parameter.
The action will be performed on:
- *ASP
- The master key used for encrypting data stored on auxiliary storage pool (ASP) disk storage.
- *SAVRST
- The master key used for encrypting all the other master keys on a SAVSYS operation.
- 1-8
- One of the eight general purpose master keys.
| Top |
Master key version (VERSION)
Specifies the version of the master key to clear.
This is a required parameter.
- *NEW
- Clear the new version.
- *CURRENT
- Clear the current version.
- *OLD
- Clear the old version.
Note: Before clearing an old master key version, ensure no keys or data are still encrypted under it.
- *PENDING
- Clear the pending version. This value is not valid if *SAVRST is specified for the Master key (MSTKEY) parameter.
| Top |
Examples
Example 1: Clear the New Version of a Master Key
CLRMSTKEY MSTKEY(1) VERSION(*NEW)
This command clears the new version of Master Key 1. The new version consists of all key parts that were loaded since the last time the master key was set. The master key could have been set by running the Set Master Key (SETMSTKEY) command.
Example 2: Clear the Pending Version of a Master Key
CLRMSTKEY MSTKEY(4) VERSION(*PENDING)
This command clears the pending version of Master Key 4. The existence of a pending version indicates that the master key had been restored to the system, but the system was unable to decrypt it.
| Top |
Error messages
*ESCAPE Messages
- CPF222E
- &1 special authority is required.
- CPF3CF2
- Error(s) occurred during running of &1 API.
- CPF9872
- Program or service program &1 in library &2 ended. Reason code &3.
- CPF9D88
- An error occurred during exit program post-processing.
- CPF9D89
- An error occurred during exit program pre-processing.
- CPF9D91
- Master Key &1 was not cleared due to an exit program cancel.
- CPF9DDA
- Unexpected return code &1 from cryptographic service provider &2.
| Top |