Add Master Key Part (ADDMSTPART)

Where allowed to run: All environments (*ALL)
Threadsafe: Yes
Parameters
Examples
Error messages

The Add Master Key Part (ADDMSTPART) command loads a key part for the specified master key by hashing the specified passphrase and adding it into the new master key version.

You should securely store your passphrase outside the system so you can recover the master key should it become damaged.

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:

Top

Parameters

Keyword Description Choices Notes
MSTKEY Master key 1-8, *ASP, *SAVRST Required, Positional 1
PASSPHRASE Passphrase Character value Required, Positional 2
PASSLEN Length of passphrase 1-256, *CALC Optional
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

Passphrase (PASSPHRASE)

Specifies a text string. The text string will be hashed and then added into the new version of the master key using an exclusive-OR operation.

Note: If a specific passphrase is added twice, the value is actually removed from the new version because a value exlusive-OR'ed with itself results in a value of 0.

This is a required parameter.

character-value
Specify the passphrase. Each character may contain any valid binary value.
Top

Length of passphrase (PASSLEN)

Specifies the number of bytes of the value specified for Passphrase (PASSPHRASE) that are to be used to create the key part which will be added to the master key.

*CALC
Allow the system to calculate the passphrase length by removing all trailing blanks.
1-256
Specify the length of passphrase typed above. If the length specified is greater than the length of the passphrase, the passphrase will be padded with binary zeros to the length specified. If the length specified is less than the length of the passphrase, the passphrase will be truncated.
Top

Examples

Example 1: Add a Key Part for a Master Key Specifying Length of Passphrase

ADDMSTPART   MSTKEY(3)
             PASSPHRASE('Twas brillig, and the slithy toves')
             PASSLEN(30)

This command takes the first 30 bytes from the PASSPHRASE parameter, hashes it down to 20 bytes, and adds it into the new version of Master Key 3.

Example 2: Add a Key Part for a Master Key Allowing the System to Calculate the Passphrase Length

ADDMSTPART   MSTKEY(*SAVRST)
             PASSPHRASE('Twas brillig, and the slithy toves')
             PASSLEN(*CALC)

This command removes all trailing blanks from the PASSPHRASE parameter value, takes the resulting text string, hashes it down to 20 bytes, and adds it into the new version of the Save/Restore Master Key.

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.
CPF9DDA
Unexpected return code &1 from cryptographic service provider &2.
Top