YubiHSM Wrap

YubiHSM Wrap is a command-line tool to create "offline wraps" for a YubiHSM 2 device.

One of the functionalities supported by the YubiHSM is to import objects under wrap. The typical use is to generate an object on one device, export it under wrap using a Wrap Key and import it to a different device which has the same Wrap Key.

At times it is also useful to be able to create those wrapped objects from a computer, so that they can be encrypted at rest and also easily sent to devices for use.


This example shows how to generate a private key using OpenSSL, wrap it to a pre-shared Wrap Key and import it on a device.

The first thing we need is a Wrap Key that we will use to wrap the object. For this example we are going to use 00112233445566778899aabbccddeeff

We first save it to a file called wrap.key by running

$ echo -en '\x00\x11\x22\x33\x44\x55\x66\x77\x88\x99\xaa\xbb\xcc\xdd\xee\xff' >wrap.key

The Wrap Key has to also exist on the YubiHSM. We can import it in the device and give it Object ID 20 by running

$ yubihsm-shell -p password -a put-wrap-key -i 20 -c all --delegated all --informat bin --in wrap.key

At this point we can use OpenSSL to generate the RSA key that we would like to wrap and import

$ openssl genrsa -out private.pem

We can now use yubihsm-wrap to produce the wrapped version of the private key. Specifically, we will be asking for the key to have, once imported, Object ID 30, label RSA_Key and belong to Domains 1, 2 and 5.

$ yubihsm-wrap -a rsa2048 -c sign-pkcs -d 1,2,5 --id 30 --label RSA_Key --in private.pem --wrapkey wrap.key --out private.yhw

The output file private.yhw is the wrapped version of the key and it is ready to be imported in the device using the Wrap Key that we stored before. The command to do that is

$ yubihsm-shell -p password -a put-wrapped --wrap-id 20 --in private.yhw

We should now be able to retrieve information about the Asymmetric Key with Object ID 30 by running

$ yubihsm-shell -p password -a get-object-info -i 30 -t asymmetric-key
Using default connector URL: http://localhost:12345
Session keepalive set up to run every 15 seconds
Created session 0
id: 0x001e, type: asymmetric-key, algorithm: rsa2048, label: "RSA_Key", length: 896, domains: 1:2:5, sequence: 0, origin: imported:imported_wrapped, capabilities: sign-pkcs