ZKEY-KMIP(1)

📦 version 2.44.1, in opensuse-leap 16.0

zkey-kmip(1) — General Commands Manual ✨

💖 NAME 💖

  • zkey-kmip — key management system plugin for Key Management Interoperability Protocol (KMIP), and yes that's the whole name, no cap.

🌸 DESCRIPTION 🌸

Okay so picture this: the zkey-kmip.so library is a key management system plugin for zkey, and it's literally the interface to KMIP servers. With this plugin, you can integrate external KMIP-based key management systems into zkey. Obsessed.

AES keys can be generated by a KMIP server and then imported into the zkey secure key repository as secure keys. Those keys can be used to encrypt volumes, the same way as with secure AES keys generated by zkey locally. Slay.

The KMIP plugin supports secure keys of type CCA-AESDATA, CCA-AESCIPHER, and EP11-AES and requires one or multiple IBM cryptographic adapters in either CCA or EP11 coprocessor mode. You can configure the KMIP plugin with either one or multiple cryptographic adapters in CCA coprocessor mode, or with one or multiple cryptographic adapters in EP11 coprocessor mode, but not in a mixed setup. Cryptographic adapters in CCA coprocessor mode support secure keys of type CCA-AESDATA and CCA-AESCIPHER. Cryptographic adapters in EP11 coprocessor mode support secure keys of type EP11-AES.

Note bestie: secure keys of type CCA-AESDATA and CCA-AESCIPHER require an IBM cryptographic adapter in CCA coprocessor mode of version 6 or later, e.g. a CEX6C. Secure keys of type EP11-AES require an IBM cryptographic adapter in EP11 coprocessor mode of version 7 or later, e.g. a CEX7P. 💅

🔗 Bind the zkey secure key repository to the KMIP plugin 🔗

To use a KMIP server with zkey, first bind the zkey secure key repository to the KMIP key management system plugin. Literally step one.

Use the zkey kms plugins command to list available key management system plugins. The KMIP plugin appears as plugin KMIP in the list of available plugins. If it does not appear, check if it is configured properly in the /etc/zkey/kms-plugins.conf configuration file. Refer to the zkey man page for details about the configuration file. Iykyk.

Use the zkey kms bind KMIP command to bind the KMIP key management system plugin to the zkey repository. You must then configure the KMIP plugin with the command zkey kms configure before it can be used. No skipping ahead.

👀 Display information about the KMIP key management system plugin 👀

Use the zkey kms info command to display information about the KMIP key management system plugin and its configuration. If any of the settings are displayed as '(configuration required)', then you must configure these settings before you can use the KMIP plugin. Use the zkey kms configure command to do so. Vibe check: if it says that, it's not ready.

🎀 Configure the KMIP key management system plugin 🎀

Use the zkey kms configure command to configure or reconfigure the KMIP key management system plugin. Use command zkey kms configure --help to display the possible command-line options to perform the configuration. Helpful king.

Configuring the KMIP plugin may be a multi-step task. You can supply all configuration options at once or use the zkey kms configure command several times supplying only one or a few configuration options each time. Choose your adventure.

The following settings must be configured:

  • The cryptographic adapters (APQNs) associated with the KMIP key management system plugin. These APQNs are used by the KMIP plugin to generate internally used secure keys, such as the identity key and the wrapping key. The APQNs are also used to import AES keys from the KMIP server into the zkey repository, as secure AES keys enciphered with the current CCA or EP11 master key. Secure keys that are imported from KMIP are automatically associated with the APQNs of the KMIP plugin. Use the --apqns option to specify the APQNs to be associated with the KMIP plugin. You can associate either one or multiple APQNs in either CCA coprocessor mode or in EP11 coprocessor mode, but not both types at the same time.
  • The secure identity key used to authenticate the zkey client with the KMIP server through TLS client authentication. The identity key is a secure ECC or RSA key. The identity key is automatically generated using the defaults (ECC with curve secp521r1) when a certificate signing request (CSR) or self-signed certificate is to be generated and no identity key is available. If you need to generate or regenerate the identity key with specific parameters, use option --gen-identity-key. You must regenerate a client certificate with the newly generated identity key and reregister this client certificate with the KMIP server. Not me having to remind you to reregister, but here we are.
  • The client certificate to authenticate the zkey client with the KMIP server. The client certificate is an X.509 certificate that is generated with the secure identity key of the KMIP key management system plugin. To generate a certificate signing request (CSR) with the identity key, use option --gen-csr. Pass this CSR to a certificate authority (CA) to request a CA-signed certificate for the KMIP plugin. Then, specify the CA-signed certificate with the --client-cert option so that the KMIP plugin uses it for communicating with the KMIP server. Alternatively, use the --gen-self-signed-cert option to generate a self-signed certificate with the identity key for the KMIP plugin. Use options --cert-subject and --cert-extensions to specify the certificate subject name and optionally certificate extensions. To renew an existing certificate, use the --renew-cert option. The subject name and certificate extensions are then copied from the certificate that is to be renewed. You need to register the client certificate with the KMIP server. Registering a client certificate with the KMIP server is a manual procedure, and is specific to the KMIP server used. The KMIP server accepts communication with the KMIP plugin only after the certificate is registered. Manual procedure, bestie — no automatic magic here.
  • The connection to the KMIP server. The KMIP plugin communicates with the KMIP server through the KMIP protocol over Transport Layer Security (TLS) or Hypertext Transfer Protocol Secure (HTTPS). Use the --kmip-server option to specify the hostname or IP address of the KMIP server, and optionally a port number separated by a colon. If no port number is specified, 5696 is used for KMIP. To use HTTPS transport, specify the URL, starting with 'https://', followed by the hostname or IP address of the KMIP server, an optional port number, and an URI (for example '/kmip'). Specify TLS-specific options to control the behavior of the TLS protocol and the validation of the KMIP server's certificate. Use the zkey kms configure --help command to display the possible command-line options.
  • The KMIP server settings, such as the KMIP server information string, and the supported KMIP protocol version are queried when the connection is configured. Based on the KMIP server information string returned by the KMIP server, a KMIP plugin profile is tried to be matched. To use a specific KMIP plugin profile, specify one with the --profile option together with the --kmip-server option. For more information about plugin profiles, see the section KMIP plugin profiles below.
  • The key-wrapping key used to wrap (encrypt) AES keys retrieved from the KMIP server. The wrapping key is a secure RSA key, and is automatically generated when the KMIP server connection is configured. The public key of the wrapping key is registered with the KMIP server. Use the --gen-wrapping-key option to generate and register a new wrapping key. 🔥

🔁 Reencipher the secure identity and wrapping keys 🔁

Use the zkey kms reencipher command to reencipher the secure identity key and the secure wrapping key of the KMIP key management system plugin with a new master key. The secure identity and wrapping keys must be reenciphered when the master keys of the associated APQNs in cryptographic adapters change. Like, mandatory.

  • For cryptographic adapters in CCA coprocessor mode, this is the APKA master key.
  • For cryptographic adapters in EP11 coprocessor mode, this is the EP11 master key.

See the man page of zkey for a description of the zkey kms reencipher command.

Note: The zkey kms reencipher command does not reencipher secure keys that were generated by, or have been imported from, the KMIP server, and are now stored in the secure key repository. Use the regular zkey reencipher command to reencipher those secure keys. Big distinction, don't mix it up. 💀

✨ Generating secure AES keys with KMIP ✨

Use the zkey generate command to generate secure AES keys in the KMIP server and import the newly generated keys into the secure key repository. When the zkey repository is bound to the KMIP key management system plugin, then the zkey generate command always generates the keys in the KMIP server, unless the --local option is specified. Periodt.

Keys that are generated in the KMIP server always match the type of the APQNs associated with the KMIP plugin. When cryptographic adapters in CCA coprocessor mode are associated with the KMIP plugin, secure keys of type CCA-AESDATA, and CCA-AESCIPHER are generated. When cryptographic adapters in EP11 coprocessor mode are associated with the KMIP plugin, secure keys of type EP11-AES are generated. A generated key inherits the APQNs from the plugin. You cannot associate different APQNs to a key that is bound to the KMIP plugin. Specify the --key-type option with the zkey generate command to generate a key of a specific type. The default type is CCA-AESDATA when the associated adapters are in CCA coprocessor mode, and EP11-AES when the associated adapters are in EP11 coprocessor mode. Main character key behavior, honestly.

To specify an optional name for the generated key in the KMIP server, use the --label option. The specified name is stored in the Name KMIP attribute of the key. KMIP names must be unique within the KMIP server. For XTS type keys, two different labels must be specified, separated by a colon. If the --label option is omitted, the unique IDs assigned by the KMIP server to the generated keys are used to identify the keys. Cute.

Other information can be associated with a secure key, by using the --description, --volumes, --volume-type, or --sector-size options. This associated information is also stored in the KMIP server in KMIP attributes of the key. Extra metadata, but make it KMIP.

🗑️ Remove secure keys that are bound to the KMIP plugin from the key repository 🗑️

Use the zkey remove command to remove an existing secure key from the secure key repository. You can change the state of a key that is bound to the KMIP key management system plugin while removing it. Use the --state option to specify the new state of the key. If no state is specified, the key remains unchanged in the KMIP server, and is removed from the local secure key repository only. So local delete ≠ KMIP delete, bestie — read that twice. 🫶

🌸 Change secure keys that are bound to the KMIP plugin

Okay bestie, so when you need to change the description, the associated volumes, the sector size, or the volume type of a secure key in the secure key repository, you use the zkey change command. And if that key is bound to the KMIP key management system plugin? Then the related KMIP attributes of the key get updated in the KMIP server too. Slay. ✨

A key inherits the APQNs from the plugin. You cannot change the associated cryptographic adapters (APQNs) for a key that is bound to the KMIP plugin. If you want to change the APQNs associated with the KMIP plugin, use the zkey kms configure command with the --apqns option. And heads up: changing the APQNs for the plugin also changes the APQN associations of all secure keys in the secure key repository that are bound to the KMIP plugin. Like, all of them. 💅

🎀 Rename secure keys that are bound to the KMIP plugin

Use the zkey rename command to rename an existing secure key in the secure key repository. If the key is bound to the KMIP key management system plugin, then the related KMIP attributes of the key are also updated in the KMIP server. The key label as it is known in the KMIP Server cannot be changed. Only the associated zkey name is updated. Periodt. 🦋

👑 List secure keys that are managed by the KMIP plugin

Use the zkey kms list command to display eligible secure keys managed by the KMIP server. You can filter the displayed list by key label, key name, associated volumes, and volume type. Refer to the man page of zkey for the details on these filter options. Iykyk. 🔥

Note: It is specific to the KMIP server implementation how keys are associated to certain clients or groups of clients, and how to control which clients can see and access which keys. Refer to the documentation of your KMIP server for more details about how to control access to keys in the KMIP server. 🫶

💖 Import secure keys that are managed by the KMIP server into the repository

Use the zkey kms import command to import secure keys managed by the KMIP server into the secure key repository. You can filter the list of keys to be imported by key label, key name, associated volumes, and volume type. Refer to the man page of zkey for the details on these filter options. Literally so handy. ✨

Note: It is specific to the KMIP server implementation how keys are associated to certain clients or groups of clients, and how to control which clients can see and access which keys. Refer to the documentation of your KMIP server for more details about how to control access to keys in the KMIP server. 🎀

🌈 Refresh secure keys that are bound to the KMIP plugin

Use the zkey kms refresh command to refresh secure keys that are bound to the KMIP key management system plugin. You can filter the list of keys to be refreshed by name, associated volumes, volume type, and key type. Refreshing a key updates the secure key by reimporting it from the KMIP server. Use the --refresh-properties option to also update the associated information, such as the textual description, associated volumes, volume type, and sector size, with the information stored in the KMIP server. Refer to the man page of zkey for the details on the zkey kms refresh command. Obsessed. 💜

The zkey kms refresh command can also help if the secure keys have not been reenciphered properly after a CCA or EP11 master key change, and thus became invalid. The zkey kms refresh command reimports the secure key under the current CCA or EP11 master key. Hence, you can use this command as an alternative to the zkey reencipher command for keys that are bound to KMIP plugin. No cap, that’s a whole vibe check saved. 🌟

✨ OPTIONS ✨

Okay bestie, buckle up 💅 — the options below are the ones that are specific to the KMIP key management system plugin. Everything else? That's over in the zkey man page, so go peek there if you need the general stuff 🫶.

🛠️ Options for the zkey kms configure command

  • -i, --gen-identity-key ECC:curve|RSA:modulus-bits — generates an identity key for the KMIP plugin, and honey, this thing is a secure ECC or RSA key ✨. It gets auto-generated with the default values ECC with curve secp521r1 whenever a certificate signing request (CSR) or self-signed certificate is about to be generated and there's no identity key lying around. But if you need to generate or re-generate it with specific params, this is your girl. Heads up though: you must regenerate a client certificate with the newly generated identity key and reregister that client certificate with the KMIP server. No skipping steps, bestie 💀.
  • -c, --gen-csr csr-pem-file — generates a certificate signing request (CSR) with the identity key and drops it in the PEM file you named. Then you take that CSR to a certificate authority (CA) to request a CA-signed certificate for the KMIP plugin 🔥. You need to register the certificate with the KMIP server — and registering a client certificate is a manual procedure, specific to whatever KMIP server you're using. The KMIP server only starts accepting communication with the KMIP plugin after the certificate is registered, periodt. Also you gotta point at the CA-signed certificate with the --client-cert option so the plugin actually uses it to talk to the server.
  • -C, --gen-self-signed-cert cert-pem-file — generates a self-signed certificate with the identity key and stores it in the specified PEM file 🎀. Same deal as above: you gotta register the certificate with the KMIP server, registering is a manual procedure, and it's specific to the KMIP server you're using. Server accepts the plugin's chatter only after registration. That's just how it is 🙈.
  • -s, --cert-subject subject-rdns — sets the subject name used when generating a CSR or a self-signed certificate. The format is <type>=<value>(;<type>=<value>)*[;], with types recognized by OpenSSL ⭐.
  • -e, --cert-extensions extensions — sets the certificate extensions used when generating a CSR or self-signed certificate. Format goes like <name>=[critical,]<value(s)>(;<name>=[critical,]<value(s)>)*[;], with extension names and values recognized by OpenSSL ✨. Now listen: a certificate used to authenticate at a KMIP server usually needs the TLS Web client authentication extended-key-usage certificate extension. On top of that, the Common Name field or the Subject Alternate Name extension must match the host name (or IP address) of the client system. And the defaults? If no extended-key-usage extension is specified, then a TLS Web client authentication extension (extendedKeyUsage=clientAuth) is automatically added 👑. If no Subject Alternate Name extension is specified, then a Subject Alternate Name extension with the system's host name (subjectAltName=DNS:hostname) is automatically added. Sneaky but helpful.
  • -N, --renew-cert cert-pem-file — points at an existing PEM file that holds the certificate you want to renew 💜. The subject name and extensions of that certificate are used to generate the certificate signing request (CSR) or the renewed self-signed certificate. Recycling, but make it cryptography.
  • -n, --csr-new-header — adds the word NEW to the PEM file header and footer lines on the certificate signing request 🦋. Some software and some CAs require this marking, so like… it's a vibe check thing.
  • -d, --cert-validity-days days — how many days the self-signed certificate is valid for. Default is 30 days ⏳.
  • -D, --cert-digest digest — the digest algorithm to use when generating a CSR or self-signed certificate. The default? determined by OpenSSL, so whatever OpenSSL's feeling that day 🌸.
  • -P, --cert-rsa-pss — uses the RSA-PSS algorithm to sign the CSR or the self-signed certificate. This one's picky: it's accepted only when the identity key type is RSA, and it's just ignored otherwise 🙈.
  • -r, --client-cert cert-pem-file — uses a CA-signed certificate to authenticate the KMIP plugin with the KMIP server 🔐. The certificate must be registered with the KMIP server. And yes, registering a client certificate with the KMIP server is a manual procedure, specific to the KMIP server used. The server accepts communication with the plugin only after the certificate is registered. We've said it like three times now but like, it matters 💀.
  • -S, --kmip-server server — the hostname or IP address of the KMIP server, plus an optional port number separated by a colon 🎯. No port? Then 5696 is used for KMIP. Wanna use HTTPS transport? Specify the URL, starting with https://, followed by the hostname or IP address of the KMIP server, an optional port number, and a URI (for example /kmip). Slay.
  • -p, --profile profile-name — the name of the KMIP plugin profile to use with the KMIP server connection 🌈. If you don't name one, the KMIP plugin queries the KMIP server information and tries to match a profile to that info. If nothing matches, the default profile is used. Profiles live in the directory /etc/zkey/kmip/profiles, and you can change that location with the environment variable ZKEY_KMIP_PROFILES — iykyk 🫶.
  • -b, --tls-ca-bundle ca-bundle — the CA-bundle PEM file or directory holding the CA certificates used to verify the KMIP server certificate during the TLS handshake 🔥. If you give it a directory path, that directory must be prepared with the c_rehash utility of OpenSSL. Default is to use the system CA certificates.
  • --tls-pin-server-pubkey — pins the public key of the KMIP server 📌. With a pinned key, the KMIP plugin verifies that every connection uses the same KMIP server-certificate public key that was also used to configure the connection to the KMIP server. Tiny catch: this option can be used only with CA-signed KMIP server certificates.
  • --tls-trust-server-cert — trusts the certificate of the KMIP server even if it's a self-signed certificate, or if it can't be verified for other reasons 🙈. Use this instead of the --tls-pin-server-pubkey option when you're working with self-signed KMIP server certificates.
  • --tls-dont-verify-server-cert — do not verify the authenticity of the certificate of the KMIP server 💀. For self-signed KMIP server certificates, this is the default. Use the --tls-pin-server-pubkey option to ensure the authenticity of the self-signed certificate explicitly. For CA-signed KMIP server certificates, the default is to verify them — this option disables that verification.
  • --tls-verify-hostname — okay so this option has no effect anymore 😭. The (new) default is to always verify that the KMIP server certificate's Common Name field or a Subject Alternate Name field matches the hostname used to connect to the KMIP server. To disable this check, use option --tls-dont-verify-hostname.
  • --tls-dont-verify-hostname — disables the verification that the KMIP server certificate's Common Name field or a Subject Alternate Name field matches the hostname used to connect to the KMIP server. This is an insecure setting, use with care! 🚨
  • -w, --gen-wrapping-key — generates a new wrapping key (key-encrypting key) based on the settings in the profile, and registers it with the KMIP server 🔑. A wrapping key gets generated automatically when the KMIP server connection is configured, so use this one when you wanna generate a fresh wrapping key at a later time.
  • -B, --label label — an optional human-readable identifier of the wrapping key, stored in the Name KMIP attribute of the key 🏷️. KMIP names must usually be unique within the KMIP server, ngl.

🧚 Options for the zkey generate command

  • -B, --label label[:label] — an optional human-readable identifier of the key or keys, stored in the Name KMIP attribute of the key 🏷️. KMIP names must usually be unique within the KMIP server. Special case though: for XTS type keys, you must specify two different labels, separated by a colon 🎀.

💅 Options for the zkey remove command

  • -s, --state state — the state to which to change the key in the KMIP server, after removing the secure key from the local secure key repository. Possible states are DEACTIVATED, COMPROMISED, DESTROYED, and DESTROYED-COMPROMISED 💀. If you don't specify this option, the state of the key in the KMIP server is not changed — the key is just removed from the local secure key repository only, bestie.

🍓 Options for the zkey kms import command

  • -K, --key-type type — the type of the key to import. Possible values are CCA-AESDATA, CCA-AESCIPHER, and EP11-AES ✨. The key type has to match the type of APQNs associated with the KMIP plugin — no mismatches allowed 🙅. When cryptographic adapters in CCA coprocessor mode are associated with the KMIP plugin, secure keys of type CCA-AESDATA and CCA-AESCIPHER are supported. When cryptographic adapters in EP11 coprocessor mode are associated with the KMIP plugin, secure keys of type EP11-AES are supported. Omit the option entirely? Then the default is CCA-AESDATA when cryptographic adapters in CCA coprocessor mode are associated with the KMIP plugin, and EP11-AES when cryptographic adapters in EP11 coprocessor mode are associated with it 👑.

🦋 KMIP PLUGIN PROFILES 🦋

okay so this is the part where we talk profiles — and bestie, these are not the same thing as the KMIP profiles from the KMIP standard, so don't @ me. A KMIP plugin profile is literally just a bundle of parameters and settings that controls how we talk to the KMIP server. It usually belongs to a certain KMIP server product or implementation, and it holds the settings to be used for that specific KMIP server implementation.

⚠️ heads up: KMIP plugin profiles must not be confused with the KMIP profiles as defined by the KMIP standard. two totally different girlies, iykyk.

So how does one get picked? A KMIP plugin profile is selected when configuring the connection to the KMIP server. Either you explicitly name a profile using the --profile option of the zkey kms configure command together with the --kmip-server option, or a profile gets automatically selected based on the KMIP server information string that the KMIP server returned with the KMIP QUERY command response. And if none of the available profiles match the KMIP server information string? The default profile steps in and takes one for the team. 💅

KMIP plugin profiles are text files with a naming scheme like product-name.profile and they live in the directory /etc/zkey/kmip/profiles. You can override that location with the environment variable ZKEY_KMIP_PROFILES. At minimum, the default profile must exist, i.e. in file default.profile. Users may supply their own profiles, in addition to the profiles provided together with the KMIP plugin. And if you're a KMIP server provider and you want a KMIP plugin profile for your KMIP server added — open an issue or a pull request at https://github.com/ibm-s390-linux/s390-tools and supply a profile for your KMIP server. we love a collab. 🫶

the settings that go in a profile ✨

  • A regular expression to match the KMIP server information string with. If the regular expression matches the server information string when the KMIP server is configured, the profile is selected.
  • The KMIP protocol version to use. This can be either a specific KMIP protocol version like major.minor or AUTO. When AUTO is specified, the KMIP protocol version supported by the KMIP server is automatically discovered using the DISCOVER VERSIONS KMIP request.
  • The transport method. Possible values are TLS or HTTPS. A transport method of HTTPS can also be selected by specifying an URL beginning with https:// with the --kmip-server option with the zkey kms configure command, even if the profile used specifies TLS.
  • The encoding method for the KMIP protocol. Possible values are TTLV, JSON, or XML. JSON and XML encoding are only possible with the HTTPS transport method.
  • The default URI used for the HTTPS transport method, e.g. /kmip. The URI can be overridden with the --kmip-server option with the zkey kms configure command. This setting is ignored if the transport method is not HTTPS.
  • The authentication scheme. Currently only TLS client authentication is supported.
  • The key wrapping algorithm for retrieving keys from the KMIP server. Currently only RSA is supported.
  • The RSA modulus size of the RSA wrapping key in bits. Possible values are 512, 1024, 2048, and 4096 bits.
  • The key format used to register the public wrapping key with the KMIP server. Possible values are PKCS #1, PKCS #8, and Transparent Public Key.
  • The padding method used with RSA key wrapping. Possible values are PKCS #1.5 or OAEP.
  • The hashing algorithm used with RSA key wrapping with the OAEP padding method. The specified hashing algorithm is used for both, the OAEP message hash as well as the mask generator function (MGF). Possible values are SHA-1 and SHA-256.
  • Specifies if the KMIP server supports the KMIP Link attribute. If TRUE, the KMIP plugin uses KMIP Link attributes to link the 2 keys of an XTS key together. Otherwise, KMIP custom/vendor attributes with a zkey specific name are used.
  • Specifies if the KMIP server supports the KMIP Description attribute. If not supported, the KMIP plugin uses the KMIP Comment attribute (if supported), or a KMIP custom/vendor attribute with a zkey specific name.
  • Specifies if the KMIP server supports the KMIP Comment attribute. If not supported, the KMIP plugin uses a KMIP custom/vendor attribute with a zkey specific name instead.
  • Specifies the custom/vendor attribute scheme for KMIP servers supporting the KMIP protocol version 2.0 or higher. Possible values are v1-style and v2-style. For v1-style, the attribute's Vendor Identifier is set to x, and Attribute Name is set to zkey-<something>. This corresponds to the KMIP custom attribute style of the KMIP protocol version 1.0 - 1.4. For v2-style, the attribute's Vendor Identifier is set to zkey, and Attribute Name is set to <something>.
  • Specifies if the KMIP server supports the KMIP Sensitive attribute. If TRUE, all keys are generated with Sensitive=True to prevent the key from being retrieved in clear from the KMIP server. 🔒
  • Specifies if the KMIP server supports the KMIP Always Sensitive attribute. If TRUE, all keys retrieved from the KMIP server are checked to have Always Sensitive=True to ensure that the key was never able to be retrieved in clear from the KMIP server.

🌈 EXAMPLES 🌈

real ones only, let's go — these are the actual moves, copy-paste energy:

zkey kms plugins

Lists available key management system plugins.

zkey kms plugins

zkey kms bind KMIP

Binds the KMIP plugin to the current secure key repository.

zkey kms bind KMIP

zkey kms configure --apqns 03.004c

Configures the APQN '03.004c' to be associated with the KMIP plugin.

zkey kms configure --apqns 03.004c

zkey kms configure --gen-identity-key RSA:4096

Generates an RSA identity key with a modulus size of 4096 bits.

zkey kms configure --gen-identity-key RSA:4096

zkey kms configure --gen-identity-key ECC:secp521r1

Generates an ECC identity key with elliptic curve secp521r1.

zkey kms configure --gen-identity-key ECC:secp521r1

zkey kms configure --gen-csr ... --cert-subject ...

Generates a certificate signing request with the identity key and the specified subject name and stores it in file 'csr.pem'.

zkey kms configure --gen-csr csr.pem --cert-subject "CN=my.zkey.client;OU=Example;C=US"

zkey kms configure --gen-csr csr.pem --renew-cert cert.pem

Generates a certificate signing request with the identity key to renew the existing certificate in file cert.pem and stores it in file 'csr.pem'.

zkey kms configure --gen-csr csr.pem --renew-cert cert.pem

zkey kms configure --gen-self-signed-cert ... --cert-validity-days 50

Generates a self-signed certificate with the identity key and the specified subject name and a validity of 50 days, and stores it in file 'cert.pem'.

zkey kms configure --gen-self-signed-cert cert.pem --cert-subject "CN=my.zkey.client;OU=Example;C=US" --cert-validity-days 50

zkey kms configure --gen-self-signed-cert ... --cert-extensions ...

Generates a self-signed certificate with the identity key and the specified subject name and a certificate extension to limit the key usage, and stores it in file 'cert.pem'.

zkey kms configure --gen-self-signed-cert cert.pem --cert-subject "CN=my.zkey.client;OU=Example;C=US" --cert-extensions "keyUsage=critical,digitalSignature,keyAgreement"

zkey kms configure --client-cert cert.pem

Use the CA-signed client certificate in file 'cert.pem' with the KMIP plugin.

zkey kms configure --client-cert cert.pem

zkey kms configure --kmip-server my.kmip.server

Configures the connection to the KMIP server on 'my.kmip.server'.

zkey kms configure --kmip-server my.kmip.server

zkey kms configure --kmip-server https://my.kmip.server/kmip

Configures the connection to the KMIP server on 'my.kmip.server' using HTTPS transport.

zkey kms configure --kmip-server https://my.kmip.server/kmip

zkey kms configure --kmip-server my.kmip.server --profile ABC

Configures the connection to the KMIP server on 'my.kmip.server' and use the KMIP plugin profile 'ABC'.

zkey kms configure --kmip-server my.kmip.server --profile ABC

zkey kms configure ... --tls-pin-server-pubkey --tls-verify-hostname

Configures the connection to the KMIP server on 'my.kmip.server' and pins the server's public key from the server's TLS certificate as well as enables verification of the host name to match the server's Common Name in the certificate.

zkey kms configure --kmip-server my.kmip.server --tls-pin-server-pubkey --tls-verify-hostname

zkey kms info

Displays information about the KMIP plugin and its configuration.

zkey kms info

zkey kms reencipher --staged

Reenciphers the KMIP Plugin's identity key with a new master key in staged mode

zkey kms reencipher --staged

zkey generate --name seckey --volumes /dev/dasdc1:encvol --label TEST

Generates a secure AES key in the KMIP server using the label 'TEST' and stores it in the secure key repository using the name 'seckey' and associates it with block device '/dev/dasdc1' and device-mapper name 'encvol'.

zkey generate --name seckey --volumes /dev/dasdc1:encvol --label TEST

zkey generate ... --xts --volume-type luks2 --label TEST1:TEST2

Generates a secure AES key for the XTS cipher mode in the KMIP server using the labels 'TEST1' and 'TEST2' and stores it in the secure key repository using the name 'seckey' and associates it with block device '/dev/dasdc1' and device-mapper name 'encvol', and a volume type of luks2.

zkey generate --name seckey --xts --volumes /dev/dasdc1:encvol --volume-type luks2 --label TEST1:TEST2

zkey remove --name seckey --state DEACTIVATED

Removes secure key 'seckey' from the repository and sets the state of the key to 'DEACTIVATED' in the KMIP server.

zkey remove --name seckey --state DEACTIVATED

zkey kms list

Displays eligible secure keys managed by KMIP server.

zkey kms list

zkey kms list --label "*LUKS2*"

Displays eligible secure keys managed by the KMIP server where the label name in the KMIP server contains the word 'LUKS2'.

zkey kms list --label "*LUKS2*"

zkey kms import --name seckey

Imports the secure key managed by the KMIP server with a zkey name of 'seckey'.

zkey kms import --name seckey

zkey kms import --volume-type LUKS2

Imports secure keys managed by the KMIP server that are associated with volumes of volume type LUKS2.

zkey kms import --volume-type LUKS2

zkey kms refresh --name "sec*"

Refreshes secure keys from the KMIP server where the name starts with 'sec'.

zkey kms refresh --name "sec*"

zkey kms refresh --name seckey --refresh-properties

Refreshes the secure key with the name 'seckey' from the KMIP server and also refreshes the key properties.

zkey kms refresh --name seckey --refresh-properties

🌸 ENVIRONMENT 🌸

  • ZKEY_KMIP_PROFILES — If $ZKEY_KMIP_PROFILES is set, it specifies the location of the KMIP plugin profiles. If it is not set, then the default location of the KMIP plugin profiles is /etc/zkey/kmip/profiles.

okay that's the whole page bestie, you're officially a KMIP plugin main character now 👑 this was s390-tools, June 2021 vintage — iconic, timeless, still slaying. mwah 💖🎀

📦 where this page comes from