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)

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 password format 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 stdin

    Default 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)

Response

Tr = 0xec
Lr = 2
Vr = I

Where –

I = Object ID of the changed Object (2 bytes)

Note

This command returns ERROR_INV_DATA if Key is not a valid EC-P256 key.

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)

Response

Tr = 0xec
Lr = 2
Vr = I

where –

I = Object ID of the changed Object (2 bytes)

CLOSE SESSION Command

Close the current Session and release it for re-use. This device must be sent over an authenticated session.

Shell Example

Close Session 0.

yubihsm> session close 0

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

Example

Close Session 0.

yubihsm> session close 0

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.

Protocol Details

Command

Tc = 0x40
Lc = 0
Vc = Ø

Response

Tr = 0xc0
Lr = 0
Vr = Ø

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.

Protocol Details

Command

Tc = 0x61
Lc = 24
Vc = I || K || P

where –

I = Object ID of the OTP AEAD Key (2 bytes)

K = OTP Key (16 bytes)

P = OTP Private ID (6 bytes)

Response

Tr = 0xe1
Lr = LA
Vr = A

where –

A = Nonce concatenated with AEAD (36 bytes)

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

Protocol Details

Command

Tc = 0x71
Lc = 2 + 16 + LE
Vc = I || V || E

Where –

I = Object ID of the symmetric key (2 bytes)

V = Encryption initialization vector (IV) in HEX (16 bytes)

E = Data to decrypt

Response

Tr = 0xf1
Lr = LD
Vr = D

Where –

D = Decrypted data

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

Protocol Details

Command

Tc = 0x6f
Lc = 2 + LE
Vc = I || E

Where –

I = Object ID of the symmetric key (2 bytes)

D = Data to decrypt

Response

Tr = 0xef
Lr = LD
Vr = D

Where –

D = Decrypted data

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)

Response

T~r~ = 0xc9
L~r~ = L~R~
V~r~ = R

Where –

R = Decrypted data with OAEP padding removed

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.

Response

Tr = 0xc9
Lr = LR
Vr = R

where –

R = Decrypted data with padding removed.

DELETE OBJECT Command

Delete an Object in the device.

Shell Example

Delete Asymmetric Key 0x52b6.

yubihsm> delete 0 0x52b6 asymmetric-key

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

Example

Delete Asymmetric Key 0x52b6.

yubihsm> delete 0 0x52b6 asymmetric-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

Example

Delete Asymmetric Key 0x52b6.

$ yubihsm-shell -a delete-object -i 0x52b6 -t asymmetric-key

Protocol Details

Command

Tc = 0x58
Lc = 2 + 1
Vc = I || T

where –

I = Object ID (2 bytes)

T = Type, Objects (1 byte)

Response

Tr = 0xd8
Lr = 0
Vr = Ø

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

Protocol Details

Command

Tc = 0x57
Lc = 2 + LD
Vc = K || D

where –

I = Object ID of the Asymmetric Key (2 bytes)

D = Uncompressed public key to perform the exchange with (57, 65, 97, 129 or 133 bytes)

Response

Tc = 0xd7
Lc = LX
Vc = X

where –

X = X coordinate of the completed key exchange

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.

Protocol Details

Command

Tc = 0x01
Lc = LE
Vc = E

where –

E = Data to echo (1-2021 bytes)

Response

Tr = 0x81
Lr = LE
Vr = E

where –

E = Data to echo (1-2021 bytes)

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

Protocol Details

Command

Tc = 0x72
Lc = 2 + 16 + LD
Vc = I || IV || D

Where –

I = Object ID of the Asymmetric Key (2 bytes)

IV = Encryption initialization vector (IV) in HEX (16 bytes)

D = Data to encrypt (multiple of 16 bytes)

Response

Tr = 0xf2
Lr = LE
Vr = E

Where –

E = Encrypted data

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

Protocol Details

Command

Tc = 0x70
Lc = 2 + LD
Vc = I || D

Where –

I = Object ID of the symmetric Key (2 bytes)

D = Data to encrypt (multiple of 16 bytes)

Response

Tr = 0xf0
Lr = LE
Vr = E

Where –

E = Encrypted data

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

Protocol Details

Command

Tc = 0x4a
Lc = 2 + 1 + 2 /{ + 1 /}
Vc = Iw || T || Io /{ || S /}

where –

Iw = Object ID of Wrap Key to use (2 bytes)

T = Type, Objects of Object to wrap (1 byte)

Io = Object ID of Object to wrap (2 bytes)

S = 1 to include seed when exporting ED25519 key, 0 otherwise. Optional with firmware 2.4 or higher (1 byte)

Response

Tr = 0xca
Lr = 13 + LR
Vr = N || R

where –

N = Nonce used for this wrap (13 bytes)

R = Wrapped data (Length dependent on object)

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)

Response

Tr = 0xf6
Lr = LR
Vr = R

where –

R = RSA wrapped data (Length dependent on object)

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)

Response

Tr = 0xf4
Lr = LR
Vr = R

where –

R = RSA wrapped key (Length dependent on key)

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 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 Value: Maximum of 40 characters string.

  • domains Required.

    Domains where the key will be accessible. Use all to 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 none to 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 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 Maximum of 40 characters string. Can be empty.

  • -d, –domains=STRING Required.

    Domains where the key will be accessible. Use all to 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 none to 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 –

IObject ID of the Asymmetric Key (2 bytes)

LLabel (40 bytes)

DDomain (2 bytes)

CEffective Capabilities (Tying It All Together) (8 bytes)

AALGORITHMS (1 byte)

Response

Tr = 0xc6
Lr = 2
Vr = I

where –

IObject ID of the created Asymmetric Key (2 bytes)

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 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 all to 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 none to 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 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 all to 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 none to 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 –

IObject ID of the HMAC Key (2 bytes)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (1 byte)

Response

Tr = 0xda
Lr = 2
Vr = I

where –

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 0 to 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 all to 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 none to 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 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.

    Possible Values: all,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16

    Use all to 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 none to 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 –

IObject ID of the OTP AEAD Key (2 bytes)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (1 byte)

N = Nonce ID (4 bytes)

Response

Tr = 0xe6
Lr = 2
Vr = I

where –

I = Object ID of the created OTP AEAD Key (2 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 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 all to 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 none to include no capability. Multiple capabilities can be separated by , or : with no spaces between

    Possible 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 all to 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 none to 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

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)

Response

Tr = 0xee
Lr = 2
Vr = I

Where –

I = Object ID of the created symmetric Key (2 bytes)

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 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 all to 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 none to 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 all to include all capabilities. Use none to 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 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 all to 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 none to 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 all to include all capabilities. Use none to 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 –

IObject ID of the Wrap Key (2 bytes)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (1 byte)

DC = Delegated Capability (8 bytes)

Response

Tr = 0xdb
Lr = 2
Vr = I

where –

I = Object ID of created Wrap Key (2 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

Command

Tc = 0x4e
Lc = 2 + 1
Vc = I || T

where –

I = Object ID (2 bytes)

T = Type, Objects (1 byte)

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

Protocol Details

Command

Tc = 0x43
Lc = 2
Vc = I

where –

I = Object ID (2 bytes)

Response

Tr = 0xc3
Lr = LD
Vr = D

where –

D = Data

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-mode option 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

Protocol Details

Command

Tc = 0x50
Lc = 1
Vc = T

where –

T = The tag of the selected option (1 byte)

Response

Tr = 0xd0
Lr = LO
Vr = O

where –

O = The option-specific value (LO bytes)

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

Protocol Details

Command

Tc = 0x51
Lc = 2
Vc = B

where –

B = Number of pseudo-random bytes to extract (2 bytes)

Response

Tr = 0xd1
Lr = B
Vr = R

where –

R = Random data (B bytes)

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

Command

Tc = 0x54
Lc = 2 | /{ + 1 /}
Vc = I /{ || T /}

where –

I = Object ID (2 bytes)

T = Type, Objects (1 byte)

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

Protocol Details

Command

Tc = 0x5f
Lc = 2
Vc = I

where –

I = Object ID of the Template to retrieve (2 bytes)

Response

Tr = 0xdf
Lr = LD
Vr = D

where –

D = Data

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

Protocol Details

Command

Tc = 0x4b
Lc = 2 + 13 + LO
Vc = I || N || O

where –

I = Object ID of the Wrap Key (2 bytes)

N = Nonce associated with this wrapped Object (13 bytes)

O = Wrapped Objects (Length dependant on Object)

Response

Tc = 0xcb
Lc = 3
Vc = T || I

where –

T = Type, Objects of imported Object (1 byte)

I = Object ID of imported Object (2 bytes)

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)

Response

Tc = 0xf7
Lc = 3
Vc = T || I

where –

T = Type, Objects of imported Object (1 byte)

I = Object ID of imported Object (2 bytes)

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 0 to 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 all to 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 all to include all capabilities. Use none to 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 0 to 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 all to 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 all to include all capabilities. Use none to 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)

Response

Tc = 0xf5
Lc = 3
Vc = T || I

where –

T = Type, Objects of imported Object (1 byte)

I = Object ID of imported Object (2 bytes)

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. 0 returns all Object IDs. Object ID is a 2 bytes integer. Can be specified in hex or decimal.

    Default Value: 0

  • Type

    Object type. any returns 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. all returns 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. all returns 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. any returns 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. 0 returns 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 any to 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 any to 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

Response

Tr = 0xc8
Lr = 4 * N
Vr = R1 || R2 ||  || RN

where –

Ri = Object ID (2 bytes), Type, Objects (1 byte) and Sequence (1 byte).

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 –

IObject ID of the Asymmetric Key (2 bytes)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (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

Response

Tr = 0xc5
Lr = 2
Vr = I

where –

I = ID of created Object (2 bytes)

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 all to 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 all to include all capabilities. Use none to 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 none to 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. If password format 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 stdin

    Default 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 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 all to 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 none to 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 all to include all capabilities.

  • delegated_capabilities Required.

    Delegated capabilities of the key. Use none to 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 all to 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 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 all to 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 all to include all capabilities. Use none to 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 all to include all delegated capabilities. Use none to 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 –

IObject ID of the Authentication Key (2 bytes)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (1 byte)

DC = Delegated Capability (8 bytes)

Ke = Encryption Key (16 bytes)

Km = Mac Key (16 bytes)

Response

Tr = 0xc4
Lr = 2
Vr = I

where –

I = Object ID of created Authentication Key (2 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 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 all to 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 none to 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)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (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

Response

Tr = 0xd2
Lr = 2
Vr = I

where –

I = Object ID of created HMAC Key (2 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 0 to 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 all to 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 0 to 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 all to 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)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (1 byte)

O = Opaque data

Response

Tr = 0xc2
Lr = 2
Vr = I

where –

I = Object ID of created Opaque Object (2 bytes)

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 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 all to 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 none to 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)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (1 byte)

N = Nonce ID (4 bytes)

K = Key (16, 24 or 32 bytes depending on algorithm)

Response

Tr = 0xe5
Lr = 2
Vr = I

where –

I = ID of created OTP AEAD Key (2 bytes)

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 all to 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 none to 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 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 all to 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 none to 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)

Response

Tr = 0xed
Lr = 2
Vr = I

Where –

I = ID of created Object (2 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 0 to 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 all to 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 0 to 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 all to 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)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (1 byte)

D = Template data

Response

Tr = 0xde
Lr = 2
Vr = I

where –

I = Object ID of created Template (2 bytes)

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 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 all to 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 none to 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 all to include all capabilities. Use none to 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 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 all to 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 none to 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 all to include all capabilities. Use none to 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)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (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

Response

Tc = 0xcc
Lc = 2
Vc = I

where –

I = ID of created Wrap Key (2 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 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 all to 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 none to 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 all to include all capabilities. Use none to 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 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 all to 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 none to 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 all to include all capabilities. Use none to 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)

LLabel (40 bytes)

DDomain (2 bytes)

CCapability (8 bytes)

AALGORITHMS (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

Response

Tc = 0xf3
Lc = 2
Vc = I

where –

I = ID of created Public Wrap Key (2 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

Protocol Details

Command

Tc = 0x62
Lc = 2
Vc = I

where –

I = Object ID for the OTP AEAD Key (2 bytes)

Response

Tr = 0xe2
Lr = 36
Vr = A

where –

A = Nonce concatenated with AEAD (36 bytes)

RESET DEVICE Command

Resets and reboots the device, deletes all Objects and restores the default Options and Authentication Key.

Shell Example

Send reset over Session 0.

yubihsm> reset 0
Device successfully reset

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

Example

Send reset over Session 0.

yubihsm> reset 0
Device successfully reset

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.

Example

Send reset over Session 0.

$ yubihsm-shell -a reset
Device successfully reset

Protocol Details

Command

Tc = 0x08
Lc = 0
Vc = Ø

Response

Tr = 0x88
Lr = 0
Vr = Ø

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.

Protocol Details

Command

Tc = 0x63
Lc = 2 + 2 + 36
Vc = I1 || I2 || A

where –

I1 = Key ID from (2 bytes)

I2 = Key ID to (2 bytes)

A = Nonce concatenated with AEAD (36 bytes)

Response

Tr = 0xe3
Lr = 36
Vr = A

where –

A = Nonce concatenated with AEAD (36 bytes)

SESSION MESSAGE Command

Sends a wrapped command for a previously established session. The command is encrypted and authenticated.

Example

Send an echo over Session 0:

yubihsm> echo 0 0xff 1
Response (1 bytes):
ff

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. default resets the default expected input format, which can be different for different commands.

    Possible Values: default, base64, binary, PEM, password, hex, ASCII

Example

Set input format to PEM.

yubihsm> set informat PEM

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.

Shell Example

Set log index 41 as the last extracted entry.

yubihsm> audit set 0 41

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

Example

Set log index 41 as the last extracted entry.

yubihsm> audit set 0 41

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

Protocol Details

Command

Tc = 0x67
Lc = 2
Vc = I

where –

I = Index to set as last read log (2 bytes)

Response

Tr = 0xe7
Lr = 0
Vr = Ø

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-mode option 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-mode option 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:

TAG is 1 byte

LENGTH is 2 bytes

VALUE is 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. default resets the default output format, which can be different for different commands

    Possible Values: default, base64, binary, PEM, password, hex, ASCII

Example

Set output format to PEM.

yubihsm> set outformat PEM

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-----

Protocol Details

Command

Tc = 0x64
Lc = 2 + 2
Vc = I || A

where –

I = Object ID of the Asymmetric Key to attest (2 bytes)

A = Object ID of the Asymmetric Key used for attestation (2 bytes)

If A is 0 the internal attestation key is used.

Response

Tr = 0xe4
Lr = LX
Vr = X

where –

X = DER encoded X.509 attestation

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 = H

The DSI for ECDSA is a possibly zero-left-padded hash of the data, H.

Response

Tr = 0xd6
Lr = LDS
Vr = DS

where –

DS = Resulting signature

The length of DS, 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 signature DS. The length of DS, L~DS~, depends on the Algorithm used. At this time only Ed25519 is implemented.

DS = EdDSA(DSI). Key is omitted

L~DS~ = 0x0040 bytes

Response

T~r~ = 0xea
L~r~ = L~DS~
V~r~ = DS

Where –

DS = Resulting signature

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

Protocol Details

Command

Tc = 0x53
Lc = 2 + LD
Vc = I || D

where –

I = Object ID of the HMAC Key (2 bytes)

D = Data to HMAC

Response

Tr = 0xd3
Lr = LR
Vr = R

where –

R = HMAC Response, 20, 32, 48 or 64 bytes depending on the Algorithm.

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==

Protocol Details

Command

Tc = 0x47
Lc = 2 + LD
Vc = I || D

where –

I = Object ID of the Asymmetric Key (2 bytes)

D = Digest

The Digest can be either a raw hash of data, where DigestInfo will be applied in the device, or DigestInfo + hash. Hashes supported are SHA-1, SHA-256, SHA-384 and SHA-512.

Response

Tr = 0xc7
Lr = LDS
Vr = DS

where –

DS = Resulting signature

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).

Hash is a supported hash Algorithm

MGF is a supported masking function

sLen is the length of the Salt

The DSI is generated internally and only the Hash of the data and the Salt length are provided.

Response

Tr = 0xd5
Lr = LDS
Vr = DS

where –

DS = Resulting signature

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)

Response

Tr = 0xd6
Lr = LS
Vr = S

where –

S = Certificate Signature (LS 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.

Protocol Details

Command

Tc = 0x69
Lc = 2 + 13 + LD + 16
Vc = I || N || D || M

where –

I = Object ID of a Wrap Key (2 bytes)

N = Nonce (13 bytes)

D = Data to be unwrapped

M = Mac (16 bytes)

Response

Tr = 0xe9
Lr = LD
Vr = D

where –

D = Unwrapped data

VERIFY HMAC Command

Verify a generated HMAC.

Shell Example

N/A

Protocol Details

Command

Tc = 0x5c
Lc = 2 + LH + LD
Vc = I || H || D

where –

I = Object ID of the HMAC Key (2 bytes)

H = HMAC (20, 32, 48 or 64 bytes)

D = Data

Response

Tr = 0xdc
Lr = 1
Vr = V

where –

V = Verified (1 byte)

V will have the value 1 if verification succeeded and 0 otherwise.

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)