YubiHSM Command Reference
This section contains a list of the commands supported by the YubiHSM 2.
Important
The YubiHSM 2 is certified at FIPS 140-2 Level 3 .
The low-level format for each command message and the relative response is provided, together with an example of how that command can be used within the yubihsm-shell.
OPEN SESSION Command
This command is the combination of sending two commands in sequence to the YubiHSM:
- The command to create a session
- The command to authenticate the session
The user of yubihsm-shell does not need to run these commands separately as that is taken care of by the session open command that uses those two commands behind the scenes.
Opens an authenticated session to the device. Subsequent commands can be communicated to the device over this authenticated session.
Interactive Mode
yubihsm> session open w:authkey, i:password=-
Parameters
authkey Required.
Authentication key object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
password
The password used to authenticate the session. The password is prompted for if not specified.
Example
Create a new session with Authentication Key 1 using the password password. This does both the session creation and authentication steps.
yubihsm> session open 1 password
Created session 0
Command Line Mode
A session is automatically created when executing yubihsm-shell commands on the command line.
AUTHENTICATE SESSION Command
Complete the mutual authentication process started with CREATE SESSION Command.
Finish the Session negotiation and authenticate the Session to the device. After this command completes successfully the Session is authenticated and can be used.
Shell Example
Create a new Session with Authentication Key 1 using the password password, this performs both the creation and authentication steps.
yubihsm> session open 1 password
Created session 0
Protocol Details
Command
Tc = 0x04
Lc = 17
Vc = S || B || M
where –
S = Session ID (1 byte)
B = Host Cryptogram (8 bytes)
M = CMAC(S-MAC, 016 || T || Lc + 8 || S || B) (8 bytes)
This is the first authenticated message in the chain.
The device verifies M and B, both using S-MAC.
Response
Tr = 0x84
Lr = 0
Vr = Ø
OPEN SESSION ASYMMETRIC Command
Available with firmware version 2.3.1 or later.
Opens an authenticated session to the device using an asymmetric key. The YubiHSM2 and a client should have exchanged public keys earlier. The asymmetric keys are created from the curve EC-P256.
A session opened with an asymmetric authentication key does not need to be authenticated separately. The command is immediately usable if the CREATE SESSION command is successful.
Subsequent commands can be communicated to the device over this authenticated session.
Interactive Mode
yubihsm> open_asym w:authkey,i:privkey=-
Parameters
authkey Required.
ObjectID of the asymmetric authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal
privkey Required.
The private key to open the session with
Possible Values: Password, path to file or “-“ for stdin
Default format: PEM
Example
Create a new session with Authentication Key 100 using a private key stored in `priv.key. This does both the session creation and authentication steps.
yubihsm> session open_asym 100 priv.key
Created session 0
Command Line Mode
Asymmetric authentication keys cannot be used in command line mode.
Protocol Details
Command
Tc = 0x03
Lc = 67
Vc = I || K
Where –
I = Key ID of an asymmetric authentication key (2 bytes)
K = Ephemeral client public key (65 bytes)
On success the device generates a Session ID S (1 byte) and sets the message counter for the current Session to 1.
The error ERROR_INV_DATA if K is not a valid EC-P256 key.
Response
Tr = 0x83
Lr = 82
Vr = S || Kd || R
Where –
S = Session ID (1 bytes)
Kd = Ephemeral device public key (65 bytes)
R = Recipient (16 bytes)
BLINK DEVICE Command
Blink the LED of the device to identify it.
This device must be sent over an authenticated session.
Interactive Mode
yubihsm> blink e:session, b:seconds=10
Parameters
seconds
Number of seconds to blink.
Default Value: 10
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Command Line Mode
$ yubihsm-shell -a blink-device [ --authkey <authKeyID> -p <password> --duration <duration> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
–duration=INT
Number of seconds to blink.
Default Value: 10
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
CHANGE ASYMMETRIC AUTHENTICATION KEY Command
Available with firmware version 2.3.1 or later.
Replace the Asymmetric Authentication Key used to establish the current Session. It is not possible to modify any of the metadata connected to the Object such as Domains or Capabilities. Only the public key will be modified.
This command must be sent over an authenticated session.
Interactive Mode
yubihsm> change authkey_asym e:session,w:key_id,i:pubkey=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
ObjectID of the authentication key used to open the current session and whose public key will be changed. Object ID is a 2 bytes integer. Can be specified in hex or decimal
pubkey
The new public key.
- When using stdin, click CTRL-D to mark end of input.
- Input format for a password string is
password.- If
passwordformat is used, the tool will derive an ec-p256 private key from the input string and calculate the public key from that. The private key is not used for anything else.Possible Values: File containing the client’s public key as an uncompressed ec-p256 public key,
passwordor-for stdinDefault Value: stdin
Possible Format for public key file: PEM, HEX, binary
Default format: PEM
Example
Change the current Asymmetric Authentication Key to newkey.pub:
yubihsm> change authkey_asym 0 100 newkey.pub
Changed Authentication key 0x0064
Command Line Mode
This command is not available in command line mode.
Protocol Details
Command
Tc = 0x6c
Lc = 2 + 1 + 16 + 16
Vc = I || A || Key
Replace the currently used Authentication Key with a new set of keys.
Where –
I = Object ID of the Authentication Key (2 bytes)
A = ALGORITHMS (1 byte) (ec-p256-yubico-authentication = 0x31)
Key = Uncompressed EC-P256 public key (64 bytes)
CHANGE AUTHENTICATION KEY Command
Available with firmware version 2.2.0 or later.
Replace the Authentication Key used to establish the current Session. It is not possible to modify any of the metadata connected to the Object such as Domains or Capabilities. Only the payload data of the Object (for example, the long-lived symmetric keys) will be modified.
The same PBKDF2 derivation scheme described in Session is available.
This device must be sent over an authenticated session.
Shell Example
Change the current Authentication Key deriving it from the password newpassword.
yubihsm> change authkey 0 1 newpassword
Changed Authentication key 0x0001
Interactive Mode
yubihsm> change authkey e:session, w:key_id, i:password=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
The ObjectID of the authentication key used to open the current session and whose password will be changed. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
password
The new password for
key_id. The password is prompted for if not specified.
Example
Change the current Authentication Key deriving it from the password newpassword.
yubihsm> change authkey 0 1 newpassword
Changed Authentication key 0x0001
Command Line Mode
This command is not available in command line mode.
Protocol Details
Command
Tc = 0x6c
Lc = 2 + 1 + 16 + 16
Vc = I || A || Ke || Km
Replace the currently used Authentication Key with a new set of keys.
where –
I = Object ID of the Authentication Key (2 bytes)
A = ALGORITHMS (1 byte)
Ke = Encryption Key (16 bytes)
Km = Mac Key (16 bytes)
CLOSE SESSION Command
Close the current Session and release it for re-use. This device must be sent over an authenticated session.
Interactive Mode
yubihsm> session close e:session
Parameters
session Required.
The ID of the session to close.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Command Line Mode
This command does not need to be run separately on the command line. The session will automatically close after the command has been executed.
CREATE OTP AEAD Command
Create a Yubico OTP AEAD using the provided data. This device must be sent over an authenticated session.
Shell Example
Create a new AEAD using Otp-aead Key 0x027c with the key 000102030405060708090a0b0c0d0e0f and private ID 010203040506. Store the result in the file aead.
yubihsm> otp aead_create 0 0x027c 000102030405060708090a0b0c0d0e0f 010203040506 aead
Interactive Mode
yubihsm> otp aead_create e:session, w:key_id, i:key, i:private_id, F:aead
Parameters
aead Required.
The file to store the Yubico OTP AEAD.
Default input format: hex
key Required.
The key used to create the Yubico OTP AEAD.
key_id Required.
OTP AEAD key object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
private_id Required.
The private ID used to create the Yubico OTP AEAD.
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Example
Create a new AEAD using Otp-aead Key 0x027c with the key 000102030405060708090a0b0c0d0e0f and private ID 010203040506. Store the result in the file aead.
yubihsm> otp aead_create 0 0x027c 000102030405060708090a0b0c0d0e0f 010203040506 aead
Command Line Mode
This command is not available in command line mode.
CREATE SESSION Command
Begin the mutual authentication process for establishing a Session.
Start negotiating a Session with the device. This command tells the device which Authentication Key to use and sends the host challenge part. The response contains the device challenge and device authentication part. To establish the session continue with AUTHENTICATE SESSION Command.
Shell Example
Create a new session with Authentication Key 1 using the password password. This does both the session creation and authentication steps.
yubihsm> session open 1 password
Created session 0
Protocol Details
Command
Tc = 0x03
Lc = 10
Vc = I || H
where –
I = Key set ID (2 bytes)
H = Host Challenge (8 bytes)
The device generates a random Card Challenge C (8 bytes).
The device derives three Session Keys (S-ENC, S-MAC and S-RMAC) starting from the set of two static keys identified by I (K-ENC and K-MAC) and the two challenges H and C, using the same procedure described in SCP03.
The device uses S-MAC together with H and C to compute the Card Cryptogram A. The host will compute the Host Cryptogram B after having received C and derived S-MAC.
On success the device generates a Session ID S (1 byte) and sets the message counter for the current Session to 1.
Response
Tr = 0x83
Lr = 17
Vr = S || C || A
DECRYPT CBC Command
Available with firmware version 2.3.1 or later.
Decrypt data in CBC mode.
Interactive Mode
yubihsm> decrypt aescbc e:session,w:key_id,s:iv,i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID of the symmetric key to decrypt with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
iv Required.
Encryption initialization vector. 16 bytes in HEX format.
data
Data to decrypt. When using stdin, the end of input is marked with CTRL-D.
Possible Values: Data or “-” for stdin
Default Value: stdin
Input format: PEM
Output format: HEX
Example
Decrypt data using key 0x0064:
yubihsm> decrypt aescbc 0 0x0064 00000000000000000000000000000000 SG0OU4CT2pH2dnd967KyTU5OgdJ8edxJjOf3Yt52gGQ=
c5cffa1c2333fd824a86951cf602bca1
Command Line Mode
$ yubihsm-shell -a decrypt-aescbc -i <key_id> --iv <iv> [--in <data> --out <out> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password will be prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the symmetric key to decrypt with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–iv=STRING Required.
Encryption initialization vector. 16 bytes in HEX format.
–in=STRING
Data to decrypt. Multiple of 16 bytes. When using stdin, the end of input is marked with CTRL-D.
Possible Values: data or stdin
Default Value: stdin
Input format: Binary
–out=STRING
Decrypted data.
Possible Valued: Path to file or stdout
Default Value: stdout
Output format: HEX
Example
Decrypt data using key 0x0064:
$ yubihsm-shell -a decrypt-aescbc -i 0x0064 --iv 00000000000000000000000000000000 --in data.enc
c5cffa1c2333fd824a86951cf602bca1
DECRYPT ECB Command
Available with firmware version 2.3.1 or later.
Decrypt data in ECB mode.
Interactive Mode
yubihsm> decrypt aesecb e:session,w:key_id,i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID of the symmetric key to decrypt with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
data
Data to decrypt. When using stdin, the end of input is marked with CTRL-D.
Possible Values: Data to sign or “-” for stdin
Default Value: stdin
Input format: PEM
Output format: HEX
Example
Decrypt data using key 0x0064:
yubihsm> decrypt aesecb 0 0x0064 SG0OU4CT2pH2dnd967KyTQSIdJILAhWsmhdFIkHAZMQ=
c5cffa1c2333fd824a86951cf602bca1
Command Line Mode
$ yubihsm-shell -a decrypt-aesecb -i <key_id> [--in <data> --out <out> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password will be prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the symmetric key to decrypt with. Object ID is a 2 bytes integer. Can be specified in hex or decimal
–in=STRING
Data to decrypt. Multiple of 16 bytes. When using stdin, the end of input is marked with CTRL-D.
Possible Values: data or stdin
Default Value: stdin
Input format: Binary
–out=STRING
Decrypted dat.
Possible Values: Path to file or stdout
Default Value: stdout
Output format: HEX
Example
Decrypt data using key 0x0064:
$ yubihsm-shell -a decrypt-aesecb -i 0x0064 --in data.enc
c5cffa1c2333fd824a86951cf602bca1
DECRYPT OAEP Command
Decrypt data encrypted with RSA-OAEP.
Example
Decrypt data stored in file enc using key 0x79c3:
yubihsm> decrypt oaep 0 0x79c3 rsa-oaep-sha1 enc
xlwIc7yQf/KkV5v4Y87Q9ZSqLReoNAxlCmmMPA4W08U=
Protocol Details
Command
T~c~ = 0x59
L~c~ = 2 + 1 + L~D~ + L~H~
V~c~ = I \|\| M \|\| D \|\| H~l~
Where –
I = link:../Concepts/Object_ID.adoc[Object ID] of the Asymmetric Key (2 bytes)
M = Hash link:../Concepts/Algorithms.adoc[Algorithm] to use for MGF1 (1 byte)
D = Decryption data (256, 384 or 512 bytes)
H~l~ = Hash of OAEP Label (20, 32, 48 or 64 bytes)
DECRYPT OTP Command
Decrypt a Yubico OTP and return counters and timer information.
Shell Example
Decrypt a (hex encoded) Yubico OTP using key ID 0x027c.
yubihsm> otp decrypt 0 0x027c 2f5d71a4915dec304aa13ccf97bb0dbb aead
OTP decoded, useCtr:1, sessionCtr:1, tstph:1, tstpl:1
Interactive Mode
yubihsm> otp decrypt e:session, w:key_id, s:otp, i:aead
Parameters
aead Required.
Nonce concatenated with AEAD (36 bytes).
Possible Values: Path to file containing the AEAD
Default format: binary
key_id Required.
OTP AEAD key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
otp Required.
OTP to decrypt.
Possible Values: rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384, rsa-oaep-sha512
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Example
Decrypt a (hex encoded) Yubico OTP using key ID 0x027c.
yubihsm> otp decrypt 0 0x027c 2f5d71a4915dec304aa13ccf97bb0dbb aead
OTP decoded, useCtr:1, sessionCtr:1, tstph:1, tstpl:1
Command Line Mode
This command is not available in command line mode.
Protocol Details
Command
Tc = 0x60
Lc = 2 + 36 + 16
Vc = K || A || O
where –
I = Object ID of the OTP AEAD Key (2 bytes)
A = Nonce concatenated with AEAD (36 bytes)
O = OTP (16 bytes)
Response
Tr = 0xe0
Lr = 6
Vr = S || U || Th || Tl
where –
S = Session counter (2 bytes)
U = Usage counter (1 byte)
Th = Timestamp high (1 byte)
Tl = Timestamp low (2 bytes)
DECRYPT PKCS1 Command
Decrypt data encrypted with RSA-PKCS#1v1.5.
Shell Example
Decrypt the file enc using key 0xa930.
yubihsm> decrypt pkcs1v1_5 0 0xa930 enc xlwIc7yQf/KkV5v4Y87Q9ZSqLReoNAxlCmmMPA4W08U=
Interactive Mode
yubihsm> decrypt pkcs1v1_5 e:session, w:key_id, i:data=-
Parameters
data
Input data to decrypt.
Possible Values: Path to file or ‘-’ for stdin
Default Value: stdin
Default data format: binary
key_id Required.
RSA key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Example
Decrypt the file enc using key 0xa930.
yubihsm> decrypt pkcs1v1_5 0 0xa930 enc xlwIc7yQf/KkV5v4Y87Q9ZSqLReoNAxlCmmMPA4W08U=
Command Line Mode
$ yubihsm-shell -a decrypt-pkcs1v15 -i <key_id> [ --authkey <authKeyID> -p <password> --in <data> --out <out_data> --informat <data_format> --outformat <outdata_format> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-i, –object-id=SHORT Required.
Object ID or an RSA key. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–in=STRING
Data to decrypt.
Possible Values: Path to file or stdin
Default Value: stdin
Default data format: binary
–informat=ENUM
Input data format.
Possible Values: base64, binary, PEM, hex
–out=STRING
Decrypted data.
Possible Values: Path to file or stdout
Default Value: stdout
Default data format: binary
–outformat=ENUM
Output data format.
Possible Values: base64, binary, PEM, hex
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
Example
Decrypt data stored in file enc using key 0x79c3.
$ yubihsm-shell -a decrypt-pkcs1v15 -i 0x79c3 --in enc xlwIc7yQf/KkV5v4Y87Q9ZSqLReoNAxlCmmMPA4W08U=
Protocol Details
Command
Tc = 0x49
Lc = 2 + LD
Vc = I || D
where –
I = Object ID of the Asymmetric Key (2 bytes)
D = Decryption data (256, 384 or 512 bytes)
The data is padded using the PKCS#1v1.5 scheme with Block Type 2. The data is decrypted and conformance to the padding scheme must be checked. Padding is then removed and the contained message is returned.
DELETE OBJECT Command
Delete an Object in the device.
Interactive Mode
yubihsm> delete e:session, w:id, t:type
Parameters
id Required.
Object ID of the object to delete. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
type Required.
Type of the object to delete.
Possible Values: asymmetric-key, authentication-key, hmac-key, opaque, otp-aead-key, template, wrap-key
Command Line Mode
$ yubihsm-shell -a delete-object -i <id> -t <type> [ --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-i, –object-id=SHORT Required.
Object ID of the object to delete. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-t, –object-type=STRING Required.
Type of the object to delete.
Posssible Values: asymmetric-key, authentication-key, hmac-key, opaque, otp-aead-key, template, wrap-key
DERIVE ECDH Command
Perform an ECDH key exchange with the private key in the device.
Shell Example
Perform an ECDH operation with key 0x52b6 and a public key in the file pubkey.pem.
yubihsm> derive ecdh 0 0x52b6 pubkey.pem
5898516bcb0cb3db89d53471137c2d1c741b8ba6ebf2bb01f4a62d97342e97b2
Interactive Mode
yubihsm> derive ecdh e:session, w:key_id, i:pubkey=-
Parameters
key_id Required.
Object ID of an EC key. Object ID is a 2 bytes integer. Can be specified in hex or decimal
pubkey
The public key of another EC key.
Possible Values: Path to file or ‘-’ for stdin
Default Value: stdin
Default data format: PEM
session Required.
The ID of the authenticated session to send the command over.
Possbile Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Example
Perform an ECDH operation with key 0x52b6 and a public key in the file pubkey.pem.
yubihsm> derive ecdh 0 0x52b6 pubkey.pem
5898516bcb0cb3db89d53471137c2d1c741b8ba6ebf2bb01f4a62d97342e97b2
Command Line Mode
$ yubihsm-shell -a derive-ecdh -i <key_id> [ --authkey <authKeyID> -p <password> --in <pubkey> --out <ecdh> --informat <pubkey_format> --outformat <ecdh_format> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-i, –object-id=SHORT Required.
EC key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–in=STRING
The public key of another EC key.
Possible Values: Path to file or stdin
Default Value: stdin
Default Data Format: PEM
–informat=ENUM
Format of public key.
Possible Values: base64, binary, PEM, hex
Default Value: PEM
–out=STRING
ECDH key.
Possible Values: Path to file or stdout
Default Value: stdout
Default Data Format: PEM
–outformat=ENUM
Format of ECDH key.
Possible Values: base64, binary, PEM, hex
Default Value: PEM
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
Example
Perform an ECDH operation with key 0x52b6 and a public key in the file pubkey.pem.
$ yubihsm-shell -a derive-ecdh -i 0x52b6 --in pubkey.pem
5898516bcb0cb3db89d53471137c2d1c741b8ba6ebf2bb01f4a62d97342e97b2
DEVICE INFO Command
Gets device version, device serial, supported ALGORITHMS and available log entries.
Shell Example
Fetch device info for currently connected device. In YubiHSM with firmware version 2.4 and above, the device info
also return Part numer which is required by FIPS.
yubihsm> get deviceinfo
Version number: 2.0.0
Serial number: 2000000
Log used: 2/62
Supported algorithms: rsa-pkcs1-sha1, rsa-pkcs1-sha256, rsa-pkcs1-sha384,
rsa-pkcs1-sha512, rsa-pss-sha1, rsa-pss-sha256,
rsa-pss-sha384, rsa-pss-sha512, rsa2048,
rsa3072, rsa4096, ecp256, ecp384, ecp521, eck256,
ecbp256, ecbp384, ecbp512, hmac-sha1, hmac-sha256,
hmac-sha384, hmac-sha512, ecdsa-sha1, ecdh,
rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384,
rsa-oaep-sha512, aes128-ccm-wrap, opaque-data,
opaque-x509-certificate, mgf1-sha1, mgf1-sha256,
mgf1-sha384, mgf1-sha512, template-ssh,
aes128-yubico-otp, aes128-yubico-authentication,
aes192-yubico-otp, aes256-yubico-otp,
aes192-ccm-wrap, aes256-ccm-wrap,
ecdsa-sha256, ecdsa-sha384, ecdsa-sha512,
ed25519, ecp224,
Part number: 78CLUFX5000P
Interactive Mode
yubihsm> get deviceinfo
Example
Fetch device info for currently connected device.
yubihsm> get deviceinfo
Version number: 2.0.0
Serial number: 2000000
Log used: 2/62
Supported algorithms: rsa-pkcs1-sha1, rsa-pkcs1-sha256, rsa-pkcs1-sha384,
rsa-pkcs1-sha512, rsa-pss-sha1, rsa-pss-sha256,
rsa-pss-sha384, rsa-pss-sha512, rsa2048,
rsa3072, rsa4096, ecp256,
ecp384, ecp521, eck256,
ecbp256, ecbp384, ecbp512,
hmac-sha1, hmac-sha256, hmac-sha384,
hmac-sha512, ecdsa-sha1, ecdh,
rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384,
rsa-oaep-sha512, aes128-ccm-wrap, opaque-data,
opaque-x509-certificate, mgf1-sha1, mgf1-sha256,
mgf1-sha384, mgf1-sha512, template-ssh,
aes128-yubico-otp, aes128-yubico-authentication,
aes192-yubico-otp, aes256-yubico-otp, aes192-ccm-wrap,
aes256-ccm-wrap, ecdsa-sha256, ecdsa-sha384,
ecdsa-sha512, ed25519, ecp224
Command Line Mode
$ yubihsm-shell -a get-device-info
Example
Fetch device info for currently connected device.
$ yubihsm-shell -a get-device-info
Version number: 2.0.0
Serial number: 2000000
Log used: 2/62
Supported algorithms: rsa-pkcs1-sha1, rsa-pkcs1-sha256, rsa-pkcs1-sha384,
rsa-pkcs1-sha512, rsa-pss-sha1, rsa-pss-sha256,
rsa-pss-sha384, rsa-pss-sha512, rsa2048, rsa3072,
rsa4096, ecp256, ecp384, ecp521, eck256,
ecbp256, ecbp384, ecbp512,
hmac-sha1, hmac-sha256, hmac-sha384,
hmac-sha512, ecdsa-sha1, ecdh,
rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384,
rsa-oaep-sha512, aes128-ccm-wrap, opaque-data,
opaque-x509-certificate, mgf1-sha1, mgf1-sha256,
mgf1-sha384, mgf1-sha512, template-ssh,
aes128-yubico-otp, aes128-yubico-authentication,
aes192-yubico-otp, aes256-yubico-otp, aes192-ccm-wrap,
aes256-ccm-wrap, ecdsa-sha256, ecdsa-sha384,
ecdsa-sha512, ed25519, ecp224
Protocol Details
Command
Tc = 0x06
Lc = /{ LI /}
Vc = /{ I /}
where –
I = Page index, can only be 0 = general device info or 1 = part number. Optional and is only available with firmware 2.4 or higher (1 byte)
Response
Unspecified or page index 0:
Tr = 0x86
Lr = 9 + algorithms
Vr = VMajor || VMinor || VBuild || S || Ltotal || Lused || A
where –
VMajor = Major version number (1 byte)
VMinor = Minor version number (1 byte)
VBuild = Build version number (1 byte)
S = Serial number (4 bytes)
Ltotal = Log Store size expressed in number of log entries (1 byte)
Lused = Log lines used (1 byte)
A = List of supported ALGORITHMS
Page index 1:
Tr = 0x86
Lr = 13
Vr = P
where –
P = Part number (13 byte)
ECHO Command
Return the byte sequence present within the data field, without any modification. Can be sent over an encrypted Session or as a bare command.
Shell Example
Plain echo
yubihsm> plain echo 0x3c 10
Response (10 bytes):
3c3c3c3c3c3c3c3c 3c3c
Echo over session 0
yubihsm> echo 0 0x3c 10
Response (10 bytes):
3c3c3c3c3c3c3c3c 3c3c
Interactive Mode
Over Encrypted Session
yubihsm> echo e:session, b:byte, w:count
Bare Command
yubihsm> plain echo b:byte, w:count
Parameters
byte Required.
The byte to be echoed.
count Required.
How many times the byte will be echoed.
session
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Example
Echo over session 0
yubihsm> echo 0 0x3c 10
Response (10 bytes):
33c3c3c3c3c3c3c3c 3c3c
Plain echo
yubihsm> plain echo 0x3c 10
Response (10 bytes):
3c3c3c3c3c3c3c3c 3c3c
Command Line Mode
This command is not available in command line mode.
ENCRYPT CBC Command
Available with firmware version 2.3.1 or later.
Encrypt data in CBC mode.
Interactive Mode
yubihsm> encrypt aescbc e:session,w:key_id,s:iv,i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID of the symmetric key to encrypt with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
iv Required.
Encryption initialization vector. 16 bytes in HEX format.
data
Data to encrypt. Multiple of 16 bytes. When using stdin, the end of input is marked with CTRL-D.
Possible Values: Data or “-” for stdin
Default Value: stdin
Input format: HEX
Output format: PEM
Example
Encrypt data using key 0x008c:
yubihsm> encrypt aescbc 0 0x008c 00000000000000000000000000000000 c5cffa1c2333fd824a86951cf602bca1
SG0OU4CT2pH2dnd967KyTU5OgdJ8edxJjOf3Yt52gGQ=
Command Line Mode
$ yubihsm-shell -a encrypt-aescbc -i <key_id> --iv <iv> [--in <data> --out <out> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password will be prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the symmetric key to encrypt with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–iv=STRING Required.
Encryption initialization vector. 16 bytes in HEX format
–in=STRING
Data to encrypt. Multiple of 16 bytes. When using stdin, the end of input is marked with CTRL-D.
Possible Values: data or stdin
Default Value: stdin
Input format: HEX
–out=STRING
Encrypted data.
Possible Values: Path to file or stdout
Default Value: stdout
Output format: Binary
Example
Encrypt data using key 0x008c:
$ yubihsm-shell -a encrypt-aescbc -i 0x008c --in c5cffa1c2333fd824a86951cf602bca1 --out data.enc
ENCRYPT ECB Command
Available with firmware version 2.3.1 or later.
Encrypt data in ECB mode.
Interactive Mode
yubihsm> encrypt aesecb e:session,w:key_id,i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID of the symmetric key to encrypt with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
data
Data to encrypt. Multiple of 16 bytes. When using stdin, the end of input is marked with CTRL-D.
Possible Values: Data to sign or “-” for stdin
Default Value: stdin
Input format: HEX
Output format: PEM
Example
Encrypt data using key 0x0064:
yubihsm> encrypt aesecb 0 0x0064 c5cffa1c2333fd824a86951cf602bca1 SG0OU4CT2pH2dnd967KyTQSIdJILAhWsmhdFIkHAZMQ=
Command Line Mode
$ yubihsm-shell -a encrypt-aesecb -i <key_id> [--in <data> --out <out> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password will be prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the symmetric key to encrypt with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–in=STRING
Data to encrypt. Multiple of 16 bytes. When using stdin, the end of input is marked with CTRL-D.
Possible Values: data or stdin
Default Value: stdin
Input format: HEX
–out=STRING
Encrypted data.
Possible Value: Path to file or stdout
Default Value: stdout
Output format: Binary
Example
Encrypt data using key 0x0064:
$ yubihsm-shell -a encrypt-aesecb -i 0x0064 --in c5cffa1c2333fd824a86951cf602bca1 --out data.enc
EXPORT WRAPPED Command
Retrieves an Object under wrap from the device. The Object is encrypted using AES-CCM with a 16 bytes MAC and a 13 bytes nonce.
Both the Wrap Key and the Authentication Key must have the capability export-wrapped and the wrapped object must have the capability exportable-under-wrap.
With YubiHSM devices with firmware version 2.4 or later, this command has been extended to be able to export ed25519 keys with the seed for the private key. To ensure backwards compatibility with older versions of the HSM, the default is to not export the seed. Importing such a legacy format will result in an all-zero seed if such a key is exported in the future.
Shell Example
Fetch the Asymmetric Key 0x997e encrypted with Wrap Key 0xcf94 and store the result in the file key.enc.
yubihsm> get wrapped 0 0xcf94 asymmetric-key 0x997e key.enc
Interactive Mode
$ yubihsm> get wrapped e:session, w:wrapkey_id, t:type, w:id, b:include_seed=0, F:file=-
Parameters
file
Encrypted/wrapped object.
Possible Values: Path to file or ‘-’ for stdin
Default Value: stdin
id Required.
Object ID of the object to be wrapped. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
include_seed
Export ED25519 key with its seed. Default is not to.
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
type Required.
Type of the object to be wrapped.
Possible Values: asymmetric-key, symmetric-key, authentication-key, hmac-key, opaque, otp-aead-key, template, wrap-key, public-wrap-key
wrapkey_id Required.
Wrap key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal
Example
Fetch the Asymmetric Key 0x997e encrypted with Wrap Key 0xcf94 and store the result in the file key.enc.
yubihsm> get wrapped 0 0xcf94 asymmetric-key 0x997e key.enc
Command Line Mode
$ yubihsm-shell -a get-wrapped --wrap-id <wrapkey_id> -t <type> -i <object_id> [ --include-seed --authkey <authKeyID> -p <password> --out <out_data> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-i, –object-id=SHORT Required.
Object ID of the object to be wrapped. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–include_seed
Export ED25519 key with its seed. Default is not to.
–out=STRING
Encrypted/wrapped object.
Possible Values: Path to file or stdout
Default Value: stdout
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified
-t, –object-type=STRING Required.
Type of the object to be wrapped.
Possible Values: symmetric-key, symmetric-key, authentication-key, hmac-key, opaque, otp-aead-key, template, wrap-key, public-wrap-key
–wrap-id=INT Required.
Wrap key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Example
Fetch the Asymmetric Key 0x997e encrypted with Wrap Key 0xcf94 and store the result in the file key.enc.
$ yubihsm-shell -a get-wrapped --wrap-id 0xcf94 -t symmetric-key -i 0x997e --out key.enc
EXPORT RSA WRAPPED Command
Available on YubiHSM devices with firmware version 2.4 or higher.
Both the Public Wrap Key and the Authentication Key must have the capability export-wrapped and the wrapped object must have the capability exportable-under-wrap.
Retrieves an Object under RSA wrap from the device. The wrapped object is serialized using the YubiHSM-internal format.
Interactive Mode
$ yubihsm> get rsa_wrapped e:session, w:wrapkey_id, t:type, w:id, a:aes=aes256, a:hash=rsa-oaep-sha256, mgf1=mgf1-sha256, F:file=-
Parameters
aes
Algorithm of the ephemeral AES key
Possible Values: aes128, aes192 or aes256
Default Value: aes256
file
Encrypted/wrapped object.
Possible Values: Path to file or ‘-’ for stdin
Default Value: stdout
Format: Binary
hash
Hash algorithm to use for OAEP label.
Possible Values: rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384 or rsa-oaep-sha512
Default Value: rsa-oaep-sha256
id Required.
Object ID of the object to be wrapped. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
mgf1
Hash algorithm to use for MGF1.
Possible Values: mgf1-sha1, mgf1-sha256, mgf1-sha384 or mgf1-sha512
Default Value: mgf1-sha256
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
type Required.
Type of the object to be wrapped.
Possible Values: asymmetric-key, symmetric-key, authentication-key, hmac-key, opaque, otp-aead-key, template, wrap-key, public-wrap-key
wrapkey_id Required.
Public Wrap Key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal
Example
Fetch the Asymmetric Key 0x997e encrypted with RSA Public Wrap Key 0xcf94 and store the result in the file object.enc.
$ yubihsm> get rsa_wrapped 0 0xcf94 asymmetric-key 0x997e aes192 rsa-oaep-sha384 mgf1-sha1 object.enc
Command Line Mode
$ yubihsm-shell -a get-rsa-wrapped --wrap-id <wrapkey_id> -t <type> -i <object_id> [ -A <aes> --oaep <oaep> --mgf1 <mgf1> --authkey <authKeyID> -p <password> --out <out_data> ]
Parameters
-A, –algorithm=STRING
Algorithm of the ephemeral AES key
Possible Values: aes128, aes192 or aes256
Default Value: aes256
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-i, –object-id=SHORT Required.
Object ID of the object to be wrapped. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–mgf1=STRING
Hash algorithm to use for MGF1.
Possible Values: mgf1-sha1, mgf1-sha256, mgf1-sha384 or mgf1-sha512
Default Value: mgf1-sha256
–oaep=STRING
Hash algorithm to use for OAEP label.
Possible Values: rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384 or rsa-oaep-sha512
Default Value: rsa-oaep-sha256
–out=STRING
Encrypted/wrapped object.
Possible Values: Path to file or stdout
Default Value: stdout
Format: Binary
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified
-t, –object-type=STRING Required.
Type of the object to be wrapped.
Possible Values: symmetric-key, symmetric-key, authentication-key, hmac-key, opaque, otp-aead-key, template, wrap-key, public-wrap-key
–wrap-id=INT Required.
Wrap key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Example
Fetch the Asymmetric Key 0x997e encrypted with Wrap Key 0xcf94 and store the result in the file object.enc.
$ yubihsm-shell -a get-rsa-wrapped --wrap-id 0xcf94 -t symmetric-key -i 0x997e -A aes192 --oaep rsa-oaep-sha384 --mgf1 mgf1-sha1 --out object.enc
Protocol Details
Command
Tc = 0x76
Lc = 2 + 1 + 2 + 1 + 1 + 1 + LHL
Vc = Iw || To || Ti || Ae || H || M || LH
where –
Iw= Object ID of Wrap Key to use (2 bytes)
To= Type, Objects of Object to wrap (1 byte)
Ti= Object ID of Object to wrap (2 bytes)
Ae= ALGORITHMS of the ephemeral AES key (1 byte)
H= ALGORITHMS to use for OAEP label (1 byte)
M= ALGORITHMS to use for MGF1 (1 byte)
LH= The label digest (Length dependent on OAEP algorithm)
EXPORT RSA WRAPPED KEY Command
Available on YubiHSM devices with firmware version 2.4 or higher.
Both the Public Wrap Key and the Authentication Key must have the capability export-wrapped and the wrapped object must have the capability exportable-under-wrap.
Wrap an (a)symmetric key. Only asymmetric and symmetric key objects are valid targets. Asymmetric keys are serialized as PKCS#8
Interactive Mode
$ yubihsm> get rsa_wrapped_key e:session, w:wrapkey_id, t:type, w:id, a:aes=aes256, a:hash=rsa-oaep-sha256, mgf1=mgf1-sha256, F:file=-
Parameters
aes
Algorithm of the ephemeral AES key
Possible Values: aes128, aes192 or aes256
Default Value: aes256
file
Encrypted/wrapped object.
Possible Values: Path to file or ‘-’ for stdin
Default Value: stdin
Format: Binary
hash
Hash algorithm to use for OAEP label.
Possible Values: rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384 or rsa-oaep-sha512
Default Value: rsa-oaep-sha256
id Required.
Object ID of the object to be wrapped. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
mgf1
Hash algorithm to use for MGF1.
Possible Values: mgf1-sha1, mgf1-sha256, mgf1-sha384 or mgf1-sha512
Default Value: mgf1-sha256
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
type Required.
Type of the object to be wrapped.
Possible Values: asymmetric-key, symmetric-key
wrapkey_id Required.
Wrap key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal
Example
Fetch the Asymmetric Key 0x997e encrypted with RSA Public Wrap Key 0xcf94 and store the result in the file key.enc.
$ yubihsm> get rsa_wrapped_key 0 0xcf94 asymmetric-key 0x997e aes192 rsa-oaep-sha384 mgf1-sha1 key.enc
Command Line Mode
$ yubihsm-shell -a get-rsa-wrapped-key --wrap-id <wrapkey_id> -t <type> -i <object_id> [ -A <aes> --oaep <oaep> --mgf1 <mgf1> --authkey <authKeyID> -p <password> --out <out_data> ]
Parameters
-A, –algorithm=STRING
Algorithm of the ephemeral AES key
Possible Values: aes128, aes192 or aes256
Default Value: aes256
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-i, –object-id=SHORT Required.
Object ID of the object to be wrapped. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–mgf1=STRING
Hash algorithm to use for MGF1.
Possible Values: mgf1-sha1, mgf1-sha256, mgf1-sha384 or mgf1-sha512
Default Value: mgf1-sha256
–oaep=STRING
Hash algorithm to use for OAEP label.
Possible Values: rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384 or rsa-oaep-sha512
Default Value: rsa-oaep-sha256
–out=STRING
Encrypted/wrapped object.
Possible Values: Path to file or stdout
Default Value: stdout
Format: Binary
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified
-t, –object-type=STRING Required.
Type of the object to be wrapped.
Possible Values: symmetric-key, symmetric-key
–wrap-id=INT Required.
Wrap key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Example
Fetch the Asymmetric Key 0x997e encrypted with Wrap Key 0xcf94 and store the result in the file key.enc.
$ yubihsm-shell -a get-rsa-wrapped-key --wrap-id 0xcf94 -t symmetric-key -i 0x997e -A aes192 --oaep rsa-oaep-sha384 --mgf1 mgf1-sha1 --out key.enc
Protocol Details
Command
Tc = 0x74
Lc = 2 + 1 + 2 + 1 + 1 + 1 + LHL
Vc = Iw || To || Ti || Ae || H || M || LH
where –
Iw= Object ID of Wrap Key to use (2 bytes)
To= Type, Objects of Object to wrap (1 byte)
Ti= Object ID of Object to wrap (2 bytes)
Ae= ALGORITHMS of the ephemeral AES key (1 byte)
H= ALGORITHMS to use for OAEP label (1 byte)
M= ALGORITHMS to use for MGF1 (1 byte)
LH= The label digest (Length dependent on OAEP algorithm)
GENERATE ASYMMETRIC KEY Command
Generate an Asymmetric Key in the device.
Shell Example
Generate a new key using secp256r1 in the device.
$ yubihsm> generate asymmetric 0 0 eckey 1 sign-ecdsa ecp256
Generated Asymmetric key 0x2846
Interactive Mode
$ yubihsm> generate asymmetric e:session, w:key_id, s:label, d:domains, c:capabilities, a:algorithm
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
label Required.
Key label. Can be empty.
Possible Value: Maximum of 40 characters string.
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, sign-pkcs, sign-pss, sign-ecdsa, sign-eddsa, decrypt-pkcs, decrypt-oaep, derive-ecdh, exportable-under-wrap, sign-ssh-certificate, sign-attestation-certificate
algorithm Required.
Key algorithm.
Possible Values: rsa2048, rsa3072, rsa4096, ecp256, ecp384, ecp521, eck256, ecbp256, ecbp384, ecbp512, ed25519, ecp224
Example
Generate a new key using secp256r1 in the device.
$ yubihsm> generate asymmetric 0 0 eckey 1 sign-ecdsa ecp256
Generated Asymmetric key 0x2846
Command Line Mode
$ yubihsm-shell -a generate-asymmetric-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> [--authkey <authKeyID> -p <password>]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING
Required. The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT
Required. Object ID of the asymmetric key. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-l, –label=STRING Required.
Key label Maximum of 40 characters string. Can be empty.
-d, –domains=STRING Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, sign-pkcs, sign-pss, sign-ecdsa, sign-eddsa, decrypt-pkcs, decrypt-oaep, derive-ecdh, exportable-under-wrap, sign-ssh-certificate, sign-attestation-certificate
-A, –algorithm=STRING Required.
Key algorithm.
Possible Values: rsa2048, rsa3072, rsa4096, ecp256, ecp384, ecp521, eck256, ecbp256, ecbp384, ecbp512, ed25519, ecp224
Example
Generate a new key using secp256r1 in the device.
$ yubihsm-shell -a generate-asymmetric-key -i 0 -l eckey -d 1 -c sign-ecdsa -A ecp256
Generated Asymmetric key 0x2846
Protocol Details
Command
Tc = 0x46
Lc = 2 + 40 + 2 + 8 + 1
Vc = I || L || D || C || A
Generate an Asymmetric key-pair with a given ID. Each parameter has a fixed length and the order is compulsory.
where –
I= Object ID of the Asymmetric Key (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Effective Capabilities (Tying It All Together) (8 bytes)
A= ALGORITHMS (1 byte)
GENERATE HMAC KEY Command
Generate an HMAC Key in the device.
Shell Example
Generate an HMAC-SHA512 key.
$ yubihsm> generate hmackey 0 0 hmackey 1 sign-hmac:verify-hmac hmac-sha512
Generated HMAC key 0xa9bf
Interactive Mode
$ yubihsm> generate hmackey e:session, w:key_id, s:label, d:domains, c:capabilities, a:algorithm
Parameters
session Required.
The ID of the authenticated session to send the command over. 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
label Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string.
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key.Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, sign-hmac, verify-hmac, exportable-under-wrap
Algorithm Required.
Key algorithm.
Possible Values: hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512
Example
Generate an HMAC-SHA512 key.
$ yubihsm> generate hmackey 0 0 hmackey 1 sign-hmac:verify-hmac hmac-sha512
Generated HMAC key 0xa9bf
Command Line Mode
$ yubihsm-shell -a generate-hmac-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> [--authkey <authKeyID> -p <password>]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-l, –label=STRING Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
-d, –domains=STRING Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, sign-hmac, verify-hmac, exportable-under-wrap
-A, –algorithm=STRING Required.
Key algorithm.
Possible Values: hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512
Example
Generate a new key using secp256r1 in the device:
$ yubihsm-shell -a generate-hmac-key -i 0 -l hmackey -d 1 -c sign-hmac,verify-hmac -A hmac-sha512
Generated HMAC key 0xa9bf
Protocol Details
Command
Tc = 0x5a
Lc = 2 + 40 + 2 + 8 + 1
Vr = I || L || D || C || A
where –
I= Object ID of the HMAC Key (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
GENERATE OTP AEAD KEY Command
Generate an OTP AEAD Key for Yubico OTP decryption.
Shell Example
Generate a new AES-256 OTP AEAD Key that can decrypt Yubico OTPs and create new AEADs.
$ yubihsm> generate otpaeadkey 0 0 otpaeadkey 1 decrypt-otp,
create-otp-aead aes256-yubico-otp 0x01020304
Generated OTP AEAD key 0x027c
Interactive Mode
$ yubihsm> generate hmackey e:session, w:key_id, s:label, d:domains, c:capabilities, a:algorithm, u:nonce_id
Parameters
session Required.
The ID of the authenticated session to send the command over.
Posible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.label Required.
Key label Maximum of 40 characters string. Can be empty
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16.
capabilities Required.
Capabilities of the key. Multiple capabilities can be separated by comma
,or colon:with no spaces between.Possible Values: none, create-otp-aead, decrypt-otp, randomize-otp-aead, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, exportable-under-wrap Use
noneto include no capability.algorithm Required.
Key algorithm. Multiple capabilities can be separated by comma
,or colon:with no spaces between.Possble Values: aes128-yubico-otp, aes192-yubico-otp, aes256-yubico-otp
nonce_id Required.
OTP nonce. 4 bytes
Example
Generate a new AES-256 OTP AEAD Key that can decrypt Yubico OTPs and create new AEADs.
$ yubihsm> generate otpaeadkey 0 0 otpaeadkey 1 decrypt-otp,create-otp-aead aes256-yubico-otp 0x01020304
Generated OTP AEAD key 0x027c
Command Line Mode
$ yubihsm-shell -a generate-otp-aead-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> --nonce <nonce_id> [--authkey <authKeyID> -p <password>]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the asymmetric key. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-l, –label=STRING Required.
Key label. Can be empty
Possible Values: Maximum of 40 characters string.
-d, –domains=STRING Required.
Domains where the key will be accessible.
Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.-c, –capabilities=STRING Required.
Capabilities of the key. Use
noneto include no capability.Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, create-otp-aead, decrypt-otp, randomize-otp-aead, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, exportable-under-wrap
-A, –algorithm=STRING Required.
Key lgorithm
Possible Values: aes128-yubico-otp, aes192-yubico-otp, aes256-yubico-otp
–nonce=INT Required.
OTP nonce
Example
Generate a new AES-256 OTP AEAD Key that can decrypt Yubico OTPs and create new AEADs.
$ yubihsm-shell -a generate-otp-aead-key -i 0 -l otpaeadkey -d 1 -c decrypt-otp,create-otp-aead -A aes256-yubico-otp --nonce 0x01020304
Generated OTP AEAD key 0x027c
Protocol Details
Command
Tc = 0x66
Lc = 2 + 40 + 2 + 8 + 1 + 4
Vc = I || L || D || C || A || N
where –
I= Object ID of the OTP AEAD Key (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
N= Nonce ID (4 bytes)
GENERATE SYMMETRIC KEY Command
Available with firmware version 2.3.1 or later.
Generate a symmetric Key in the device.
Interactive Mode
$ yubihsm> generate symmetric e:session,w:key_id,s:label,d:domains,c:capabilities,a:algorithm
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.label Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by,or:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by,or:with no spaces betweenPossible Values: none, decrypt-ecb, encrypt-ecb, decrypt-cbc, encrypt-cbc, exportable-under-wrap
algorithm Required.
Key algorithm
Possible Values: aes128, aes192, aes256
Example
Generate a new key using aes256 in the device:
$ yubihsm> generate asymmetric 0 0 aeskey 1 encrypt-ecb,decrypt-ecb aes256
Generated symmetric key 0xc040
Command Line Mode
$ yubihsm-shell -a generate-symmetric-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> [--authkey <authKeyID> -p <password>]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password will be prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the asymmetric key. Use ‘0’ to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-l, –label=STRING Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
-d, –domains=STRING Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by,or:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by,or:with no spaces betweenPossible Values: none, encrypt-ecb, decrypt-ecb, encrypt-cbc, decrypt-cbc, exportable-under-wrap
-A, –algorithm=STRING Required.
Key algorithm
Possible Values: aes128, aes192, aes256
Example
Generate a new key using secp256r1 in the device:
$ yubihsm-shell -a generate-symmetric-key -l aeskey -d 1 -c encrypt-ecb,decrypt-ecb -A aes256
Generated symmetric key 0xc040
Protocol Details
Command
Tc = 0x6e
Lc = 2 + 40 + 2 + 8 + 1
Vc = I || L || D || C || A
Generate a symmetric key with a given ID. Each parameter has a fixed length and the order is compulsory.
Where –
I = Object ID of the symmetric Key (2 bytes)
L = Label (40 bytes)
D = Domain (2 bytes)
C = Capability (8 bytes)
A = ALGORITHMS (1 byte)
GENERATE WRAP KEY Command
Generate a Wrap Key that can be used for export, import, wrap data and unwrap data.
Shell Example
Generate a new Wrap Key that can be used for wrap and unwrap.
$ yubihsm> generate wrapkey 0 0 wrapkey 1 wrap-data:unwrap-data none
aes256-ccm-wrap
Generated Wrap key 0x5b3a
Interactive Mode
$ yubihsm> generate hmackey e:session, w:key_id, s:label, d:domains, c:capabilities, c:delegated_capabilities, a:algorithm
Parameters
Session Required.
The ID of the authenticated session to send the command over.
Possbile Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Label Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string.
Domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, wrap-data, unwrap-data, export-wrapped, import-wrapped, exportable-under-wrap
delegated_capabilities Required.
Delegated capabilities. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
Algorithm Required.
Key algorithm.
Possible Values: aes128-ccm-wrap, aes192-ccm-wrap, aes256-ccm-wrap, rsa2048, rsa3072, rsa4096
Example
Generate a new Wrap Key that can be used for wrap and unwrap.
$ yubihsm> generate wrapkey 0 0 wrapkey 1 wrap-data:unwrap-data none aes256-ccm-wrap
Generated Wrap key 0x5b3a
Command Line Mode
$ yubihsm-shell -a generate-wrap-key -i <key_id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> -A <algorithm> [--authkey <authKeyID> -p <password>]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified
-i, –object-id=SHORT Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.-l, –label=STRING Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
-d, –domains=STRING Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, wrap-data, unwrap-data, export-wrapped, import-wrapped, exportable-under-wrap
–delegated=STRING
Delegated capabilities of kry. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
Default Value: none
-A, –algorithm=STRING Required.
Key algorithm.
Possible Values: aes128-ccm-wrap, aes192-ccm-wrap, aes256-ccm-wrap
Example
Generate a new Wrap Key that can be used for wrap and unwrap.
$ yubihsm-shell -a generate-wrap-key -i 0 -l wrapkey -d 1 -c wrap-data:unwrap-data -A aes256-ccm-wrap
Generated Wrap key 0x5b3a
Protocol Details
Command
Tc = 0x5b
Lc = 2 + 40 + 2 + 8 + 1 + 8
Vc = I || L || D || C || A || DC
where –
I= Object ID of the Wrap Key (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
DC= Delegated Capability (8 bytes)
GET DEVICE PUBLIC KEY Command
Available with firmware version 2.3.1 or later.
Fetch the device public key to use with asymmetric authentication to the device. This is end as a bare command and not over an encrypted session.
Example
Get device public key:
yubihsm> get devicepubkey
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEfSE6zN59ONnsOf
9C8VGNym+oBgnWO5mjJZJ5Z9kkbpMIhLwkjsqKOhgKI+Slfv3o
XmrcwVzUstLAkQe1HdC/uA==
-----END PUBLIC KEY-----
Protocol Details
Command
T~c~ = 0x0a
L~c~ = 0
V~c~ = Ø
Response
T~r~ = 0x8a
L~r~ = 1 + 64
V~r~ = A | | K
Where –
A= ALGORITHMS (1 byte)
K= Uncompressed EC-P256 public key (64 bytes)
The algorithm will currently always be ec-p256-yubico-authentication.
The uncompressed EC key marker is omitted (hence the 64 bytes), similarly to how other EC keys are handled.
GET LOG ENTRIES Command
Fetch device audit log. Fetch all current entries from the device Log Store.
Shell Example
$ yubihsm> audit get 0
0 unlogged boots found
0 unlogged authentications found
Found 6 items
item: 46 -- cmd: 0x4b -- length: 234 -- session key: 0x0001
-- target
key: 0xcf94 -- second key: 0x997e -- result: 0xcb -- tick: 335725
-- hash: 415f51f1f035a1b713e730e4464e4033
item: 47 -- cmd: 0x4c -- length: 77 -- session key: 0x0001
-- target
key: 0xaff7 -- second key: 0xffff -- result: 0xcc -- tick: 351714
-- hash: 5496a60d478c2b9c801d8d32ca66b554
item: 48 -- cmd: 0x00 -- length: 0 -- session key: 0xffff
-- target
key: 0x0000 -- second key: 0x0000 -- result: 0x00 -- tick: 0 -- hash:
14ac7747ba9bbb243cfc70befeb5349b
item: 49 -- cmd: 0x03 -- length: 10 -- session key: 0xffff
-- target
key: 0x0001 -- second key: 0xffff -- result: 0x83 -- tick: 139 -- hash:
b20a8f25c025e693a8e869b433294a20
item: 50 -- cmd: 0x04 -- length: 17 -- session key: 0xffff
-- target
key: 0x0001 -- second key: 0xffff -- result: 0x84 -- tick: 139 -- hash:
ebfae425c319ac7a0afbb8b92597de7c
item: 51 -- cmd: 0x67 -- length: 2 -- session key: 0x0001
-- target
key: 0xffff -- second key: 0xffff -- result: 0xe7 -- tick: 697 -- hash:
2e395d1b706668737e1d2215813db47e
Interactive Mode
$ yubihsm> audit get e:session, F:file=-
Parameters
Session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
File
Log entries. Default output format: ASCII.
Possible Values: Path to file or “-“ for stdout
Default Value: stdout
Example
$ yubihsm> audit get 0
0 unlogged boots found
0 unlogged authentications found
Found 6 items
item: 46 -- cmd: 0x4b -- length: 234 -- session key: 0x0001 -- target key: 0xcf94 -- second key: 0x997e -- result: 0xcb -- tick: 335725 -- hash: 415f51f1f035a1b713e730e4464e4033
item: 47 -- cmd: 0x4c -- length: 77 -- session key: 0x0001 -- target key: 0xaff7 -- second key: 0xffff -- result: 0xcc -- tick: 351714 -- hash: 5496a60d478c2b9c801d8d32ca66b554
item: 48 -- cmd: 0x00 -- length: 0 -- session key: 0xffff -- target key: 0x0000 -- second key: 0x0000 -- result: 0x00 -- tick: 0 -- hash: 14ac7747ba9bbb243cfc70befeb5349b
item: 49 -- cmd: 0x03 -- length: 10 -- session key: 0xffff -- target key: 0x0001 -- second key: 0xffff -- result: 0x83 -- tick: 139 -- hash: b20a8f25c025e693a8e869b433294a20
item: 50 -- cmd: 0x04 -- length: 17 -- session key: 0xffff -- target key: 0x0001 -- second key: 0xffff -- result: 0x84 -- tick: 139 -- hash: ebfae425c319ac7a0afbb8b92597de7c
item: 51 -- cmd: 0x67 -- length: 2 -- session key: 0x0001 -- target key: 0xffff -- second key: 0xffff -- result: 0xe7 -- tick: 697 -- hash: 2e395d1b706668737e1d2215813db47e
Command Line Mode
$ yubihsm-shell -a get-logs --out <file> [--authkey <authKeyID> -p <password>]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
–out=STRING
Log entries.
Possible Values: Path to file or stdout
Default Value: stdout
–outformat=ENUM
Output data format.
Possible Values: default, base64, binary, PEM, hex, ASCII
Default Format: ASCII A
Example
$ yubihsm-shell -a get-logs
0 unlogged boots found
0 unlogged authentications found
Found 6 items
item: 46 -- cmd: 0x4b -- length: 234 -- session key: 0x0001 -- target key: 0xcf94 -- second key: 0x997e -- result: 0xcb -- tick: 335725 -- hash: 415f51f1f035a1b713e730e4464e4033
item: 47 -- cmd: 0x4c -- length: 77 -- session key: 0x0001 -- target key: 0xaff7 -- second key: 0xffff -- result: 0xcc -- tick: 351714 -- hash: 5496a60d478c2b9c801d8d32ca66b554
item: 48 -- cmd: 0x00 -- length: 0 -- session key: 0xffff -- target key: 0x0000 -- second key: 0x0000 -- result: 0x00 -- tick: 0 -- hash: 14ac7747ba9bbb243cfc70befeb5349b
item: 49 -- cmd: 0x03 -- length: 10 -- session key: 0xffff -- target key: 0x0001 -- second key: 0xffff -- result: 0x83 -- tick: 139 -- hash: b20a8f25c025e693a8e869b433294a20
item: 50 -- cmd: 0x04 -- length: 17 -- session key: 0xffff -- target key: 0x0001 -- second key: 0xffff -- result: 0x84 -- tick: 139 -- hash: ebfae425c319ac7a0afbb8b92597de7c
item: 51 -- cmd: 0x67 -- length: 2 -- session key: 0x0001 -- target key: 0xffff -- second key: 0xffff -- result: 0xe7 -- tick: 697 -- hash: 2e395d1b706668737e1d2215813db47e
Protocol Details
Command
Tc = 0x4d
Lc = 0
Vc = Ø
Response
Tr = 0xcd
Lr = 2 + 2 + 1 + (N * 32)
Vr = B || O || N || E1 || E2 || … || EN
Where –
B = Number of unlogged boot events (if the log buffer is full and audit enforce is set) (2 bytes)
O = Number of unlogged authentication events (if the log buffer is full and audit enforce is set) (2 bytes)
N = Number of elements in the list (1 byte)
Ei = Generic log entry composed of
- Command number (two bytes)
- Command ID (one byte)
- Command length (two bytes)
- ID of the originating session’s authentication key (two bytes)
- Target key affected by the command (two bytes)
- Secondary key if the command affected more than one key (two bytes)
- Result of the command on success or an error code if unsuccessful (one byte)
- Systick when the command was processed (4 bytes)
- Digest (16 bytes)
The digest is computed as trunc(16, SHA256(Ei.Data || trunc(16, Ei-1.Digest))). For the initial log entry, a random string of 32 bytes is used, instead of the digest of the previous message.
When the device initializes after a reset, a log entry with all fields set to 0xff is logged.
When the device boots up, a log entry with all fields set to 0x00 is logged.
GET OBJECT INFO Command
Fetch all metadata about an Objects.
Shell Example
Get Object info for Asymmetric Key with ID 0x1e15.
$ yubihsm> get objectinfo 0 0x1e15 asymmetric-key
id: 0x1e15, type: asymmetric-key, algorithm: rsa2048, label: "rsakey",
length: 896, domains: 1, sequence: 0, origin: imported, capabilities:
sign-pkcs
Interactive Mode
$ yubihsm> get objectinfo e:session, w:id, t:type
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Value: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
id Required.
Object ID of the object to delete. Object ID is a 2 bytes integer. Can be specified in hex or decimal
type Required.
Type of the object to delete.
Possbile Values: asymmetric-key, authentication-key, hmac-key, opaque, otp-aead-key, template, wrap-key
Example
Get Object info for Asymmetric Key with ID 0x1e15.
$ yubihsm> get objectinfo 0 0x1e15 asymmetric-key
id: 0x1e15, type: asymmetric-key, algorithm: rsa2048, label: "rsakey", length: 896, domains: 1, sequence: 0, origin: imported, capabilities: sign-pkcs
Command Line Mode
$ yubihsm-shell -a get-object-info -i <id> -t <type> [ --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the object to delete. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-t, –object-type=STRING Required.
Type of the object to delete.
Possible Values: asymmetric-key, authentication-key, hmac-key, opaque, otp-aead-key, template, wrap-key
Example
Get Object info for Asymmetric Key with ID 0x1e15.
$ yubihsm-shell -a get-object-info -i 0x1e15 -t asymmetric-key
Protocol Details
Response
Tr = 0xce
Lr = 8 + 2 + 2 + 2 + 1 + 1 + 1 + 1 + 40 + 8
Vr = C || I || N || D || T || A || S || O || L || DC
where –
C= Capability (8 bytes)
I= Object ID (2 bytes)
N= Object Length (2 bytes)
D= Domain (2 bytes)
T= Type, Objects (1 byte)
A= ALGORITHMS (1 byte)
S= Sequence (1 byte)
O= Origin (1 byte)
L= Label (40 bytes)
DC= Delegated Capability (8 bytes)
GET OPAQUE Command
Retrieve an Opaque Object (like an X.509 certificate) from the device.
Shell Example
Fetch Opaque Object 0xe255 and store in the file cert.der.
$ yubihsm> get opaque 0 0xe255 cert.der
Interactive Mode
$ yubihsm> get opaque e:session, w:object_id, F:file=-
Parameters
Session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
object_id Required.
Opaque Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
File
Value of Opaque object. Default output format: binary (DER). If object algorithm is opaque-x509-certificate, the output will be an X509Certificate.
Possible Values: Path to file or ‘-’ for stdout
Default Value: stdout
Example
Fetch Opaque Object 0xe255 and store in the file cert.der.
$ yubihsm> get opaque 0 0xe255 cert.der
Command Line Mode
$ yubihsm-shell -a get-opaque -i <object_id> [--out <file> --outformat <format> --authkey <authKeyID> -p <password>]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Opaque Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–out=STRING
Value of Opaque object. Default output format: binary (DER). If object algorithm is opaque-x509-certificate, the output will be an X509Certificate.
Possible Values: Path to file or stdout
Default Value: stdout
–outformat=ENUM
Output data format.
Possible Values: binary, PEM
Example
Fetch Opaque Object 0xe255 and store in the file cert.pem.
$ yubihsm-shell -a get-opaque -i 0xe255 --out cert.pem
GET OPTION Command
Get device-global Options. Each invocation of this command retrieves a single Option, which is selected by its represented TAG (see SET OPTION Command).
Shell Example
$ yubihsm> get option 0 force-audit
Option value is: 00
Interactive Mode
$ yubihsm> get option e:session, o:option
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possbile Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Option Required.
Device option. fips-mode option is only applicable in FIPS compatible YubiHSMs.
Possible Values: algorithm-toggle, command-audit, force-audit, fips-mode
Example
$ yubihsm> get option 0 force-audit
2Option value is: 00
Command Line Mode
$ yubihsm-shell -a get-option --opt-name <option> [ --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
–opt-name=STRING Required.
Device option name.
fips-modeoption is only applicable in FIPS compatible YubiHSMs.Possible Values: algorithm-toggle, command-audit, force-audit, fips-mode
Example
$ yubihsm-shell -a get-option --opt-name force-audit
Option value is: 00
GET PSEUDO RANDOM Command
Extract a fixed number of pseudo-random bytes from the device, using the internal PRNG.
Shell Example
$ yubihsm> get random 0 16 bd50979da2d1bca13d8d735abf419556
Interactive Mode
$ yubihsm> get random e:session, w:count, F:out=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Count Required.
Number of bytes to request.
File
Pseudo random number.
Possible Values: Path to file or “-“ for stdout
Default Value: stdout
Default Output Format: hexf
Example
$ yubihsm> get random 0 16 bd50979da2d1bca13d8d735abf419556
Command Line Mode
$ yubihsm-shell -a get-pseudo-random [--count <count> --out <file> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
–p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
—count=INT
Number of bytes to request
Default Value: 256
—out=STRING
Pseudo random number.
Possible Values: Path to file or stdout
Default Value: stdout
Default Output Format: hex
—outformat=ENUM
Output data format
Possible Values: base64, binary, PEM, hex
Example
$ yubihsm-shell -a get-pseudo-random 6bce0cc95f41459d8d4b539df5c9a3b2478460877291f227df5a6d38065c25bce7a741e685b3e7c6664edf98e8079b2d2414b074d391e42342ce053f59043a799248ed6392c653354039ca1268b165d04a65f0d92bc485a53d84b4826308c969a358d1db4dab0c2dbfc4213e7a63c337419db09b2bf5f7b622f2c038e905b9ee24e1def4fe43b397fc0daaf1a7f3501b9520be095b6e90b62388526c01d3cea591ea60c68fe04a01f9bf89156dc4124ad71a74586db6c4e78d8e17bde3231af51eb4f2d3476158de427060b35747745d2c14e4ee959df616d8859b0006d7ec35ce541cf30a79f9e3a896e19c9a0183bb97b76593f5aec7483399371a78a68fd0
GET PUBLIC KEY Command
Fetch the public key of an object. With YubiHSM firmware version prior to 2.4, only public key of Asymmetric Key are returned. With firmware version 2.4 or later, public keys of RSA Wrap Keys can also be returned.
Interactive Mode
$ yubihsm> get pubkey e:session, w:key_id, t:key_type=asymmetric-key, F:file=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possbile Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Asymmetric key Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
key_type
Object type.
Possible Values: asymmetric-key or wrap-key
Default Value: asymmetric-key
File
Public key.
Possible Values: Path to file or “-“ for stdout
Default Value: stdout
Default Format: PEM
Example
Fetch the public key of RSA Wrap Key 0x2846.
$ yubihsm> get pubkey 0 0x2846 wrap-key
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE85fayPHTvCrv0RRcyCsHv0hTKAM7
xHiU2I3NgO61RTRQumGDeBnQZIITykK/0PWKLGDANfBVrmKkWWxB47ze9A==
-----END PUBLIC KEY-----
Command Line Mode
$ yubihsm-shell -a get-public-key -i <key_id> [ -t <key_type> --out <file> --outformat <format> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of an asymmetric key. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-t, –object-type=STRING
Object type.
Possible Values: asymmetric-key or wrap-key
Default Value: asymmetric-key
–out=STRING
Public key.
Possible Values: Path to file or stdout
Default Value: stdout
Default Format: PEM
–outformat=ENUM
Output data format.
Possible Values: binary, PEM
Example
Fetch the public key of RSA Wrap Key 0x2846.
$ yubihsm-shell -a get-public-key -i 0x2846 -t wrap-key
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE85fayPHTvCrv0RRcyCsHv0hTKAM7
xHiU2I3NgO61RTRQumGDeBnQZIITykK/0PWKLGDANfBVrmKkWWxB47ze9A==
-----END PUBLIC KEY-----
Protocol Details
Response
Tr = 0xd4
Lr = 1 + LP1 /{ + LP2 /}
Vr = A || P1 /{ || P2 /}
where –
AA = ALGORITHMS
P1 =
- For RSA: Public modulus N (256, 384 or 512 bytes)
- For ECC: Public point X (32, 48, 64 or 66 bytes)
- For EDC: Public point A, compressed (32 bytes)
P2=
- For RSA: NOT DEFINED
- For ECC: Public point Y (32, 48, 64 or 66 bytes)
- For EDC: NOT DEFINED
GET STORAGE INFO Command
Report currently free storage. This is reported as currently free records, free pages and page size. Each object takes a record slot and will use as many pages as needed.
Shell Example
$ yubihsm> get storage 0
free records: 255/256, free pages: 1023/1024 page size: 126 bytes
Interactive Mode
$ yubihsm> get storage e:session
Parameters
session Required,
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Example
$ yubihsm> get storage 0
free records: 255/256, free pages: 1023/1024 page size: 126 bytes
Command Line Mode
This command is not available in command line mode.
Protocol Details
Command
Tc = 0x41
Lc = 0
Vc = Ø
Response
Tr = 0xc1
Lr = 10
Vr = Rtotal || Rfree || Ptotal || Pfree || S
where –
Rtotal= Total number of records (2 bytes)
Rfree= Currently free storage records (2 bytes)
Ptotal= Total number of pages (2 bytes)
Pfree= Currently free storage pages (2 bytes)
S= Page size in bytes (2 bytes)
GET TEMPLATE Command
Retrieve a Template Object from the device.
Shell Example
Fetch Template Object 0x7b19 and store in the file template.dat.
$ yubihsm> get template 0 0x7b19 template.dat
Interactive Mode
$ yubihsm> get template e:session, w:object_id, F:out=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
object_id Required.
Object ID of a template object. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
File
Template value.
Possible Values: Path to file or ‘-’ for stdout
Default Value: stdout
Example
Fetch Template Object 0x7b19 and store in the file template.dat.
$ yubihsm> get template 0 0x7b19 template.dat
Command Line Mode
$ yubihsm-shell -a get-template -i <object_id> [--out <file> --outformat <format> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of a template object. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–out=STRING
Template value.
Possible Values: Path to file or stdout
Default Value: stdout
–outformat=ENUM
Output data format.
Possible Values: base64, hex, PEM
Example
Fetch the public key of Asymmetric Key 0x2846.
$ yubihsm-shell -a get-template -i 0x7b19 --out template.dat
IMPORT WRAPPED Command
Import a wrapped/encrypted Object that was previously exported by an YubiHSM 2 device into the device. The imported object will retain its metadata (Object ID, Domains, Capabilities, etc), however, the object’s origin will be marked as imported instead of generated.
Shell Example
Import the Object stored in key.enc and unwrap it using Wrap Key 0xcf94.
$ yubihsm> put wrapped 0 0xcf94 key.enc
Object imported as 0x997e of type asymmetric
Interactive Mode
$ yubihsm> put wrapped e:session, w:wrapkey_id, i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
wrapkey_id Required.
Object ID of the wrap key to decrypt/unwrap the data. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
File
Encrypted/wrapped object.
Possible Values: Path to file or ‘-’ for stdin
Default Value: stdin
Default Format: base64
Example
Import the Object stored in key.enc and unwrap it using Wrap Key 0xcf94.
$ yubihsm> put wrapped 0 0xcf94 key.enc
Object imported as 0x997e of type asymmetric
Command Line Mode
$ yubihsm-shell -a put-wrapped --wrap-id <wrapkey_id> [--in <file> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-p, –password=STRING
The password to authentication key used to open a session. The password is prompted for if not specified.
–wrap-id=INT Required.
Object ID of the wrap key to decrypt/unwrap the data. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–in=STRING
Encrypted/wrapped object.
Possbile Values: Path to file or stdin
Default Value: stdin
Default Format: base64
Example
Import the Object stored in key.enc and unwrap it using Wrap Key 0xcf94.
$ yubihsm-shell -a put-wrapped --wrap-id 0xcf94 --in key.enc
IMPORT RSA WRAPPED Command
Available on YubiHSM devices with firmware version 2.4 or higher.
Import a wrapped/encrypted Object that was previously exported by an YubiHSM 2 device into the device. The imported object will retain its metadata (Object ID, Domains, Capabilities, etc), however, the object’s origin will be marked as imported instead of generated.
Interactive Mode
$ yubihsm> put rsa_wrapped e:session, w:wrapkey_id, a:hash=rsa-oaep-sha256, mgf1=mgf1-sha256, i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
wrapkey_id Required.
Object ID of the wrap key to decrypt/unwrap the data. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
File
Encrypted/wrapped object.
Possible Values: Path to file or ‘-’ for stdin
Default Value: stdin
Format: Binary
hash
Hash algorithm to use for OAEP label.
Possible Values: rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384 or rsa-oaep-sha512
Default Value: rsa-oaep-sha256
mgf1
Hash algorithm to use for MGF1.
Possible Values: mgf1-sha1, mgf1-sha256, mgf1-sha384 or mgf1-sha512
Default Value: mgf1-sha256
Example
Import the Object stored in object.enc and unwrap it using Wrap Key 0xcf94.
$ yubihsm> put rsa_wrapped 0 0xcf94 rsa-oaep-sha384 mgf1-sha1 object.enc
Object imported as 0x997e of type asymmetric
Command Line Mode
$ yubihsm-shell -a put-rsa-wrapped --wrap-id <wrapkey_id> [ --oaep <oaep> --mgf1 <mgf1> --in <file> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-p, –password=STRING
The password to authentication key used to open a session. The password is prompted for if not specified.
–wrap-id=INT Required.
Object ID of the wrap key to decrypt/unwrap the data. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–in=STRING
Encrypted/wrapped object.
Possbile Values: Path to file or stdin
Default Value: stdin
Format: Binary
–oaep=STRING
Hash algorithm to use for OAEP label.
Possible Values: rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384 or rsa-oaep-sha512
Default Value: rsa-oaep-sha256
–mgf1=STRING
Hash algorithm to use for MGF1.
Possible Values: mgf1-sha1, mgf1-sha256, mgf1-sha384 or mgf1-sha512
Default Value: mgf1-sha256
Example
Import the Object stored in object.enc and unwrap it using Wrap Key 0xcf94.
$ yubihsm-shell -a put-rsa-wrapped --wrap-id 0xcf94 --oaep rsa-oaep-sha384 --mgf1 mgf1-sha1 --in object.enc
Protocol Details
Command
Tc = 0x77
Lc = 2 + 1 + 1 + Lw + LHL
Vc = I || H || M || W || HL
where –
I= Object ID of the Wrap Key (2 bytes)
H= ALGORITHMS to use for OAEP label (1 byte)
M= ALGORITHMS to use for MGF1 (1 byte)
W= The wrapped object (Length dependent on object)
LH= The label digest (Length dependent on OAEP algorithm)
IMPORT RSA WRAPPED KEY Command
Available on YubiHSM devices with firmware version 2.4 or higher.
Import a wrapped/encrypted an (a)symmetric key object. Only asymmetric and symmetric key objects are valid targets. Asymmetric keys are expected to have been serialized as PKCS#8. Since the object properties are not part of the wrapped object, they must be provided separately.
Interactive Mode
$ yubihsm> put rsa_wrapped_key e:session, w:wrapkey_id, t:type, w:key_id, a:algorithm, s:label, d:domains, c:capabilities, a:hash=rsa-oaep-sha256, mgf1=mgf1-sha256, i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
wrapkey_id Required.
Object ID of the wrap key to decrypt/unwrap the data. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
type Required.
Type of the object to import.
Possible Values: asymmetric-key or symmetric-key
key_id Required.
Object ID of the imported key. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.algorithm Required.
Algorithm of the imported key.
Possible values:
For RSA keys: rsa2048, rsa3072, rsa4096
For EC keys: eck256, ecp224, ecp256, ecp384, ecp521, ecbp256, ecbp384, ecbp512
For ED keys: ed25519
For AES keys: aes128, aes192, aes256
label Required.
Key label. Can be empty.
Possbile Values: Maximum of 40 characters string
data
Encrypted/wrapped object.
Possible Values: Path to file or ‘-’ for stdin
Default Value: stdin
Format: Binary
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by,or:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by,or:with no spaces between.Possbile Values: none, all, decrypt-oaep, decrypt-pkcs, derive-ecdh, exportable-under-wrap, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-pkcs, sign-pss, sign-ssh-certificate
hash
Hash algorithm to use for OAEP label.
Possible Values: rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384 or rsa-oaep-sha512
Default Value: rsa-oaep-sha256
mgf1
Hash algorithm to use for MGF1.
Possible Values: mgf1-sha1, mgf1-sha256, mgf1-sha384 or mgf1-sha512
Default Value: mgf1-sha256
Example
Import the Object stored in key.enc and unwrap it using Wrap Key 0xcf94.
$ yubihsm> put rsa_wrapped_key 0xcf94 asymmetric-key 0 rsa2048 "" 1,2,3 sign-pkcs,exportable-under-wrap rsa-oaep-sha384 mgf1-sha1 key.enc
Object imported as 0x97df of type asymmetric
Command Line Mode
$ yubihsm-shell -a put-rsa-wrapped-key --wrap-id <wrapkey_id> -t <key_type> -A <key_algorithm> -d <domains> [ -i <key_id> -l <key_label> -c <capabilities> --oaep <oaep> --mgf1 <mgf1> --in <file> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-p, –password=STRING
The password to authentication key used to open a session. The password is prompted for if not specified.
–wrap-id=INT Required.
Object ID of the wrap key to decrypt/unwrap the data. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–in=STRING
Encrypted/wrapped object.
Possbile Values: Path to file or stdin
Default Value: stdin
Format: Binary
-t, –object-type=STRING Required.
Type of the object to import.
Possible Values: asymmetric-key or symmetric-key
-i, –object-id=SHORT
Object ID of the imported key. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.-A, –algorithm=STRING Required.
Algorithm of the imported key.
Possible values:
For RSA keys: rsa2048, rsa3072, rsa4096
For EC keys: eck256, ecp224, ecp256, ecp384, ecp521, ecbp256, ecbp384, ecbp512
For ED keys: ed25519
For AES keys: aes128, aes192, aes256
-l, –label=STRING
Key label. Can be empty.
Possbile Values: Maximum of 40 characters string
-d, –domains=STRING Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by,or:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING
Capabilities of the key. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by,or:with no spaces between.Possbile Values: none, all, decrypt-oaep, decrypt-pkcs, derive-ecdh, exportable-under-wrap, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-pkcs, sign-pss, sign-ssh-certificate
–oaep=STRING
Hash algorithm to use for OAEP label.
Possible Values: rsa-oaep-sha1, rsa-oaep-sha256, rsa-oaep-sha384 or rsa-oaep-sha512
Default Value: rsa-oaep-sha256
–mgf1=STRING
Hash algorithm to use for MGF1.
Possible Values: mgf1-sha1, mgf1-sha256, mgf1-sha384 or mgf1-sha512
Default Value: mgf1-sha256
Example
Import the Object stored in key.enc and unwrap it using Wrap Key 0xcf94.
$ yubihsm-shell -a put-rsa-wrapped-key --wrap-id 0xcf94 -t asymmetric-key -d 1,2,3 -A rsa2048 --oaep rsa-oaep-sha384 --mgf1 mgf1-sha1 --in key.enc
Protocol Details
Command
Tc = 0x75
Lc = 2 + 1 + 2 + 40 + 2 + 8 + 1 + 1 + 1 + Lw + LHL
Vc = I || To || Ti || L || D || C || A || H || M || W || HL
where –
I= Object ID of the Wrap Key (2 bytes)
To= Objects of the imported key (1 byte)
Ti= Object ID of the imported key (2 bytes)
L= Label of the imported key (40 bytes)
D= Domain of the imported key (2 bytes)
C= Capability of the imported key (8 bytes)
A= ALGORITHMS of the imported key (1 byte)
H= ALGORITHMS to use for OAEP label (1 byte)
M= ALGORITHMS to use for MGF1 (1 byte)
W= The wrapped object (Length dependent on object)
LH= The label digest (Length dependent on OAEP algorithm)
LIST OBJECTS Command
Get a filtered list of Objects from the device.
Shell Example
Get a list of all Asymmetric Keys for Session 0.
yubihsm> list objects 0 0 asymmetric-key
Found 4 object(s)
id: 0x3479, type: asymmetric-key, sequence: 0
id: 0x7df6, type: asymmetric-key, sequence: 0
id: 0x9602, type: asymmetric-key, sequence: 0
id: 0xd6cd, type: asymmetric-key, sequence: 0
Interactive Mode
yubihsm> list objects e:session, w:id=0, t:type=any, d:domains=0, c:capabilities=0, a:algorithm=any, s:label=
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Id
Object ID.
0returns all Object IDs. Object ID is a 2 bytes integer. Can be specified in hex or decimal.Default Value: 0
Type
Object type.
anyreturns all types>Possible Values: any, opaque, authentication-key, asymmetric-key, wrap-key, hmac-key, template, otp-aead-key
Default Value; any
domains
Domains where the key will be accessible.
allreturns all domains.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
Default Value: all
capabilities
Capabilities of the key.
allreturns all capabilities.Possible Values: all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
Default Value: all
Algorithm
Key algorithm.
anyreturns all algorithms.Possible Values: any, rsa2048, rsa3072, rsa4096, ecp256, ecp384, ecp521, eck256, ecbp256, ecbp384, ecbp512, ed25519, ecp224, hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512, aes128-ccm-wrap, opaque-data, opaque-x509-certificate, aes128-yubico-otp, aes128-yubico-authentication, aes192-yubico-otp, aes256-yubico-otp, aes192-ccm-wrap, aes256-ccm-wrap
Default Value: any
Label
Object label. Empty value means all labels.
Possible Values: Maximum of 40 characters string.
Default Value: Empty
Example
Get a list of all Asymmetric Keys for Session 0.
yubihsm> list objects 0 0 asymmetric-key
Found 4 object(s)
id: 0x3479, type: asymmetric-key, sequence: 0
id: 0x7df6, type: asymmetric-key, sequence: 0
id: 0x9602, type: asymmetric-key, sequence: 0
id: 0xd6cd, type: asymmetric-key, sequence: 0
Command Line Mode
$ yubihsm-shell -a list-objects -t <type> -A <algorithm> [-i <key_id> -l <label> -d <domains> -c <capabilities> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT
Object ID.
0returns all Object IDs. Object ID is a 2 bytes integer. Can be specified in hex or decimal.Default Value: 0
-t, –object-type=STRING Required.
Object type. Use
anyto return all types.Possible Values: any, opaque, authentication-key, asymmetric-key, wrap-key, hmac-key, template, otp-aead-key
-l, –label=STRING
Object label.
Possible Values: Maximum of 40 characters string
Default Value: Empty
-d, –domains=STRING
Domains where the key will be accessible.
Possbile Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
Default Value: all
-c, –capabilities=STRING
Capabilities of the key.
Possible Values: all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
Default Value: all
-A, –algorithm=STRING Required.
Key algorithm. Use
anyto return all algorithms.Possible Values: any, rsa2048, rsa3072, rsa4096, ecp256, ecp384, ecp521, eck256, ecbp256, ecbp384, ecbp512, ed25519, ecp224, hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512, aes128-ccm-wrap, opaque-data, opaque-x509-certificate, aes128-yubico-otp, aes128-yubico-authentication, aes192-yubico-otp, aes256-yubico-otp, aes192-ccm-wrap, aes256-ccm-wrap
Example
Generate a new key using secp256r1 in the device.
$ yubihsm-shell -a list-objects -t any -A any
Found 4 object(s)
id: 0x3479, type: asymmetric-key, sequence: 0
id: 0x7df6, type: asymmetric-key, sequence: 0
id: 0x9602, type: asymmetric-key, sequence: 0
id: 0xd6cd, type: asymmetric-key, sequence: 0
Protocol Details
Command
Tc = 0x48
Lc = LF
Vc = F
where –
F= List of Tag-Value pairs describing a filter to apply. Possible tags to use for filtering are described in the table below.
| Name | Identifier | Length |
|---|---|---|
| ID, Object ID | 0x01 | 2 bytes |
| TYPE, Objects | 0x02 | 1 byte |
| Domain | 0x03 | 2 bytes |
| Capability | 0x04 | 8 bytes |
| ALGORITHMS | 0x05 | 1 byte |
| Label | 0x06 | 40 bytes |
PUT ASYMMETRIC KEY Command
Import an Asymmetric Key into the device.
Shell Example
Store an RSA key from key.pem into the device.
yubihsm> put asymmetric 0 0 rsakey 1 sign-pkcs key.pem
Stored Asymmetric key 0x1e15
Protocol Details
Command
Tc = 0x45
Lc = 2 + 40 + 2 + 8 + 1 + LP1 /{ + LP2 /}
Vc = I || L || D || C || A || P1 /{ || P2 /}
The key parameters vary according to the chosen algorithm. Each parameter has a fixed length and the order is compulsory.
where –
I= Object ID of the Asymmetric Key (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
P1=For RSA: secret prime p (128, 192 or 256 bytes)
For ECC: private key integer d (32, 48, 64 or 66 bytes)
For EDC: private key integer k (32 bytes)
P2=For RSA: secret prime q (128, 192 or 256 bytes)
For ECC: NOT DEFINED
For EDC: NOT DEFINED
PUT ASYMMETRIC AUTHENTICATION KEY Command
Available with firmware version 2.3.1 or later.
Store an Asymmetric Authentication Key in the device.
Interactive Mode
yubihsm> put authkey_asym e:session,w:key_id,s:label,d:domains,c:capabilities,c:delegated_capabilities,i:pubkey=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use ‘0’ to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal
label Required.
Key label. Can be empty.
Possbile Values: Maximum of 40 characters string
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by,or:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by,or:with no spaces between.Possbile Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
delegated_capabilities Required.
Delegated capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by,or:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data Use ‘all’ to include all capabilities.
pubkey
The public key of the clien. When using stdin, click CTRL-D to mark end of input. Input format for a password string is
password. Ifpasswordformat is used, the tool will derive an ec-p256 private key from the input string and calculate the public key from that. The private key is not used for anything else.Possible Values: File containing the client’s public key as an uncompressed ec-p256 public key, password or
-for stdinDefault Value: stdin
Default format: PEM
Possible format for public key file: PEM, HEX, binary.
Example
Store a new Asymmetric Authentication Key using a client’s public key:
yubihsm> put authkey_asym 0 0 asym_authkey 1,2,3 generate-asymmetric-key,sign-pkcs sign-pkcs
-----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEKIfzuX9uJ2gsNgXcFYtNkP30aBp+
e0f9mhpy+lQbvbbD72y5HiMIkbNkqBXHOwSPu/suD/f1BoN8xcP4FHk4iw==
-----END PUBLIC KEY-----
Stored Authentication key 0xe599
Command Line Mode
Asymmetric authentication keys cannot be added using the command line.
Protocol Details
Command
Tc = 0x44
Lc = 2 + 40 + 2 + 8 + 1 + 8 + 64
Vc = I || L || D || C || A || DC || Key
Where –
I = Object ID of the Authentication Key (2 bytes)
L = Label (40 bytes)
D = Domains (2 bytes)
C = Capabilities (8 bytes)
A = Algorithm (1 bytes)
DC = Delegated Capabilities (8 bytes)
Key = Uncompressed EC-P256 public key (64 bytes)
Response
Tr = 0xc4
Lr = 2
Vr = I
Where –
I = Object ID of created Authentication Key (2 bytes)
Note
This command will return ERROR_INV_DATA if Key is not a valid EC-P256 key.
PUT AUTHENTICATION KEY Command
Store an Authentication Key in the device.
Shell Example
Store a new Authentication Key derived from the password newpassword.
yubihsm> put authkey 0 0 authkey 1 generate-asymmetric-key,sign-pkcs
sign-pkcs newpassword
Stored Authentication key 0xbb72
Interactive Mode
yubihsm> put authkey e:session, w:key_id, s:label, d:domains, c:capabilities, c:delegated_capabilities, i:password=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.label Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data Use
allto include all capabilities.delegated_capabilities Required.
Delegated capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data Use
allto include all capabilities.password
The password used to derive the session keys from this authentication key.
Possible Values: The password or “-“ for stdin
Default Value: stdin
Input Format: password
Example
Store a new Authentication Key derived from the password newpassword.
yubihsm> put authkey 0 0 authkey 1 generate-asymmetric-key,sign-pkcs sign-pkcs newpassword
Stored Authentication key 0xbb72
Command Line Mode
$ yubihsm-shell -a put-authentication-key -i <key_id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> [--new-password <new_authkey_password> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the asymmetric key. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.-l, –label=STRING Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string.
-d, –domains=STRING Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Value: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING Required.
Capabilities of the key. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
–delegated=STRING Required.
Delegated capabilities of the key. Use
allto include all delegated capabilities. Usenoneto include no delegated capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
–new-password=STRING
The password used to derive the session keys from this authentication key.
Possible Values: The password or stdin
Default ValueL: stdin
Input Format: password
Example
Fetch the public key of Asymmetric Key 0x2846.
$ yubihsm-shell -a put-authentication-key -i 0 -l authkey -d 1 -c generate-asymmetric-key,sign-pkcs --delegated sign-pkcs --new-password newpassword
Stored Authentication key 0xbb72
Protocol Details
Command
Tc = 0x44
Lc = 2 + 40 + 2 + 8 + 1 + 8 + 16 + 16
Vc = I || L || D || C || A || DC || Ke || Km
where –
I= Object ID of the Authentication Key (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
DC= Delegated Capability (8 bytes)
Ke= Encryption Key (16 bytes)
Km= Mac Key (16 bytes)
PUT HMAC KEY Command
Store an HMAC Key in the device.
Shell Example
Store an HMAC Key with the binary value 666f6f in the device.
yubihsm> put hmackey 0 0 hmackey 1 sign-hmac, verify-hmac hmac-sha256 666f6f
Stored HMAC key 0x7cf2
Interactive Mode
yubihsm> put hmackey e:session, w:key_id, s:label, d:domains, c:capabilities, a:algorithm, i:key
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.label Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, sign-hmac, verify-hmac, exportable-under-wrap
Algorithm Required.
Key algorithm.
Possible Values: hmac-sha1, hmac-sha256, hmac-sha384, hmac-sha512
key Required.
The HMAC key.
Format: hex
Example
Store an HMAC Key with the binary value 666f6f in the device.
yubihsm> put hmackey 0 0 hmackey 1 sign-hmac, verify-hmac hmac-sha256 666f6f
Stored HMAC key 0x7cf2
Command Line Mode
This command is not available in command line mode.
Protocol Details
Command
Tc = 0x52
Lc = 2 + 40 + 2 + 8 + 1 + LP
Vc = I || L || D || C || A || P
where –
I= Object ID of the HMAC Key (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
P= Key (Minimum 1 byte)For HMAC-SHA1 and HMAC-SHA256: maximum 64 bytes
For HMAC-SHA384 and HMAC-SHA512: maximum 128 bytes
PUT OPAQUE Command
Stores Opaque data (like an X.509 certificate) in the device. The size of the object is currently limited to what will fit into one message to the YubiHSM 2 (2028 bytes, including the headers).
Shell Example
Store the certificate in file cert.der in the device.
yubihsm> put opaque 0 0 certificate 1 none opaque-x509-certificate cert.der
Stored Opaque object 0xe255
Interactive Mode
yubihsm> put opaque e:session, w:object_id, s:label, d:domains, c:capabilities, a:algorithm, i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.label Required.
Object label. Can be empty.
Possible Values: Maximum of 40 characters string.
domains Required.
Domains where the object will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
Capabilities Required.
Capabilities of the data
Possible Values: none, exportable-under-wrap
Algorithm Required.
Key algorithm. If
opaque-x509-certificate, the value of the object will be treated as an X509Certificate.Possible Values: opaque-data, opaque-x509-certificate
data
Opaque data value (e.g. X509Certificate).
Possible Values: Path to file or “-“ for stdin
Defaul Value: stdin
Default Format: binary (DER).
Example
Store the certificate in file cert.pem in the device.
yubihsm> put opaque 0 0 certificate 1 none opaque-x509-certificate cert.pem
Stored Opaque object 0xe255
Command Line Mode
$ yubihsm-shell -a put-opaque -i <key_id> -l <label> -d <domains> -c <capabilities> [--in <key> --informat <informat> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the asymmetric key. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.-l, –label=STRING Required.
Object label. Can be empty.
Possible Values: Maximum of 40 characters string
-d, –domains=STRING
Domains where the opaque object will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING
Capabilities of the key.
Possible Values: none, exportable-under-wrap
Default Value: none
–in=STRING
Opaque data value (e.g. X509Certificate).
Possible Values: Path to file or stdin
Default Value: stdin
Default Format: binary (DER)
–informat=ENUM
Input data format
Possible Values: PEM, binary
Example
Store the certificate in file cert.der in the device.
$ yubihsm-shell -a put-opaque -i 0 -l certificate -d 1 -A opaque-x509-certificate --in cert.der
Protocol Details
Command
Tc = 0x42
Lc = 2 + 40 + 2 + 8 + 1 + LO
Vc = I || L || D || C || A || O
where –
I= Object ID (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
O= Opaque data
PUT OTP AEAD KEY Command
Import an OTP AEAD Key used for Yubico OTP Decryption.
Shell Example
Import OTP AEAD Key with Nonce ID 0x01020304 and key value 000102030405060708090a0b0c0d0e0f (AES-128).
yubihsm> put otpaeadkey 0 0 otpaeadkey 1 decrypt-otp 0x01020304 000102030405060708090a0b0c0d0e0f
Stored OTP AEAD key 0xe34f
Interactive Mode
yubihsm> put otpaeadkey e:session, w:key_id, s:label, d:domains, c:capabilities, u:nonce_id, i:key
Parameters
session Required.
The ID of the authenticated session to send the command over. 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.label Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
Capabilities Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, decrypt-otp, create-otp-aead, randomize-otp-aead, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, exportable-under-wrap
nonce_id Required.
OTP nonce. 4 bytes.
key Required.
The AEAD key.
Format: hex
Example
Import OTP AEAD Key with Nonce ID 0x01020304 and key value 000102030405060708090a0b0c0d0e0f (AES-128).
yubihsm> put otpaeadkey 0 0 otpaeadkey 1 decrypt-otp 0x01020304 000102030405060708090a0b0c0d0e0f
Stored OTP AEAD key 0xe34f
Command Line Mode
This command is not available in command line mode.
Protocol Details
Command
Tc = 0x65
Lc = 2 + 40 + 2 + 8 + 1 + 4 + LK
Vc = I || L || D || C || A || N || K
where –
I= Object ID (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
N= Nonce ID (4 bytes)
K= Key (16, 24 or 32 bytes depending on algorithm)
PUT SYMMETRIC KEY Command
Available with firmware version 2.3.1 or later.
Import a symmetric Key into the device.
Interactive Mode
yubihsm> put symmetric e:session,w:key_id,s:label,d:domains,c:capabilities,a:algorithm,i:key
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use ‘0’ to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
label Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by,or:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by,or:with no spaces between.Possible Values: none, encrypt-ecb, decrypt-ecb, encrypt-cbc, decrypt-cbc, exportable-under-wrap
algorithm Required.
Key algorithm.
Possible Values: aes128, aes192,aes256
key Required.
Symmetric key.
Possible Values: Value of the symmetric key
Input format: HEX
Example
Store an AES128 key into the device:
yubihsm> put symmetric 0 0 aeskey 1 encrypt-cbc,decrypt-cbc aes128 0a8a7ecc862b3d42b5dc127c111da0f4
Stored symmetric key 0x71c9
Command Line Mode
$ yubihsm-shell -a put-symmetric-key -i <key_id> -l <label> -d <domains> -c <capabilities> -A <algorithm> --in <key> [--authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password will be prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the symmetric key. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal-l, –label=STRING Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string.
-d, –domains=STRING Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by,or:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by,or:with no spaces between.Possible Values: none, encrypt-ecb, decrypt-ecb, encrypt-cbc, decrypt-cbc,exportable-under-wrap
-A, –algorithm=STRING Required.
Key algorithm.
Possible Values: aes128, aes192, aes256
–in=STRING
Symmetric key.
Possible Values: Value of the symmetric key
Input format: HEX
Example
Store an AES128 key into the device:
$ yubihsm-shell -a put-symmetric-key -l aeskey -d 1 -c encrypt-cbc, decrypt-cbc -A aes128 --in 0a8a7ecc862b3d42b5dc127c111da0f4
Protocol Details
Command
Tc = 0x6d
Lc = 2 + 40 + 2 + 8 + 1 + Lk
Vc = I || L || D || C || A || K
The key parameters vary according to the chosen algorithm. Each parameter has a fixed length and the order is compulsory.
Where –
I = Object ID of the symmetric Key (2 bytes)
L = Label (40 bytes)
D = Domain (2 bytes)
C = Capability (8 bytes)
A = ALGORITHMS (1 byte)
K = The key value (16, 24 or 32 bytes)
PUT TEMPLATE Command
Stores a Template in the device. The size of the object is currently limited to what will fit into one message to the YubiHSM (2021 bytes, including the headers).
Shell Example
Store the SSH Template in file template.dat in the device.
yubihsm> put template 0 0 ssh_template 1 none template-ssh template.dat
Stored Template object 0x7b19
Interactive Mode
yubihsm> put template e:session, w:object_id, s:label, d:domains, c:capabilities, a:algorithm, i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.label Required.
Object label. Can be empty.
Possible Values: Maximum of 40 characters string
domains Required.
Domains where the object will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
Capabilities Required.
Capabilities of the data.
Possible Values: none, exportable-under-wrap
Algorithm Required.
Key algorithm.
Possible Values: template-ssh
data
Template value.
Possible Values: Path to file or “-“ for stdin
Default Value: stdin
Default Format: base64
Example
Store the SSH Template in file template.dat in the device.
yubihsm> put template 0 0 ssh_template 1 none template-ssh template.dat
Stored Template object 0x7b19
Command Line Mode
$ yubihsm-shell -a put-template -i <key_id> -l <label> -d <domains> -c <capabilities> [--in <key> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session.The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.-l, –label=STRING Required.
Object label. Can be empty.
Possible Values: Maximum of 40 characters string
-d, –domains=STRING Required.
Domains where the opaque object will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING
Capabilities of the key.
Possible Values: none, exportable-under-wrap
Default Value: none
–in=STRING
Template value.
Possible Values: Path to file or stdin
Default Value: stdin
Default Format: base64
Example
Store the SSH Template in file template.dat in the device.
$ yubihsm-shell -a put-template -i 0 -l ssh_template -d 1 -c none -A template-ssh --in template.dat
Protocol Details
Command
Tc = 0x5e
Lc = 2 + 40 + 2 + 8 + 1 + LD
Vc = I || L || D || C || A || D
where –
I= Object ID of the Template (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
D= Template data
PUT WRAP KEY Command
Import a key for wrapping into the device.
Interactive Mode
Use put wrapkey command to import AES Wrap Key and put rsa_wrapkey command to import RSA Wrap Key
$ yubihsm> put wrapkey e:session, w:key_id, s:label, d:domains, c:capabilities, c:delegated_capabilities, i:key
$ yubihsm> put rsa_wrapkey e:session, w:key_id, s:label, d:domains, c:capabilities, c:delegated_capabilities, i:key
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.label Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, wrap-data, unwrap-data, export-wrapped, import-wrapped, exportable-under-wrap
delegated_capabilities Required.
Delegated capabilities of the key. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
key Required.
The wrap key.
Default Format: hex
Example
Import an AES-128 Wrap Key able to export and import, with some Delegated Capabilities set.
yubihsm> put wrapkey 0 0 wrapkey 1 export-wrapped,import-wrapped exportable-under-wrap,sign-pkcs,sign-pss 000102030405060708090a0b0c0d0e0f
Stored Wrap key 0xaff7
Command Line Mode
Use put-wrap-key subcommand to import AES Wrap Key and put-rsa-wrapkey subcommand to import RSA Wrap Key
$ yubihsm-shell -a put-wrap-key -i <key_id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> --in <key> [ --authkey <authKeyID> -p <password> ]
$ yubihsm-shell -a put-rsa-wrapkey -i <key_id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> --in <key> [ --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.-l, –label=STRING Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
-d, –domains=STRING Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, wrap-data, unwrap-data, export-wrapped, import-wrapped, exportable-under-wrap
–delegated=STRING Required.
Delegated capabilities of the key. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
–in=STRING Required.
The wrap key.
Possible Values: Path to file or stdin
Default Value: stdin
Default Format: hex
Example
Import an AES-128 Wrap Key able to export and import, with some Delegated Capabilities set.
$ yubihsm-shell -a generate-wrap-key -i 0 -l wrapkey -d 1 -c export-wrapped,import-wrapped --delegated exportable-under-wrap,sign-pkcs,sign-pss --in wrap.key
Stored Wrap key 0xaff7
Protocol Details
Command
Tc = 0x4c
Lc = 2 + 40 + 2 + 8 + 1 + 8 + LW
Vc = I || L || D || C || A || DC || W
where –
I= Object ID (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
DC= Delegated Capability (8 bytes)
W= Wrap Key (16, 24 or 32, 256, 384, 512 bytes)For AES128_CCM_WRAP: 16 bytes
For AES192_CCM_WRAP: 24 bytes
For AES256_CCM_WRAP: 32 bytes
For RSA2048: 256 bytes
For RSA3072: 384 bytes
For RSA4096: 512 bytes
PUT PUBLIC WRAP KEY Command
Import a public RSA Wrap Key exporting wrapped objects.
Interactive Mode
$ yubihsm> put pub_wrapkey e:session, w:key_id, s:label, d:domains, c:capabilities, c:delegated_capabilities, i:key=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.label Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
domains Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
capabilities Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, wrap-data, unwrap-data, export-wrapped, import-wrapped, exportable-under-wrap
delegated_capabilities Required.
Delegated capabilities of the key. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
key Required.
A Public RSA key.
Default Format: PEM
Example
Import the public RSA key from rsa2048_pubkey.pem as a Public Wrap Key able to export and import, with some Delegated Capabilities set.
$ yubihsm> put pub_wrapkey 0 0 rsa_wrapkey 1 export-wrapped,import-wrapped exportable-under-wrap,sign-pkcs,sign-pss rsa2048_pubkey.pem
Stored Wrap key 0xadf8
Command Line Mode
$ yubihsm-shell -a put-public-wrapkey -i <key_id> -l <label> -d <domains> -c <capabilities> --delegated <delegated_capabilities> --in <key> [ --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID. Use
0to generate Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.-l, –label=STRING Required.
Key label. Can be empty.
Possible Values: Maximum of 40 characters string
-d, –domains=STRING Required.
Domains where the key will be accessible. Use
allto indicate all domains. Multiple domains can be separated by comma,or colon:with no spaces between.Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16
-c, –capabilities=STRING Required.
Capabilities of the key. Use
noneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, wrap-data, unwrap-data, export-wrapped, import-wrapped, exportable-under-wrap
–delegated=STRING Required.
Delegated capabilities of the key. Use
allto include all capabilities. Usenoneto include no capability. Multiple capabilities can be separated by comma,or colon:with no spaces between.Possible Values: none, all, change-authentication-key, create-otp-aead, decrypt-oaep, decrypt-otp, decrypt-pkcs, delete-asymmetric-key, delete-authentication-key, delete-hmac-key, delete-opaque, delete-otp-aead-key, delete-template, delete-wrap-key, derive-ecdh, export-wrapped, exportable-under-wrap, generate-asymmetric-key, generate-hmac-key, generate-otp-aead-key, generate-wrap-key, get-log-entries, get-opaque, get-option, get-pseudo-random, get-template, import-wrapped, put-asymmetric-key, put-authentication-key, put-mac-key, put-opaque, put-otp-aead-key, put-template, put-wrap-key, randomize-otp-aead, reset-device, rewrap-from-otp-aead-key, rewrap-to-otp-aead-key, set-option, sign-attestation-certificate, sign-ecdsa, sign-eddsa, sign-hmac, sign-pkcs, sign-pss, sign-ssh-certificate, unwrap-data, verify-hmac, wrap-data
–in=STRING Required.
The file containing an RSA public key.
Possible Values: Path to file or stdin
Default Value: stdin
Default Format: PEM
Example
Import the public RSA key from rsa2048_pubkey.pem as a Public Wrap Key able to export and import, with some Delegated Capabilities set.
$ yubihsm-shell -a put-public-wrapkey -i 0 -l wrapkey -d 1 -c export-wrapped,import-wrapped --delegated exportable-under-wrap,sign-pkcs,sign-pss --in rsa2048_pubkey.pem
Stored Wrap key 0xadf8
Protocol Details
Command
Tc = 0x73
Lc = 2 + 40 + 2 + 8 + 1 + 8 + LN
Vc = I || L || D || C || A || DC || N
where –
I= Object ID (2 bytes)
L= Label (40 bytes)
D= Domain (2 bytes)
C= Capability (8 bytes)
A= ALGORITHMS (1 byte)
DC= Delegated Capability (8 bytes)
N= RSA public key (256, 384 or 512 bytes)For RSA2048: 256 bytes
For RSA3072: 384 bytes
For RSA4096: 512 bytes
RANDOMIZE OTP AEAD Command
Create a new OTP AEAD using random data for key and private ID.
Shell Example
Generate a new OTP AEAD using OTP AEAD Key 0xc5f4 and put the result in file aead.
yubihsm> otp aead_random 0 0xc5f4 aead
Interactive Mode
yubihsm> otp aead_random e:session, w:key_id, F:aead
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID of an OTP AEAD key. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
aead Required.
The generated OTP AEAD.
Possible Values: Path to file or “-“ for stdout
Default Value: stdout
Example
Generate a new OTP AEAD using OTP AEAD Key 0xc5f4 and put the result in file aead.
yubihsm> otp aead_random 0 0xc5f4 aead
Command Line Mode
$ yubihsm-shell -a randomize-otp-aead -i <key_id> [--out <aead> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of an OTP AEAD key. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–out=STRING
The generated OTP AEAD.
Possible Values: Path to file or stdout
Default Value: stdout
Example
Generate a new OTP AEAD using OTP AEAD Key 0xc5f4 and put the result in file aead.
$ yubihsm-shell -a randomize-otp-aead -i 0xc5f4 --out aead
RESET DEVICE Command
Resets and reboots the device, deletes all Objects and restores the default Options and Authentication Key.
Interactive Mode
yubihsm> reset e:session
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
Command Line Mode
$ yubihsm-shell -a reset [ --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
REWRAP OTP AEAD Command
Re-encrypt a Yubico OTP AEAD from one OTP AEAD Key to another OTP AEAD Key.
Shell Example
N/A
Interactive Mode
yubihsm> otp rewrap e:session, w:id_from, w:id_to, i:aead_in, F:aead_out
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
id_from Required.
Object ID of the OTP AEAD used to unwrap. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
id_to Required.
Object ID of the OTP AEAD used to wrap. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
aead_in Required.
OTP AEAD to unwrap.
Default Format: binary
aead_out Required.
OTP AEAD to wrap
Command Line Mode
This command is not available in command line mode.
SESSION MESSAGE Command
Sends a wrapped command for a previously established session. The command is encrypted and authenticated.
Protocol Details
Command
T~c~ = 0x05
L~c~ = 1 + L~inner_c~ + 8
V~c~ = S | | I~c~ | | M~c~
Where –
S = Session ID (1 byte)
L~inner_c/inner_r~ = Length of the encrypted inner command / response (2 bytes)
M~c/r~ = CMAC of the outer command / response (8 bytes)
Response
T~r~ = 0x85
L~r~ = 1 + L~inner_r~ + 8
V~r~ = S | | I~r~ | | M~r~
SET INFORMAT Command
Set global input format. When set to something other than default, all future input is expected to have the set format.
Interactive Mode
yubihsm> set informat I:format
Parameters
format Required.
Input format.
defaultresets the default expected input format, which can be different for different commands.Possible Values: default, base64, binary, PEM, password, hex, ASCII
Command Line Mode
Setting global input format is not possible in command line mode. However, individual commands can be set to expect a certain input format by using the --informat=ENUM flag.
SET LOG INDEX Command
Inform the device what the last extracted log entry is so logs can be reused. Mostly of practical use when forced auditing is enabled.
Interactive Mode
yubihsm> audit set e:session, w:index
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
index Required.
Log index.
Possible Values: 1-60
Command Line Mode
$ yubihsm-shell -a set-log-index --log-index <index> [ --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
–log-index=INT Required.
Log index.
Possible Values: 1-60
Example
Set log index 41 as the last extracted entry.
$ yubihsm-shell -a set-log-index --log-index 41
SET OPTION Command
Set device-global options that affect general behavior. Each invocation of this command sets a single option, which is represented as a TAG-LENGTH-VALUE (TLV).
Shell Example
Turn off audit logging for Sign HMAC (command 53) and Verify HMAC (command 5c).
yubihsm> put option 0 command_audit 53005c00
Interactive Mode
yubihsm> put option e:session, o:option, i:data
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
option Required.
Device option name.
fips-modeoption is only applicable in FIPS compatible YubiHSMs.Possible Value: algorithm-toggle, command-audit, fips-mode, force-audit
data Required.
Value of option.
Default Input Format: hex
Example
Turn off audit logging for Sign HMAC (command 53) and Verify HMAC (command 5c).
yubihsm> put option 0 command-audit 53005c00
Command Line Mode
$ yubihsm-shell -a put-option --opt-name <option> --opt-value <value> [ --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
–opt-name=STRING Required.
Device option name.
fips-modeoption is only applicable in FIPS compatible YubiHSMs.Possible Values: algorithm-toggle, command-audit, fips-mode, force-audit
–opt-value=STRING Required.
Device option value.
Default input format: hex
Example
Set log index 41 as the last extracted entry.
$ yubihsm-shell -a put-option --opt-name command-audit --opt-value 53005c00
Protocol Details
Command
Tc = 0x4f
Lc = 3 + Lo
Vc = TO
where –
To= The TLV encoding of the selected option
Lo= The option-specific length in bytes
The options currently supported are the following:
TAGis 1 byte
LENGTHis 2 bytes
VALUEis Lo bytes
Tags.
force-audit = 0x01
command-audit = 0x03
algorithm-toggle = 0x4 (>=2.2.0)
fips-mode = 0x05 (>=2.2.0)
Values.
OFF = 0x00 (Disabled)
ON = 0x01 (Enabled)
FIX = 0x02 (Enabled, only possible to turn off through factory reset)
The defined options are as follows:
With Force audit set, the device will refuse operations as long as the Logs Store is full. It takes a 1 byte value option.
Command audit can be used to toggle whether a specific command should be logged, this takes tuples of command number and option value.
Algorithm toggle allows the user to selectively disable individual algorithms for the whole device. This option can only be toggled on a freshly reset device, i.e. one with only the default Authentication Key. This takes a tuple of algorithm number and option value.
FIPS mode is only available on FIPS devices and can only be toggled on a freshly reset device, i.e. one with only the default Authentication Key present. It disables algorithms that are not allowed by FIPS 140. This step is required as part of setting the device in the approved mode of operation, together with deleting the default Authentication Key (see Section 3.2 of the YubiHSM FIPS Security Policy).
Response
Tr = 0xcf
Lr = 0
Vr = Ø
SET OUTFORMAT Command
Set global output format. When set to something other than default, all future output will be in the set format.
Interactive Mode
yubihsm> set outformat I:format
Parameters
format Required.
Output format.
defaultresets the default output format, which can be different for different commandsPossible Values: default, base64, binary, PEM, password, hex, ASCII
Command Line Mode
Setting global output format is not possible in command line mode. However, individual commands can be set to output in a certain format by using the --outformat=ENUM flag.
SIGN ATTESTATION CERTIFICATE Command
Get attestation of an Asymmetric Key, output is an X.509 certificate.
Shell Example
Attest Asymmetric Key 0x79c3 using attestation key 0 (builtin).
yubihsm> attest asymmetric 0 0x79c3 0
-----BEGIN CERTIFICATE-----
MIIDeTCCAmGgAwIBAgIQaa8FkvRhqntp5HjyyCfilzANBgkqhkiG9w0BAQsFADAn
MSUwIwYDVQQDDBxZdWJpSFNNIEF0dGVzdGF0aW9uICgxMjM0NTYpMCAXDTE3MDEw
MTAwMDAwMFoYDzIwNzExMDA1MDAwMDAwWjAoMSYwJAYDVQQDDB1ZdWJpSFNNIEF0
dGVzdGF0aW9uIGlkOjB4NzljMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoC
ggEBAMYpAzHar0syanQEiRqWy8WDO5qETjDulo2txNBDwyMCNgeEYzo/uglUXLEm
Zj6Dd8EcdY9upHoqVpLduB+GIt+UEq5DeMN5Rzj2QZ/lQMELMdaD9ODc707aPvKT
/oAuj1aZ89vfg7jEVWBTPWquyFaxaCBoz8WWta9j5JxRppQpR27ub43950fX3wpW
btvlNLMx0QAQdDqEm2V3TEhnbo6T5XsgC78OdOikyJw2TP062rQXSY7GRuXob/Qa
INsJRXbbydqUXDHFNq8GnSkL8dHsNdf7bOSdAV6Vlw30JFbJ2uoW2EkGmF9qYWnt
EVyyPMMQwF09r9HVpLF83TBaYoMCAwEAAaOBnTCBmjATBgorBgEEAYLECgQBBAUE
AwIAADATBgorBgEEAYLECgQCBAUCAx6EgDASBgorBgEEAYLECgQDBAQDAgABMBMG
CisGAQQBgsQKBAQEBQMDAAABMBkGCisGAQQBgsQKBAUECwMJAAAAAAAAAARAMBIG
CisGAQQBgsQKBAYEBAICecMwFgYKKwYBBAGCxAoECQQIDAZyc2FrZXkwDQYJKoZI
hvcNAQELBQADggEBABRReYze+KRfevrgyI3C2aLAWSiQRjJ6vvaP1Fh4bOw4X2HC
rLAI150h4O5eH/aXVNv+368FWlQhcY68jKDgDoeckrlt9thFxaphasd/Wt1Pbqzj
trnEillYjjP6rddyCR1yitmnQ3Qnsk3w1mTE/AtzmDOi7V/wNymilB79OFDGmB6P
d1VI7zGUHtLlj1qeyY4/ETqKuPDzZY5RUPYrO8/iPzy64AdtDXt1e39n9pTcohp2
PSQQe36gU7vt9+5SebEj0CF/qTk317L1R42TfeHFSJlgBTHSWcuvDORNJxDHTcco
bI+wE2dCcnjyLU9dr5tkNsD3k5pscuTmpBGFDlg=
-----END CERTIFICATE-----
SIGN ECDSA Command
Computes a digital signature using ECDSA on the provided data.
Shell Example
Sign data in file data using key 0x52b6 and put the result in file sig.
yubihsm> sign ecdsa 0 0x52b6 ecdsa-sha256 data sig
Protocol Details
Command
Tc = 0x56
Lc = 2 + LD
Vc = I || D
where –
I= Object ID of the Asymmetric Key (2 bytes)
D= HThe DSI for ECDSA is a possibly zero-left-padded hash of the data,H.
Response
Tr = 0xd6
Lr = LDS
Vr = DS
where –
DS= Resulting signatureThe length ofDS,LDS, depends on the ALGORITHMS used and equals the length of the signature plus its DER encoding.
SIGN EDDSA Command
Computes a digital signature using EdDSA on the provided data.
Example
Perform an EdDSA signature with key 0xddf6 of the content of file data:
yubihsm> sign eddsa 0 0xddf6 ed25519 data
wZljrOstOLPuMHGrXDnpAb5Wxo79+wX/vQkb/6K34tOd8se
QfLNRVTonfErttkWUAz/UlNtaG4XJYnY8vabCQ==
Protocol Details
Command
T~c~ = 0x6a
L~c~ = 2 + L~D~
V~c~ = I \|\| D
Where –
I = Object ID of the Asymmetric Key (2 bytes)
The DSI for EdDSA is the raw data D.
DSI = D
For a given DSI, the command will generate a digital signatureDS. The length ofDS,L~DS~, depends on the Algorithm used. At this time only Ed25519 is implemented.
DS = EdDSA(DSI). Key is omitted
L~DS~ = 0x0040 bytes
SIGN HMAC Command
Perform an HMAC operation in device and return the result.
Shell Example
Perform an HMAC operation using the HMAC Key 0x7cf2.
yubihsm> hmac 0 0x7cf2 666f6f626172
4c17e17300a51a3f8aeeba131e9c680e4e40b429aa1d547807efd8e3d95ccd39
SIGN PKCS1 Command
Computes a digital signature using RSA-PKCS1v1.5 on the provided data.
Shell Example
Sign the data in the file test using rsa-pkcs1-sha256.
yubihsm> sign pkcs1v1_5 0 0x1e15 rsa-pkcs1-sha256 test
eu9HQceSs0zsUogVloovRRcDGtkBj5AIp2Nnk6LWT4KbQZX8ac+vmFtVotjDIF9PkQ9MA8K
sfUGvXAxpnvUyin3BjGvzENu5XRi+ZOGP4m8777zbDi1v7FKQSx8/KdZf4tulIsL4rM4M+uH
/QoQ83vWty4c63QjcSlZJQDsdHn9r3E5or3QgBo06yK2Rd8W3WYGloSPvDaGu7L87CDFy
MniAQB//Sw7bYr4hbVpKIWi6q4VPhBKdaB6+FzTmYrqsSv1vwek0V4LbvyelTHlh9PpFuSF
ZeGJ/i1gkIeSO2XlKNLa4+AO+H+TYUOP3b6Qlhs3f7e4AFFWKE6lPpDHJA==
Interactive Mode
yubihsm> sign pkcs1v1_5 e:session, w:key_id, a:algorithm, i:data=-, F:out=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID of the asymmetric key to sign with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Algorithm Required.
Signing algorithm.
Possible Values: rsa-pkcs1-sha1, rsa-pkcs1-sha256, rsa-pkcs1-sha384, rsa-pkcs1-sha512
data
Data to sign.
Possible Values:Path to file or “-“ for stdin
Default Value: stdin
Default Input Format: binary
out
Signed data.
Possible Values: Path to file or “-“ for stdout
Default Value: stdout
Default Input Format: PEM
Example
Sign the data in the file test using rsa-pkcs1-sha256.
yubihsm> sign pkcs1v1_5 0 0x1e15 rsa-pkcs1-sha256 test
eu9HQceSs0zsUogVloovRRcDGtkBj5AIp2Nnk6LWT4KbQZX8ac+vmFtVotjDIF9PkQ9MA8KlsfUGvXAxpnvUyin3BjGvzENu5XRi+ZOGP4m8777zbDi1v7FKQSx8/KdZf4tulIsL4rM4M+uH/QoQ83vWty4c63QjcSlZJQDsdHn9r3E5or3QgBo06yK2Rd8W3WYGloSPvDaGu7L87CDFyMniAQB//Sw7bYr4hbVpKIWi6q4VPhBKdaB6+FzTmYrqsSv1vwek0V4LbvyelTHlh9PpFuSFZeGJ/i1gkIeSO2XlKNLa4+AO+H+TYUOP3b6Qlhs3f7e4AFFWKE6lPpDHJA==
Command Line Mode
$ yubihsm-shell -a sign-pkcs1v15 -i <key_id> -A <algorithm> [--in <data> --informat <informat> --out <out> --outformat <outformat> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the asymmetric key to sign with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-A, –algorithm=STRING Required.
Signing algorithm.
Possible Values: rsa-pkcs1-sha1, rsa-pkcs1-sha256, rsa-pkcs1-sha384, rsa-pkcs1-sha512
–in=STRING
Data to sign.
Possible Values: Path to file or stdin
Default Value: stdin
Default Input Format: binary
–informat=ENUM
Input data format.
Possible Values: binary, base64, hex, PEM
–out=STRING
Signed data.
Possible Values: Path to file or stdout
Default Value: stdout
Default Output Format: PEM
–outformat=ENUM
Output data format.
Possible Values: binary, base64, hex, PEM
Example
Sign the data in the file test using rsa-pkcs1-sha256.
$ yubihsm-shell -a sign-pkcs1v15 -i 0x1e15 -A rsa-pkcs1-sha256 --in test
eu9HQceSs0zsUogVloovRRcDGtkBj5AIp2Nnk6LWT4KbQZX8ac+vmFtVotjDIF9PkQ9MA8KlsfUGvXAxpnvUyin3BjGvzENu5XRi+ZOGP4m8777zbDi1v7FKQSx8/KdZf4tulIsL4rM4M+uH/QoQ83vWty4c63QjcSlZJQDsdHn9r3E5or3QgBo06yK2Rd8W3WYGloSPvDaGu7L87CDFyMniAQB//Sw7bYr4hbVpKIWi6q4VPhBKdaB6+FzTmYrqsSv1vwek0V4LbvyelTHlh9PpFuSFZeGJ/i1gkIeSO2XlKNLa4+AO+H+TYUOP3b6Qlhs3f7e4AFFWKE6lPpDHJA==
SIGN PSS Command
Computes a digital signature using RSA-PSS on the provided data.
Shell Example
Sign what is in file data using key 0x79c3 and put the resulting signature in sig.
yubihsm> sign pss 0 0x79c3 rsa-pss-sha256 data sig
Interactive Mode
yubihsm> sign pss e:session, w:key_id, a:algorithm, i:data=-, F:out=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID of the asymmetric key to sign with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Algorithm Required.
Signing algorithm.
Possible Values: rsa-pss-sha1, rsa-pss-sha256, rsa-pss-sha384, rsa-pss-sha512
data
Data to sign.
Possible Values: Path to file or “-“ for stdin
Devault Value: stdin
Default Input Format: binary
out
Signed data.
Possible Values: Path to file or “-“ for stdout
Default Value: stdout
Default Input Format: PEM
Example
Sign what is in file data using key 0x79c3 and put the resulting signature in sig.
yubihsm> sign pss 0 0x79c3 rsa-pss-sha256 data sig
Command Line Mode
$ yubihsm-shell -a sign-pss -i <key_id> -A <algorithm> [--in <data> --informat <informat> --out <out> --outformat <outformat> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified
-i, –object-id=SHORT Required.
Object ID of the asymmetric key to sign with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-A, –algorithm=STRING Required.
Signing algorithm.
Possible Values: rsa-pss-sha1, rsa-pss-sha256, rsa-pss-sha384, rsa-pss-sha512
–in=STRING
Data to sign.
Possible Values: Path to file or stdin
Default Value: stdin
Default Input Format: binary
–informat=ENUM
Input format.
Possible Values: binary, base64, hex, PEM
–out=STRIN
Signed data.
Possible Values: Path to file or stdout
Default Value: stdout
Default Output Format: PEM
–outformat=ENUM
Output format.
Possible Values: binary, base64, hex, PEM
Example
Sign what is in file data using key 0x79c3 and put the resulting signature in sig.
$ yubihsm-shell -a sign-pss -i 0x79c3 -A rsa-pss-sha256 --in data --out sig
Protocol Details
Command
Tc = 0x55
Lc = 2 + 1 + 2 + LD
Vc = I || M || S || D
where –
I= Object ID of the Asymmetric Key (2 bytes)
M= Hash ALGORITHMS to use for MGF1
S= Salt len (2 bytes)
D= Hashed data (20, 32, 48 or 64 bytes)The DSI of EMSA-PSS is as defined in RFC 3447.
DSI= EMSA-PSS-ENCODE(M, emBits, Hash, MGF, sLen).
Hashis a supported hash Algorithm
MGFis a supported masking function
sLenis the length of the SaltThe DSI is generated internally and only the Hash of the data and the Salt length are provided.
SIGN SSH CERTIFICATE Command
Produce an SSH Certificate signature. The certificate can then be used to login to hosts.
Shell Example
Produce a new SSH Certificate.
yubihsm> certify 0 0xabcd 0x1234 rsa-pkcs-sha256 req.dat cert.dat
Interactive Mode
yubihsm> certify e:session, w:key_id, w:template_id, a:algorithm, i:infile=-, F:outfile=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID of the asymmetric key to sign with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
template_id Required.
Template Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
algorithm Required.
Signing algorithm.
Possible Values: rsa-pkcs1-sha1, rsa-pkcs1-sha256, rsa-pkcs1-sha384, rsa-pkcs1-sha512
data
Certificate request.
Possible Values: Path to file or “-“ for stdin
Default Value: stdin
Default Input Format: binary
out
Signed SSH certificate.
Possible Values: Path to file or “-“ for stdout
Default Value: stdout
Default Input Format: binary
Example
Produce a new SSH Certificate.
yubihsm> certify 0 0xabcd 0x1234 rsa-pkcs-sha256 req.dat cert.dat
Command Line Mode
$ yubihsm-shell -a sign-ssh-certificate -i <key_id> --template-id <template_id> -A <algorithm> [--in <data> --informat <informat> --out <out> --authkey <authKeyID> -p <password> ]
Parameters
–authkey=INT
The ObjectID of the authentication key used to open a session. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
Default Value: 1
-p, –password=STRING Required.
The password to authentication key used to open a session. The password is prompted for if not specified.
-i, –object-id=SHORT Required.
Object ID of the asymmetric key to sign with. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
–template-id=INT Required.
Template Object ID. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
-A, –algorithm=STRING Required.
Signing algorithm.
Possible Values: rsa-pkcs1-sha1, rsa-pkcs1-sha256, rsa-pkcs1-sha384, rsa-pkcs1-sha512
–in=STRING
Certificate request
Possible Values: Path to file or stdin
Default Value: stdin
Default Input Format: binary
–informat=ENUM
Input data format.
Possible Values: binary, base64, hex, PEM
–out=STRING
Signed SSH certificate.
Possible Values: Path to file or stdout
Default Value: stdout
Default Output Format: binary
Example
Produce a new SSH Certificate.
$ yubihsm-shell -a sign-ssh-certificate -i 0xabcd --template-id 0x1234 -A rsa-pkcs-sha256 --in req.dat --out cert.dat
Protocol Details
Command
Tc = 0x5d
Lc = 2 + 2 + 1 + 4 + 256 + LR
Vc = I || T || A || N || S || R
Sign and SSH Certificate by using the given Asymmetric Key and SSH Template.
where –
I = Object ID of the Asymmetric Key (2 bytes)
T = Object ID of the SSH Template (2 bytes)
A = ALGORITHMS (1 byte)
N = Timestamp with the definition of Now (4 bytes)
S = Signature over the request and timestamp (256 bytes)
R = Request (LR bytes)
UNWRAP DATA Command
Decrypt (unwrap) data using a Wrap Key.
Shell Example
yubihsm> decrypt aesccm 0 0x5b3a MRkj6B0AAAAAAAAAAoO4dkIeAYoPvwTV/M/JX1dwKnLqnERO1hSW4wPS
Hello world!
Interactive Mode
yubihsm> decrypt aesccm e:session, w:key_id, i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Required.
Object ID of the wrap key. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
data
Data to decrypt/unwrap.
Possible Values: Path to file or “-“ for stdin
Default Value: stdin
Default Input Format: base64
Example
yubihsm> decrypt aesccm 0 0x5b3a MRkj6B0AAAAAAAAAAoO4dkIeAYoPvwTV/M/JX1dwKnLqnERO1hSW4wPS
Hello world!
Command Line Mode
This command is not available in command line mode.
WRAP DATA Command
Encrypt (wrap) data using a Wrap Key.
Shell Example
Using Wrap Key 0x5b3a encrypt the string Hello world!.
yubihsm> encrypt aesccm 0 0x5b3a "Hello world!"
MRkj6B0AAAAAAAAAAoO4dkIeAYoPvwTV/M/JX1dwKnLqnERO1hSW4wPS
Interactive Mode
yubihsm> encrypt aesccm e:session, w:key_id, i:data=-
Parameters
session Required.
The ID of the authenticated session to send the command over.
Possible Values: 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15
key_id Requiredc.
Object ID of the wrap key. Object ID is a 2 bytes integer. Can be specified in hex or decimal.
data
Data to encrypt/wrap.
Possible Values: Path to file or “-“ for stdin
Default Value: stdin
Default Input Format: binary
Example
Using Wrap Key 0x5b3a encrypt the string Hello world!.
yubihsm> encrypt aesccm 0 0x5b3a "Hello world!"
MRkj6B0AAAAAAAAAAoO4dkIeAYoPvwTV/M/JX1dwKnLqnERO1hSW4wPS
Command Line Mode
This command is not available in command line mode.
Protocol Details
Command
Tc = 0x68
Lc = 2 + LD
Vc = I || D
where –
I= Object ID of the Wrap Key (2 bytes)
D= Data to be wrapped
Response
Tr = 0xe8
Lr = 13 + LD + 16
Vr = N || D || M
where –
N= Nonce (13 bytes)
D= Wrapped data (L~W~ = 1 + L~D~ bytes)The wrapped data includes a leading encrypted nul byte that is added automatically by the YubiHSM2. This byte is checked by UNWRAP DATA and therefore must be added if manually generating an encrypted message offline.
M= Mac (16 bytes)