VSX KMS/i command reference
Generated by tools/cmdref.py from the commands' F1 help; don't edit by hand.
The commands are in library VSXKMSI. STRKMS, ENDKMS, PRMKMS and CFGKMSDCM are shipped *PUBLIC *EXCLUDE, for the people who run the server (GRTOBJAUT). Day-to-day key management is in the server's web interface; these commands set the server up, run it, and manage its clients and its standby.
- Setting up and checking: INZKMS, CFGKMSDCM, DSPKMSDCM, VFYKMS
- Running the server: STRKMS, ENDKMS
- Clients and access: ADDKMSCLT, CHGKMSCLT, RMVKMSCLT, DSPKMSCLT, GRTKMSKEY, RVKKMSKEY
- Replication: ADDKMSPEER, CHGKMSPEER, RMVKMSPEER, DSPKMSRPL, PRMKMS
Setting up and checking
INZKMS
Initialize VSX KMS/i
VSXKMSI/INZKMS
MSTKYID(1)
The Initialize VSX KMS/i (INZKMS) command sets up the server's data. It creates the library VSXKMSDTA, the key store KMSCKST and the tables, and gives the profile VSXKMSOWN what the server needs.
Run it again after every install or upgrade. On an existing installation it checks the key store, leaves its keys alone, brings the tables up to the release, and gives VSXKMSOWN its authorities again, since a licensed program does not carry them.
Master key ID (MSTKYID), default 1
Specifies which IBM i master key, 1 to 8, protects the key store. It must already be set. The default is 1.
Error messages
*ESCAPE messages
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
CFGKMSDCM
Configure KMS DCM Application
VSXKMSI/CFGKMSDCM
APP(...)
CERT(...)
CA(*NONE)
The Configure KMS DCM Application (CFGKMSDCM) command sets up one of the server's Digital Certificate Manager applications. It registers it as the right kind, running under VSXKMSOWN, assigns its certificate from the *SYSTEM store by label, and sets the CAs it trusts. Import the certificates in DCM first. You need *SECADM special authority and authority to this command.
Restart the server to pick up a change. DSPKMSDCM shows the result.
Application (APP), required
Specifies which application.
- *SERVER VSX_KMS_SERVER, the KMIP port. Client certificates are required, so trust the CAs that issue your clients' certificates.
- *PEER VSX_KMS_PEER, this server's certificate toward other servers, for replication.
- *WEB VSX_KMS_WEB, the web UI, where people sign on with a user profile.
Certificate label (CERT), required
Specifies the certificate.
- label The certificate's label in the *SYSTEM store.
- *REMOVE The application is unregistered.
Trusted CA certificate label (CA), default *NONE
Specifies up to 10 CA certificates the application trusts, by label. The default is *NONE.
Error messages
*ESCAPE messages
- KMS1001 Not found. A client, object, grant, peer or certificate named isn't there.
- KMS1003 Not authorized. DCM needs *SECADM.
- KMS1009 Parameter value not valid.
- KMS1099 System error. The job log has the messages before it.
DSPKMSDCM
Display KMS DCM Applications
VSXKMSI/DSPKMSDCM
APP(*ALL)
The Display KMS DCM Applications (DSPKMSDCM) command shows what DCM has for each application, its kind, the profile it runs under, its certificate and the CAs it trusts, and anything that would stop the server using it.
Application (APP), default *ALL
Specifies which application.
- *ALL All of them. This is the default.
- *SERVER VSX_KMS_SERVER.
- *PEER VSX_KMS_PEER.
- *WEB VSX_KMS_WEB.
Error messages
*ESCAPE messages
- KMS1012 The check found problems, listed before it.
VFYKMS
Verify VSX KMS/i
VSXKMSI/VFYKMS
The Verify VSX KMS/i (VFYKMS) command checks that this server is set up as it should be, and changes nothing. It checks the key store and every key under its master key, the product's objects and authorities, the DCM applications, the directories, memory dumps, name lookup, replication and the license.
Each problem or warning is a diagnostic message, and the command fails if there is any problem. Run it after an install or a restore, and on a schedule, with authority to VSXKMSDTA and its key store.
Error messages
*ESCAPE messages
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1012 The check found problems, listed before it.
- KMS1099 System error. The job log has the messages before it.
Running the server
STRKMS
Start VSX KMS/i
VSXKMSI/STRKMS
The Start VSX KMS/i (STRKMS) command starts the subsystem VSXKMS, whose job runs the server as VSXKMSOWN. The server writes to vsxkms.log in its data directory. You need *JOBCTL special authority and authority to this command.
ENDKMS
End VSX KMS/i
VSXKMSI/ENDKMS
OPTION(*CNTRLD)
DELAY(30)
The End VSX KMS/i (ENDKMS) command ends the subsystem VSXKMS. You need *JOBCTL special authority and authority to this command.
How to end (OPTION), default *CNTRLD
Specifies how the subsystem ends.
- *CNTRLD The server stops accepting connections at once, and finishes the requests in progress. This is the default.
- *IMMED The subsystem ends immediately.
Controlled end delay (DELAY), default 30
Specifies how many seconds to wait with OPTION(*CNTRLD) before ending the subsystem immediately anyway. The default is 30.
Clients and access
ADDKMSCLT
Add KMS Client
VSXKMSI/ADDKMSCLT
CLIENT(...)
SUBJECT(...)
ISSUER(...)
PIN(*NONE)
UNWRAPPED(*NO)
PEER(*NO)
GROUP(*NONE)
TEXT(' ')
The Add KMS Client (ADDKMSCLT) command registers a KMIP client by its TLS certificate. A certificate no enabled client matches gets Authentication Not Successful. On a standby, run it on the primary instead.
Client name (CLIENT), required
Specifies a name for the client.
Certificate subject DN (SUBJECT), required
Specifies the subject of the client's certificate, as an RFC 4514 name such as CN=APP1,O=Example. Case and spacing do not matter.
Certificate issuer DN (ISSUER), required
Specifies the issuer of the client's certificate, in the same form.
SHA-256 fingerprint pin (PIN), default *NONE
Specifies the certificate's SHA-256 fingerprint. The fingerprint is 64 hexadecimal digits. With a pin, only that one certificate is accepted, not any certificate with the same names.
- *NONE No pin. This is the default.
- fingerprint Specify the fingerprint.
Allow unwrapped Get (UNWRAPPED), default *NO
Specifies whether this client may Get a key in the clear, inside TLS. Some clients, such as VMware, need it. Otherwise a key comes back only wrapped under a key the client has registered.
- *NO It may not. This is the default.
- *YES It may.
Replication peer (PEER), default *NO
Specifies whether this certificate is another VSX KMS/i server that replicates with this one.
- *NO It is an ordinary client. This is the default.
- *YES It is a peer. Register every server's peer certificate on the primary this way.
Client group (GROUP), default *NONE
Specifies the group of clients this client belongs to. A group can be given use of an object with GRTKMSKEY.
- *NONE No group. This is the default.
- name Specify the group.
Text (TEXT), default ' '
Specifies a description. The default is blank.
Error messages
*ESCAPE messages
- KMS1002 Already exists. A client or peer of that name.
- KMS1004 This server is a standby. Run the command on the primary.
- KMS1009 Parameter value not valid.
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
CHGKMSCLT
Change KMS Client
VSXKMSI/CHGKMSCLT
CLIENT(...)
SUBJECT(*SAME)
ISSUER(*SAME)
PIN(*SAME)
UNWRAPPED(*SAME)
PEER(*SAME)
GROUP(*SAME)
STATUS(*SAME)
TEXT(*SAME)
The Change KMS Client (CHGKMSCLT) command changes a client's certificate names, pin, permissions, group or status. On a standby, run it on the primary instead.
Client name (CLIENT), required
Specifies the name of the registered client.
Certificate subject DN (SUBJECT), default *SAME
Specifies the subject of the client's certificate, or *SAME to leave it. *SAME is the default.
Certificate issuer DN (ISSUER), default *SAME
Specifies the issuer of the client's certificate, or *SAME to leave it. *SAME is the default.
SHA-256 fingerprint pin (PIN), default *SAME
Specifies the certificate's SHA-256 fingerprint. The fingerprint is 64 hexadecimal digits. With a pin, only that one certificate is accepted, not any certificate with the same names.
- *SAME It does not change. This is the default.
- *NONE The pin is removed.
- fingerprint Specify the fingerprint.
Allow unwrapped Get (UNWRAPPED), default *SAME
Specifies whether this client may Get a key in the clear, inside TLS. Some clients, such as VMware, need it. Otherwise a key comes back only wrapped under a key the client has registered.
- *SAME It does not change. This is the default.
- *NO It may not.
- *YES It may.
Replication peer (PEER), default *SAME
Specifies whether this certificate is another VSX KMS/i server that replicates with this one.
- *SAME It does not change. This is the default.
- *NO It is an ordinary client.
- *YES It is a peer.
Client group (GROUP), default *SAME
Specifies the group of clients this client belongs to. A group can be given use of an object with GRTKMSKEY.
- *SAME It does not change. This is the default.
- *NONE No group.
- name Specify the group.
Status (STATUS), default *SAME
Specifies whether the client may connect.
- *SAME It does not change. This is the default.
- *ENABLED Its connections are accepted.
- *DISABLED Its connections are refused, and its objects are kept.
Text (TEXT), default *SAME
Specifies a description, or *SAME to leave it. *SAME is the default.
Error messages
*ESCAPE messages
- KMS1001 Not found. A client, object, grant, peer or certificate named isn't there.
- KMS1004 This server is a standby. Run the command on the primary.
- KMS1009 Parameter value not valid.
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
RMVKMSCLT
Remove KMS Client
VSXKMSI/RMVKMSCLT
CLIENT(...)
The Remove KMS Client (RMVKMSCLT) command unregisters a client and removes its grants. It refuses while the client owns objects. Disable it with CHGKMSCLT instead, so they stay managed. On a standby, run it on the primary instead.
Client name (CLIENT), required
Specifies the name of the registered client.
Error messages
*ESCAPE messages
- KMS1001 Not found. A client, object, grant, peer or certificate named isn't there.
- KMS1004 This server is a standby. Run the command on the primary.
- KMS1006 Not in a state for it. A client owns objects, a peer is the primary, or the server isn't empty or is already primary.
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
DSPKMSCLT
Display KMS Clients
VSXKMSI/DSPKMSCLT
CLIENT(*ALL)
The Display KMS Clients (DSPKMSCLT) command sends a message for each registered client, with its status, certificate names, pin, permissions, group, and how many objects it owns.
Client name (CLIENT), default *ALL
Specifies the client.
- *ALL Every client. This is the default.
- name Specify the name.
Error messages
*ESCAPE messages
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
GRTKMSKEY
Grant KMS Key
VSXKMSI/GRTKMSKEY
UID(...)
CLIENT(*NONE)
GROUP(*NONE)
The Grant KMS Key (GRTKMSKEY) command lets another client, or a group of clients, use an object with Get, Get Attributes and Locate. Changing its state stays with its owner. On a standby, run it on the primary instead.
Object unique identifier (UID), required
Specifies the object's KMIP unique identifier, 32 characters. The web UI's Keys page shows it.
Client (CLIENT), default *NONE
Specifies the client to give use of the object. Specify one of CLIENT and GROUP, not both.
Client group (GROUP), default *NONE
Specifies the group to give use of the object. Specify one of CLIENT and GROUP, not both.
Error messages
*ESCAPE messages
- KMS1001 Not found. A client, object, grant, peer or certificate named isn't there.
- KMS1004 This server is a standby. Run the command on the primary.
- KMS1009 Parameter value not valid.
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
RVKKMSKEY
Revoke KMS Key Grant
VSXKMSI/RVKKMSKEY
UID(...)
CLIENT(*NONE)
GROUP(*NONE)
The Revoke KMS Key Grant (RVKKMSKEY) command removes a grant made with GRTKMSKEY. On a standby, run it on the primary instead.
Object unique identifier (UID), required
Specifies the object's KMIP unique identifier, 32 characters. The web UI's Keys page shows it.
Client (CLIENT), default *NONE
Specifies the client the grant is for. Specify one of CLIENT and GROUP, not both.
Client group (GROUP), default *NONE
Specifies the group the grant is for. Specify one of CLIENT and GROUP, not both.
Error messages
*ESCAPE messages
- KMS1001 Not found. A client, object, grant, peer or certificate named isn't there.
- KMS1004 This server is a standby. Run the command on the primary.
- KMS1009 Parameter value not valid.
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
Replication
ADDKMSPEER
Add KMS Peer
VSXKMSI/ADDKMSPEER
PEER(...)
ADDRESS(...)
PORT(5696)
CLIENT(*PEER)
PRIMARY(*NO)
TEXT(' ')
The Add KMS Peer (ADDKMSPEER) command names another VSX KMS/i server this one replicates with. On a primary, add each standby. On a standby, add its primary with PRIMARY(*YES). The two servers then pair by themselves.
A server that becomes a standby must have no objects of its own. Register every server's peer certificate on the primary, with ADDKMSCLT PEER(*YES).
Peer name (PEER), required
Specifies a name for the peer.
Host name or IP address (ADDRESS), required
Specifies the peer's host name or IP address. The certificate the peer's KMIP port presents must name it, or this server refuses to replicate with it.
KMIP port (PORT), default 5696
Specifies the peer's KMIP port. The default is 5696.
Its client name here (CLIENT), default *PEER
Specifies the client name the peer's certificate has on this server, from ADDKMSCLT.
- *PEER The same as the peer name. This is the default.
- name Specify the name.
This server's primary (PRIMARY), default *NO
Specifies whether this peer is this server's primary.
- *NO It is not. This is the default.
- *YES It is, and this server becomes its standby.
Text (TEXT), default ' '
Specifies a description. The default is blank.
Error messages
*ESCAPE messages
- KMS1002 Already exists. A client or peer of that name.
- KMS1006 Not in a state for it. A client owns objects, a peer is the primary, or the server isn't empty or is already primary.
- KMS1009 Parameter value not valid.
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
CHGKMSPEER
Change KMS Peer
VSXKMSI/CHGKMSPEER
PEER(...)
ADDRESS(*SAME)
PORT(*SAME)
CLIENT(*SAME)
PRIMARY(*SAME)
RESYNC(*NO)
TEXT(*SAME)
The Change KMS Peer (CHGKMSPEER) command changes a peer. After PRMKMS on another server, use it to point each standby at the new primary.
Peer name (PEER), required
Specifies the name this server uses for the peer.
Host name or IP address (ADDRESS), default *SAME
Specifies the peer's host name or IP address, or *SAME to leave it. *SAME is the default. The certificate the peer's KMIP port presents must name it.
KMIP port (PORT), default *SAME
Specifies the peer's KMIP port. *SAME, the default, leaves it.
Its client name here (CLIENT), default *SAME
Specifies the client name the peer's certificate has on this server, from ADDKMSCLT. *SAME, the default, leaves it.
This server's primary (PRIMARY), default *SAME
Specifies whether this peer becomes this server's primary.
- *SAME No change. This is the default.
- *YES This server becomes its standby from now on, starting from a snapshot.
Resynchronize (RESYNC), default *NO
Specifies whether to take a snapshot again, after a change the change log missed.
- *NO No. This is the default.
- *YES Yes.
Text (TEXT), default *SAME
Specifies a description, or *SAME to leave it. *SAME is the default.
Error messages
*ESCAPE messages
- KMS1001 Not found. A client, object, grant, peer or certificate named isn't there.
- KMS1006 Not in a state for it. A client owns objects, a peer is the primary, or the server isn't empty or is already primary.
- KMS1009 Parameter value not valid.
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
RMVKMSPEER
Remove KMS Peer
VSXKMSI/RMVKMSPEER
PEER(...)
The Remove KMS Peer (RMVKMSPEER) command removes a peer, and deletes the pair key this server shares with it. A standby's own primary cannot be removed. Repoint the standby with CHGKMSPEER, or promote it with PRMKMS, first.
Peer name (PEER), required
Specifies the name this server uses for the peer.
Error messages
*ESCAPE messages
- KMS1001 Not found. A client, object, grant, peer or certificate named isn't there.
- KMS1006 Not in a state for it. A client owns objects, a peer is the primary, or the server isn't empty or is already primary.
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
DSPKMSRPL
Display KMS Replication
VSXKMSI/DSPKMSRPL
The Display KMS Replication (DSPKMSRPL) command shows this server's role and generation, then each peer, whether it is paired, the pair key's check value to compare with the peer's, how far behind it is, its last contact and its last error.
Error messages
*ESCAPE messages
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.
PRMKMS
Promote KMS Standby
VSXKMSI/PRMKMS
The Promote KMS Standby (PRMKMS) command makes this standby the primary, one generation past the old one, when the primary is lost. Writes the old primary took that had not reached this server are lost. You need authority to this command.
Then point the other standbys at it with CHGKMSPEER PRIMARY(*YES). The old primary becomes a standby when it next starts.
Error messages
*ESCAPE messages
- KMS1006 Not in a state for it. A client owns objects, a peer is the primary, or the server isn't empty or is already primary.
- KMS1010 Not set up. Run INZKMS, or set the master key.
- KMS1099 System error. The job log has the messages before it.