FIDO Device Onboard - Go Client

go-fdo-client is a client implementation of FIDO Device Onboard specification in Go using FDO GO protocols.

Prerequisites

• Go 1.25.0 or later
• A Go module initialized with go mod init

Building the Client Application

The client application can be built with go build directly,

$ go build

FDO Client Command Syntax

$ ./go-fdo-client -h

FIDO Device Onboard Client

Usage:
  go-fdo-client [command]

Available Commands:
  device-init Run device initialization (DI)
  help        Help about any command
  onboard     Run FDO TO1 and TO2 onboarding
  print       Print device credential blob and exit

Flags:
      --blob string   File path of device credential blob
      --debug         Print HTTP contents
  -h, --help          help for go-fdo-client
      --tpm string    Use a TPM at path for device credential secrets

Use "go-fdo-client [command] --help" for more information about a command.


$ ./go-fdo-client device-init -h
Run device initialization (DI)

Usage:
  go-fdo-client device-init <server-url> [flags]

Flags:
      --device-info string       Device information for device credentials, if not specified, it'll be gathered from the system
      --device-info-mac string   Mac-address's iface e.g. eth0 for device credentials   
  -h, --help                     help for device-init
      --insecure-tls             Skip TLS certificate verification
      --key string               Key type for device credential [options: ec256, ec384, rsa2048, rsa3072]
      --key-enc string           Public key encoding to use for manufacturer key [x509,x5chain,cose] (default "x509")
      --serial-number string     Serial number for device credentials, if not specified, it'll be gathered from the system

Global Flags:
      --blob string   File path of device credential blob
      --debug         Print HTTP contents
      --tpm string    Use a TPM at path for device credential secrets


$ ./go-fdo-client onboard -h
Run FDO TO1 and TO2 onboarding

Usage:
  go-fdo-client onboard [flags]

Flags:
      --allow-credential-reuse     Allow credential reuse protocol during onboarding
      --cipher string              Name of cipher suite to use for encryption (see usage) (default "A128GCM")
      --download string            fdo.download: override destination directory set by Owner server
  -h, --help                       help for onboard
      --insecure-tls               Skip TLS certificate verification
      --kex string                 Name of cipher suite to use for key exchange (see usage)
      --key string                 Key type for device credential [options: ec256, ec384, rsa2048, rsa3072]
      --max-serviceinfo-size int   Maximum service info size to receive (default 1300)
      --resale                     Perform resale
      --rv-only                    Perform TO1 then stop
      --to2-retry-delay duration   Delay between failed TO2 attempts when trying multiple Owner URLs from same RV directive (0=disabled)
      --upload fsVar               fdo.upload: restrict Owner server upload access to specific dirs and files, flag can be used multiple times for multiple files (default [])
      --wget-dir string            fdo.wget: override destination directory set by Owner server

Global Flags:
      --blob string   File path of device credential blob
      --debug         Print HTTP contents
      --tpm string    Use a TPM at path for device credential secrets

Key types:
  - RSA2048RESTR
  - RSAPKCS
  - RSAPSS
  - SECP256R1
  - SECP384R1

Encryption suites:
  - A128GCM
  - A192GCM
  - A256GCM
  - AES-CCM-64-128-128 (not implemented)
  - AES-CCM-64-128-256 (not implemented)
  - COSEAES128CBC
  - COSEAES128CTR
  - COSEAES256CBC
  - COSEAES256CTR

Key exchange suites:
  - DHKEXid14
  - DHKEXid15
  - ASYMKEX2048
  - ASYMKEX3072
  - ECDH256
  - ECDH384

Onboarding Retry Behavior

The onboard command implements an infinite retry loop that continues attempting TO1 and TO2 protocols until successful or manually interrupted:

• RV Bypass: When an RV directive has rv_bypass enabled, the client skips TO1 and attempts TO2 directly to the Owner. The RV instruction must include the owner server's IP/DNS address, protocol, and device_port to successfully connect for TO2 and complete onboarding
• Directive Iteration: Client processes all RV directives sequentially. If one fails, it continues to the next directive
• Delays: Applies delays between retry attempts as specified in RV directives (with ±25% jitter per FDO spec)
• TO2 Retry Delay: Use --to2-retry-delay to add delay between multiple Owner URLs from the same directive (default: 0, disabled)

ServiceInfo Module Support

The onboard command supports the following FDO Service Modules that can be invoked by the FDO Owner server during device onboarding:

• fdo.command: The fdo.command module provides the functionality that allows the FDO Owner server to execute arbitrary shell commands on the device.
• fdo.download: The fdo.download module provides the functionality to download a binary file from the FDO Owner server to the device.
• fdo.upload: The fdo.upload module provides the functionality to transfer a binary file from the device to the FDO Owner server.
• fdo.wget: The fdo.wget module provides the functionality to transfer a binary file from an HTTP server to the device via a network.

Please refer to the FSIM module definition documentation for further details. By default all Service Modules are available for use by the FDO Owner server during onboarding. Refer to the onboard command help text for additional service module configuration options. Refer to the FDO Owner server documentation for server-side service module configuration details.

Running the FDO Client using a Credential File Blob

Remove Credential File

Remove the credential file if it exists:

rm cred.bin

Run the FDO Client with DI server URL

Run the FDO client, specifying the DI URL, key type and credentials blob file (on linux systems, root is required to properly gather a device identifier):

./go-fdo-client device-init http://127.0.0.1:8038 --device-info gotest --key ec256 --debug --blob cred.bin

Print FDO Client Configuration or Status

Print the FDO client configuration or status:

./go-fdo-client print --blob cred.bin

Execute TO0 from FDO Go Server

TO0 will be completed in the respective Owner and RV.

Run the FDO Client onboard command

Perform FDO client onboard. The supported key type and key exchange suite must always be explicitly configured through the --key and --kex flags:

./go-fdo-client onboard --key ec256 --kex ECDH256 --debug --blob cred.bin

Optional: Run the FDO Client in RV-Only Mode

Run the FDO client in RV-only mode, which stops after TO1 is performed:

./go-fdo-client onboard --rv-only --key ec256 --kex ECDH256 --debug --blob cred.bin

Running the FDO Client with a TPM device

NOTE: fdo_client may require elevated privileges to use the TPM device. Please use 'sudo' to execute the fdo_client.

Clear TPM NV Index to Delete Existing Credential

Ensure tpm2_tools is installed on your system.

Clear TPM NV Index

Use the following command to clear the TPM NV index:

sudo tpm2_nvundefine 0x01D10001

Run the FDO Client device-init command with DI server URL

Run FDO client device-init, specifying the DI server URL with the TPM resource manager path specified. The supported key type must always be explicitly configured through the --key flag:

./go-fdo-client device-init http://127.0.0.1:8038 --device-info gotest --key ec256 --tpm /dev/tpmrm0 --debug

Print FDO Client Configuration or Status

Print the FDO client configuration or status:

./go-fdo-client print --tpm /dev/tpmrm0

Execute TO0 from FDO Go Server

TO0 will be completed in the respective Owner and RV.

Run the FDO Client onboard command

Perform FDO client onboard. The supported key type and key exchange suite must always be explicitly configured through the --key and --kex flags:

./go-fdo-client onboard --key ec256 --kex ECDH256 --tpm /dev/tpmrm0 --debug

Optional: Run the FDO Client in RV-Only Mode

Run the FDO client in RV-only mode, which stops after TO1 is performed: The supported key type and key exchange suite must always be explicitly configured through the --key and --kex flags:

./go-fdo-client onboard --rv-only --key ec256 --kex ECDH256 --tpm /dev/tpmrm0  --debug