How to find keys in HSM - Key Management Service - Alibaba Cloud Documentation Center

Use findKey to search for keys in a Hardware Security Module (HSM) by key attributes and retrieve their key handles for use in subsequent operations.

findKey is scoped to the current user — it returns only keys the user owns or keys that have been shared with them.

Prerequisites

Before you begin, ensure that you have:

Started key_mgmt_tool
Logged in to HSM as a Crypto User (CU)

Syntax

findKey [-c <key class>]
        [-t <key type>]
        [-l <key label>]
        [-id <key ID>]
        [-sess (0 | 1)]
        [-u <user-ids>]
        [-m <modulus>]
        [-kcv <key_check_value>]

Important

Enter parameters in the order shown above.

All parameters are optional. Running findKey with no parameters returns all keys accessible to the current user.

Parameters

Parameter	Description	Valid values
`-t`	Key type	`0`: RSA, `1`: DSA, `3`: EC, `16`: GENERIC_SECRET, `18`: RC4, `21`: Triple DES (3DES), `31`: AES
`-c`	Key class	`2`: Public key, `3`: Private key, `4`: Symmetric key
`-l`	Key label	Any string
`-id`	Key ID	Any string
`-sess`	Key persistence	`1`: Session keys, `0`: Persistent keys
`-u`	User ID of the key owner or a user with shared access. To filter by multiple users, separate IDs with commas.	Any valid user ID
`-m`	Path to the hex file containing the RSA modulus. Use this to find RSA keys by the modulus they were created with.	File path
`-kcv`	Key Check Value (KCV) of the key. For additional information on KCV, see Key Check Value.	Hex string

Examples

Find all accessible keys

Running findKey with no parameters returns all keys the current user can access.

Command:  findKey

Find persistent AES keys shared with a specific user

This command finds persistent AES keys (-t 31 -sess 0) that are accessible to user 3.

Command:  findKey -t 31 -sess 0 -u 3

Find public keys by label

This command finds all public keys with the label 2024-audit.

Command:  findKey -c 2 -l 2024-audit

Find RSA keys by modulus

This command finds RSA keys created with the modulus stored in m4.txt.

Command:  findKey -t 0 -m m4.txt

Output

findKey returns the total number of keys found and their key handles. Use the key handles in subsequent commands such as getAttribute or getKeyInfo.

Command:  findKey

           	Total number of keys present: 4

           	Number of matching keys from start index 0::3

           	Handles of matching keys:
           	6, 7, 8, 9

           	Cluster Status:
           	Node id 0 status: 0x00000000 : HSM Return: SUCCESS

           	Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS

In this example, the matching key handles are 6, 7, 8, and 9. HSM Return: SUCCESS confirms the operation completed without errors.

What's next

Use getAttribute to inspect the properties of a key by its handle.
Use getKeyInfo to check the ownership and sharing status of a key.