runmqakm -keydb (manage key repositories)

Purpose

Use the runmqakm command to manage the key repositories, certificates, certificate requests, and secret keys that IBM® MQ uses.

The runmqakm command is certified as FIPS compliant, and can be configured to operate in a FIPS compliant manner by specifying the -fips parameter.

The runmqakm command supports the following file formats for key repositories:

• CMS
• PKCS #12

The runmqktool command supports other key repository formats. For more information, see runmqktool (manage keys, certificates, and certificate requests).

Actions

-changepw

Changes the password for a specified key repository.

–convert

Converts the key repository to a different format.

-create

Creates a CMS or PKCS#12 key repository.

-delete

Deletes a specified key repository.

-list

Lists information about key repositories.

-stashpw

Stashes the password for a specified key repository to a specified file.

Parameters

-crypto moduleName

Specifies a PKCS#11 cryptographic device, where moduleName is the path to the module to manage the cryptographic device.

If you specify the module name in the properties file, you do not need to specify a value after -crypto.

-db keyRepositoryName

Specifies the fully qualified path name of a key repository.

-expire passwordExpiry

The number of days until the password for the key repository expires. The value specified must be between 1 and 7300 days (20 years). If this parameter is not specified, the key repository password does not expire.

This parameter is ignored for a PKCS#12 key repository.

-fips

Specifies whether to force Federal Information Processing Standards (FIPS) mode. In FIPS mode, the underlying cryptographic provider is initialized in FIPS mode so that it uses only algorithms that are FIPS validated.

If -fips is set to true and the provider cannot be initialized in FIPS mode, the command fails. If -fips is set to false and the provider cannot be initialized in FIPS mode, then the utility uses a non-FIPS mode of operation.

-genpw

Specifies that a password is generated for the new key repository.

If you use the -genpw parameter, you must also use the -stash parameter.

-new_db keyRepositoryName

Specifies the fully qualified path name of the new key repository that is created.

-new_format

Specifies the type of the key repository that is created.

The value is either cms or pkcs12.

-new_pw newKeyRepositoryPassword

Specifies a new password for the key repository.

-pqc true(default) | false

When enabled, instructs runmqakm to use a stronger keystore protection algorithm. This algorithm might not be available on earlier versions of IBM MQ or Java.

-pw keyRepositoryPassword

Specifies the password for the key repository.

-stash

Specifies that the password for the key repository is stashed to a file.

-stashed

Specifies that the password for the key repository is stored in a stash file.

-strong

Specifies that the password meets the following minimum requirements:

• The minimum password length is 14 characters.
• A password must have at least one lowercase character, one uppercase character, and one digit or special character. A space is classified as a special character.
• Each character must not occur more than three times in a password.
• No more than two consecutive characters of the password can be identical.
• All characters are in the standard ASCII printable character set within the range from 0x20 to 0x7E inclusive.

-tokenlabel tokenLabel

Specifies the token label that is associated with the PKCS#11 device.

-type

Specifies the type of key repository.

The value is either cms or pkcs12.

Error codes

Error code	Error message
0	Success
1	Unknown error occurred
2	An ASN.1 encoding/decoding error occurred.
3	An error occurred while initializing the ASN.1 encoder/decoder.
4	An ASN.1 encoding/decoding error occurred because of an out-of-range index or nonexistent optional field.
5	A database error occurred.
6	An error occurred opening the database file, check for file existence and permission.
7	An error occurred re-opening the database file.
8	Database creation failed.
9	The database exists.
10	An error occurred deleting the database file.
11	The database cannot be opened.
12	An error occurred reading the database file.
13	An error occurred writing data to the database file.
14	A database validation error occurred.
15	An invalid database version was encountered.
16	An invalid database password was encountered.
17	An invalid database file type was encountered.
18	The specified database is corrupted.
19	An invalid password was provided or the key database has been tampered with or corrupted.
20	A database key entry integrity error occurred.
21	A duplicate certificate exists in the database.
22	A duplicate key exists in the database (Record ID).
23	A certificate with the same label exists in the key database.
24	A duplicate key exists in the database (Signature).
25	A duplicate key exists in the database (Unsigned Certificate).
26	A duplicate key exists in the database (Issuer and Serial Number).
27	A duplicate key exists in the database (Subject Public Key Info).
28	A duplicate key exists in the database (Unsigned CRL).
29	The label has been used in the database.
30	A password encryption error occurred.
31	An LDAP related error occurred. (LDAP is not supported by this program)
32	A cryptographic error occurred.
33	An encryption/decryption error occurred.
34	An invalid cryptographic algorithm was found.
35	An error occurred signing data.
36	An error occurred verifying data.
37	An error occurred computing a digest of data.
38	An invalid cryptographic parameter was found.
39	An unsupported cryptographic algorithm was encountered.
40	The specified input size is greater than the supported modulus size.
41	An unsupported modulus size was found.
42	A database validation error occurred.
43	Key entry validation failed.
44	A duplicate extension field exists.
45	The version of the key is wrong.
46	A required extension field does not exist.
47	The validity period does not include today or does not fall within its issuer's validity period
48	The validity period does not include today or does not fall within its issuer's validity period.
49	An error occurred validating the private key usage extension.
50	The issuer of the key was not found.
51	A required certificate extension is missing.
52	An invalid basic constraint extension was found.
53	The key signature validation failed.
54	The root key of the key is not trusted.
55	The key has been revoked.
56	An error occurred validating the authority key identifier extension.
57	An error occurred validating the private key usage extension.
58	An error occurred validating the subject alternative name extension.
59	An error occurred validating the issuer alternative name extension.
60	An error occurred validating the key usage extension.
61	An unknown critical extension was found.
62	An error occurred validating key pair entries.
63	An error occurred validating CRL.
64	A mutex error occurred.
65	An invalid parameter was found.
66	A null parameter or memory allocation error was encountered.
67	Number or size is too large or too small.
68	The old password is invalid.
69	The new password is invalid.
70	The password has expired.
71	A thread-related error occurred.
72	An error occurred creating threads.
73	An error occurred while a thread was waiting to exit.
74	An I/O error occurred.
75	An error occurred loading CMS.
76	A cryptography hardware-related error occurred.
77	The library initialization routine was not successfully called.
78	The internal database handle table is corrupted.
79	A memory allocation error occurred.
80	An unrecognized option was found.
81	An error occurred getting time information.
82	Mutex creation error occurred.
83	An error occurred opening message catalog.
84	An error occurred opening error message catalog
85	A null file name was found.
86	An error occurred while opening files, check for file existence and permissions.
87	An error occurred opening files to read.
88	An error occurred opening files to write.
89	No such file.
90	The file cannot be opened because of its permission setting.
91	An error occurred writing data to files.
92	An error occurred deleting files.
93	Invalid Base64-encoded data was found.
94	An invalid Base64 message type was found.
95	An error occurred while encoding data with Base64 encoding rule.
96	An error occurred decoding Base64-encoded data.
97	An error occurred getting a distinguished name tag.
98	The required common name field is empty.
99	The required country or region name field is empty.
100	An invalid database handle was found.
101	The key database does not exist.
102	The request key pair database does not exist.
103	The password file does not exist.
104	The new password is identical to the old one.
105	No key was found in the key database.
106	No request key was found.
107	No trusted CA was found.
108	No request key was found for the certificate.
109	There is no private key in the key database.
110	There is no default key in the key database.
111	There is no private key in the key record.
112	There is no certificate in the key record.
113	There is no CRL entry.
114	An invalid key database file name was found.
115	An unrecognized private key type was found.
116	An invalid distinguished name input was found.
117	No key entry was found that has the specified key label.
118	The key label list is corrupted.
119	The input data is not valid PKCS12 data.
120	The password is invalid or the PKCS12 data is corrupted or has been created with later version of PKCS12
121	An unrecognized key export type was found.
122	An unsupported password-based encryption algorithm was found.
123	An error occurred converting the key ring file to a CMS key database.
124	An error occurred converting the CMS key database to a key ring file.
125	An error occurred creating a certificate for the certificate request.
126	A complete issuer chain cannot be built.
127	Invalid WEBDB data was found.
128	There is no data to be written to the key ring file.
129	The number of days that you entered extends beyond the permitted validity period.
130	The password is too short; it must consist of at least {0} characters.
131	A password must contain at least one numeric digit.
132	All characters in the password are either alphabetic or numeric characters.
133	An unrecognized or unsupported signature algorithm was specified.
134	An invalid database type was encountered.
135	The specified secondary key database is in use by another PKCS#11 device.
136	No secondary key database was specified.
137	The label does not exist on the PKCS#11 device.
138	Password is required to access the PKCS#11 device.
139	Password is not required to access the PKCS#11 device.
140	Unable to load the cryptographic library.
141	PKCS#11 is not supported for this operation.
142	An operation on a PKCS#11 device failed.
143	The LDAP user is not a valid user. (LDAP is not supported by this program)
144	The LDAP user is not a valid user. (LDAP is not supported by this program)
145	The LDAP query failed. (LDAP is not supported by this program)
146	An invalid certificate chain was found.
147	The root certificate is not trusted.
148	A revoked certificate was encountered.
149	A cryptographic object function failed.
150	There is no certificate revocation list data source available.
151	There is no cryptographic token available.
152	FIPS mode is not available.
153	There is a conflict with the FIPS mode settings.
154	The password does not meet the minimum required strength.
200	There was a failure during initialization of the program.
201	Tokenization of the arguments passed to the runmqakm Program failed.
202	The object that is identified in the command is not a recognized object.
203	The action is not a known -keydb action.
204	The action is not a known -cert action.
205	The action is not a known -certreq action.
206	There is a tag missing for the requested command.
207	The value that is passed with the -version tag is not a recognized value.
208	The value that is passed with the -size tag is not a recognized value.
209	The value that is passed in with the -dn tag is not in the correct format.
210	The value that is passed in with the -format tag is not a recognized value.
211	There was an error with opening the file.
212	PKCS12 is not supported at this stage.
213	The cryptographic token that you are trying to change the password for is not password protected.
214	PKCS12 is not supported at this stage.
215	The password does not meet the minimum required strength.
216	FIPS mode is not available.
217	The number of days entered as the expiry date is out of the allowed range.
218	Password strength failed the minimum requirements.
219	No Default certificate was found in the requested key database.
220	An invalid trust status was encountered.
221	An unsupported signature algorithm was encountered. At this stage only MD5 and SHA1 are supported.
222	PCKS11 is not supported for that particular operation.
223	The action is not a known -random action.
224	A length less than zero is not allowed.
225	When using the -strong tag the minimum length password is 14 characters.
226	When using the -strong tag the maximum length password is 300 characters.
227	The MD5 algorithm is not supported when in FIPS mode.
228	The site tag is not supported for the -cert -list command. This attribute is added for backward compatibility and potential future enhancement.
229	The value associated with the -ca tag is not recognized. The value must be either 'true' or 'false'.
230	The value passed in with the -type tag is not valid.
231	The value passed in with the -expire tag is below the allowed range.
232	The encryption algorithm that is used or requested is not supported.
233	The target exists.