Skip to main content

Module backup

signstar_yubihsm2

Module backup 

Source
Expand description

Utilities for parsing and creating YubiHSM2 wrap files.

Wrap files are used for backup and restore actions with a YubiHSM2 device. This module provides support for the proprietary YHW data format, used by Yubico tooling.

The module supports backup of the following types of objects:

  • ed25519 private keys (both seeded and expanded form),
  • AES-128 authentication keys,
  • opaque byte vectors.

§YHW format

YubiHSM wrap files (*.yhw) consist of an inner and an outer format.

§Outer

The outer format is represented by a base64-encoded file. Its contents consist of 13 bytes of nonce at the start and AES-CCM encrypted data until the end of the file.

§Inner

Decrypting the AES-CCM encrypted outer data reveals the inner format which has the following structure:

  • 1 byte for WrapAlgorithm
  • 8 bytes for Capabilities
  • 2 bytes for encoding the object’s identifier
  • 2 bytes for encoding the wrapped object length without framing
  • 2 bytes for Domains
  • 1 byte for the object type (e.g. asymmetric key, opaque)
  • 1 byte for the subtype of the object (e.g. ed25519 key)
  • 1 byte for a sequence number, which is used internally and always 0
  • 1 byte for encoding the origin (this is only relevant when exporting)
  • 40 bytes for a UTF-8 encoded label
  • the rest of the inner format is specific to each object type (e.g. opaque byte vectors are embedded in their entirety here)

Structs§

AuthAes128
An AES-128 based authentication key.
BeReader 🔒
Reader of big-endian encoded bytes.
ExpandedEd25519KeyData
Expanded form of an ed25519 private key without seed.
InnerFormat
Parsed representation of the backup’s inner format.
PlainWrappedDataWithKey
The representation of data about to be wrapped (encrypted) with key.
SeedEd25519KeyData
The private parts of an ed25519 key.
SerializedEd25519
An Ed25519 key serialized in YubiHSM2 specific format.
YubiHsm2Wrap
The representation of wrapped (encrypted) data of a YubiHSM2.

Enums§

Error
Backup error.
ObjectType
The object type contained in the backup.
WrapAlgorithm
The supported algorithms available for wrapping (encryption) of data.
WrappedPayload
The deserialized body of a wrapped object.

Type Aliases§

Aes128Ccm 🔒