Docs / VSX KMS/i

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

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.