tkeypqdevicesign

README

Tillitis tkey-pq-device-sign package

A Go package for communicating with the tkey-pq-device-signer device app on a Tillitis TKey to get cryptographic signatures over a message.

The package has functionality to call for signing with external MU computation, the external is used by the tkey-pq-device-signer uses external computation for signing.

See the ML-DSA draft for more info about external MU computation.

See the Go doc for tkey-pq-device-sign for details on how to call the functions.

See tkey-pq-sign-cli for client applications using this go package.

Release notes in RELEASE.md.

Licenses and SPDX tags

Unless otherwise noted, the project sources are copyright Tillitis AB, licensed under the terms and conditions of the "BSD-2-Clause" license. See LICENSE for the full license text.

Until Oct 25, 2024, the license was GPL-2.0 Only.

External source code we have imported are isolated in their own directories. They may be released under other licenses. This is noted with a similar LICENSE file in every directory containing imported sources.

The project uses single-line references to Unique License Identifiers as defined by the Linux Foundation's SPDX project on its own source files, but not necessarily imported files. The line in each individual source file identifies the license applicable to that file.

The current set of valid, predefined SPDX identifiers can be found on the SPDX License List at:

https://spdx.org/licenses/

We attempt to follow the REUSE specification.

Documentation

Overview

Package tkeysign provides a connection to the mldsa signer app running on the TKey. You're expected to pass an existing connection to it, so use it like this:

tk := tkeyclient.New()
err := tk.Connect(port)
err := tk.LoadApp(appBinary, secretPhrase)
signer := tkeysign.New(tk)

Then use it like this to get the public key of the TKey:

pubkey, err := signer.GetPubkey()

And like this to sign a message:

signature, err := signer.Sign(message)

Index

• Constants
• type Signer
  • func New(tk *tkeyclient.TillitisKey) Signer
  • func (s Signer) Close() error
  • func (s Signer) ComputeMu(pubkey, message []byte) []byte
  • func (s Signer) GetAppNameVersion() (*tkeyclient.NameVersion, error)
  • func (s Signer) GetFWDigest(len int) ([]byte, error)
  • func (s Signer) GetPubkey() ([]byte, error)
  • func (s Signer) SignExtMu(mu []byte) ([]byte, error)

Constants

const MLDSAMuSize = 64

MLDSAMuSize is the size of the external mu input (FIPS 204 CRHBYTES) in bytes.

const MLDSAPubKeySize = 1312

MLDSAPubKeySize is the size of an ML-DSA-44 (Dilithium2) public key in bytes.

const MLDSASigSize = 2420

MLDSASigSize is the size of an ML-DSA-44 (Dilithium2) signature in bytes.

Types

type Signer

type Signer struct {
	// contains filtered or unexported fields
}

func New

func New(tk *tkeyclient.TillitisKey) Signer

New allocates a struct for communicating with the mldsa signer app running on the TKey. You're expected to pass an existing connection to it, so use it like this:

tk := tkeyclient.New()
err := tk.Connect(port)
signer := tkeysign.New(tk)

func (Signer) Close

func (s Signer) Close() error

Close closes the connection to the TKey

func (Signer) ComputeMu

func (s Signer) ComputeMu(pubkey, message []byte) []byte

computeMu derives the 64-byte message representative mu from the public key and message following FIPS 204 ML-DSA.Sign (Algorithm 2, external-mu variant):

tr = SHAKE256(pk, 64)
mu = SHAKE256(tr || 0x00 || 0x00 || message, 64)

The two zero bytes encode format byte 0 (ML-DSA, not HashML-DSA) and an empty context string length.

func (Signer) GetAppNameVersion

func (s Signer) GetAppNameVersion() (*tkeyclient.NameVersion, error)

GetAppNameVersion gets the name and version of the running app in the same style as the stick itself.

func (Signer) GetFWDigest

func (s Signer) GetFWDigest(len int) ([]byte, error)

GetFWDigest asks the signer app to hash len bytes of the firmware.

It returns the resulting SHA512 digest or an error.

func (Signer) GetPubkey

func (s Signer) GetPubkey() ([]byte, error)

GetPubkey fetches the public key of the signer.

func (Signer) SignExtMu

func (s Signer) SignExtMu(mu []byte) ([]byte, error)

SignExtMu signs a pre-computed 64-byte message representative (mu) and returns an ML-DSA-44 signature. The device app uses mldsa_signature_extmu internally, so the caller must provide exactly MLDSAMuSize (64) bytes. Use computeMu (in the CLI) to derive mu from the public key and message following FIPS 204: tr = SHAKE256(pk, 64); mu = SHAKE256(tr||0x00||0x00||msg, 64).