identity

Documentation

Overview

SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io

SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io

SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io

SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io

SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io

Index

• Constants
• Variables
• func GetKnownDestination(hash string) ([]any, bool)
• func GetRandomHash() []byte
• func HashFromString(hash string) ([]byte, error)
• func IsHardwareBoundIdentityFilePayload(data []byte) bool
• func Remember(packet []byte, destHash []byte, publicKey []byte, appData []byte)
• func TruncatedHash(data []byte) []byte
• func ValidateAnnounce(packet []byte, destHash []byte, publicKey []byte, signature []byte, ...) bool
• func WriteHardwareBoundIdentityFile(path string, x25519Private []byte, ed25519Pub ed25519.PublicKey) error
• type Ed25519Signer
• type Identity
  • func FromBytes(data []byte) (*Identity, error)
  • func FromFile(path string) (*Identity, error)
  • func FromPublicKey(publicKey []byte) *Identity
  • func LoadIdentityFile(path string, signer cryptography.Ed25519Signer) (*Identity, error)
  • func LoadOrCreateTransportIdentity(customPath string) (*Identity, error)
  • func New() (*Identity, error)
  • func NewIdentity() (*Identity, error)
  • func NewIdentityWithSigner(x25519Private []byte, signer cryptography.Ed25519Signer) (*Identity, error)
  • func Recall(hash []byte) (*Identity, error)
  • func RecallIdentity(path string) (*Identity, error)
  • func (i *Identity) CleanupExpiredRatchets()
  • func (i *Identity) ComputeHMAC(key, message []byte) []byte
  • func (i *Identity) Decrypt(ciphertextToken []byte, ratchets [][]byte, enforceRatchets bool, ...) ([]byte, error)
  • func (i *Identity) DecryptWithHMAC(data []byte, key []byte) ([]byte, error)
  • func (i *Identity) Encrypt(plaintext []byte, ratchet []byte) ([]byte, error)
  • func (i *Identity) EncryptWithHMAC(plaintext []byte, key []byte) ([]byte, error)
  • func (i *Identity) GenerateHMACKey() []byte
  • func (i *Identity) GetContext() []byte
  • func (i *Identity) GetCurrentRatchetKey() []byte
  • func (i *Identity) GetEncryptionKey() []byte
  • func (i *Identity) GetHexHash() string
  • func (i *Identity) GetNameHash() []byte
  • func (i *Identity) GetPrivateKey() ([]byte, error)
  • func (i *Identity) GetPublicKey() []byte
  • func (i *Identity) GetRatchetID(ratchetPubBytes []byte) []byte
  • func (i *Identity) GetRatchetKey(id string) ([]byte, bool)
  • func (i *Identity) GetRatchets() [][]byte
  • func (i *Identity) GetSalt() []byte
  • func (i *Identity) GetSigningKey() []byte
  • func (i *Identity) Hash() []byte
  • func (i *Identity) Hex() string
  • func (i *Identity) RotateRatchet() ([]byte, error)
  • func (i *Identity) SetRatchetKey(id string, key []byte)
  • func (i *Identity) Sign(data []byte) ([]byte, error)
  • func (i *Identity) String() string
  • func (i *Identity) ToFile(path string) error
  • func (i *Identity) ToHardwareBoundFile(path string) error
  • func (i *Identity) ValidateAnnounce(data []byte, destHash []byte, appData []byte) bool
  • func (i *Identity) ValidateHMAC(key, message, messageHMAC []byte) bool
  • func (i *Identity) Verify(data []byte, signature []byte) bool

Constants

const (
	Curve               = "Curve25519"
	KeySize             = 512
	RatchetSize         = 256
	RatchetExpiry       = 2592000
	TruncatedHashLength = 128
	NameHashLength      = 80

	TokenOverhead   = 16
	AES128BlockSize = 16
	HashLength      = 256
	SigLength       = KeySize

	RatchetRotationInterval = 1800
	MaxRetainedRatchets     = 512
)

Variables

var ErrHardwareBoundSignerPublicKeyMismatch = errors.New("signer public key does not match hardware-bound identity file")

ErrHardwareBoundSignerPublicKeyMismatch means the signer public key != file pubkey.

var ErrHardwareBoundSignerRequired = errors.New("hardware-bound identity file requires an Ed25519 signer or OptionalIdentitySignerHook")

ErrHardwareBoundSignerRequired means a RHB1 file was loaded without a signer and OptionalIdentitySignerHook did not supply one.

var ErrSigningMaterialNotExportable = errors.New("identity signing material is not exportable")

ErrSigningMaterialNotExportable is returned when the identity uses an external signer (e.g. HSM) and raw private bytes are not available.

var OptionalIdentitySignerHook func() (cryptography.Ed25519Signer, error)

OptionalIdentitySignerHook supplies a signer when LoadIdentityFile loads a hardware-bound file and the signer argument is nil (e.g. set in init for PKCS#11).

Functions

func GetKnownDestination

func GetKnownDestination(hash string) ([]any, bool)

func GetRandomHash

func GetRandomHash() []byte

func HashFromString

func HashFromString(hash string) ([]byte, error)

func IsHardwareBoundIdentityFilePayload

func IsHardwareBoundIdentityFilePayload(data []byte) bool

IsHardwareBoundIdentityFilePayload reports whether data is a v1 RHB1 descriptor.

func Remember

func Remember(packet []byte, destHash []byte, publicKey []byte, appData []byte)

func TruncatedHash

func TruncatedHash(data []byte) []byte

func ValidateAnnounce

func ValidateAnnounce(packet []byte, destHash []byte, publicKey []byte, signature []byte, appData []byte) bool

func WriteHardwareBoundIdentityFile

func WriteHardwareBoundIdentityFile(path string, x25519Private []byte, ed25519Pub ed25519.PublicKey) error

WriteHardwareBoundIdentityFile writes RHB1 v1: 8-byte header, X25519 priv, Ed25519 pub (no seed).

Types

type Ed25519Signer

type Ed25519Signer = cryptography.Ed25519Signer

Ed25519Signer is re-exported for identity callers configuring HSM-backed signing.

type Identity

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

func FromBytes

func FromBytes(data []byte) (*Identity, error)

FromBytes creates an Identity from a 64-byte private key representation

func FromFile

func FromFile(path string) (*Identity, error)

func FromPublicKey

func FromPublicKey(publicKey []byte) *Identity

func LoadIdentityFile

func LoadIdentityFile(path string, signer cryptography.Ed25519Signer) (*Identity, error)

LoadIdentityFile loads 64-byte software identity bytes or RHB1 v1 hardware-bound descriptor. Hardware-bound paths need a matching signer or OptionalIdentitySignerHook.

func LoadOrCreateTransportIdentity

func LoadOrCreateTransportIdentity(customPath string) (*Identity, error)

func New

func New() (*Identity, error)

func NewIdentity

func NewIdentity() (*Identity, error)

NewIdentity creates a new Identity instance with fresh keys

func NewIdentityWithSigner

func NewIdentityWithSigner(x25519Private []byte, signer cryptography.Ed25519Signer) (*Identity, error)

NewIdentityWithSigner builds an identity whose Ed25519 operations go through signer (e.g. HSM via cryptography.NewEd25519SignerFromCryptoSigner). The X25519 half is still supplied as a 32-byte private scalar (often generated in software or from a second key in the HSM). On-wire format is unchanged.

func Recall

func Recall(hash []byte) (*Identity, error)

func RecallIdentity

func RecallIdentity(path string) (*Identity, error)

func (*Identity) CleanupExpiredRatchets

func (i *Identity) CleanupExpiredRatchets()

func (*Identity) ComputeHMAC

func (i *Identity) ComputeHMAC(key, message []byte) []byte

func (*Identity) Decrypt

func (i *Identity) Decrypt(ciphertextToken []byte, ratchets [][]byte, enforceRatchets bool, ratchetIDReceiver *common.RatchetIDReceiver) ([]byte, error)

func (*Identity) DecryptWithHMAC

func (i *Identity) DecryptWithHMAC(data []byte, key []byte) ([]byte, error)

func (*Identity) Encrypt

func (i *Identity) Encrypt(plaintext []byte, ratchet []byte) ([]byte, error)

func (*Identity) EncryptWithHMAC

func (i *Identity) EncryptWithHMAC(plaintext []byte, key []byte) ([]byte, error)

func (*Identity) GenerateHMACKey

func (i *Identity) GenerateHMACKey() []byte

func (*Identity) GetContext

func (i *Identity) GetContext() []byte

func (*Identity) GetCurrentRatchetKey

func (i *Identity) GetCurrentRatchetKey() []byte

func (*Identity) GetEncryptionKey

func (i *Identity) GetEncryptionKey() []byte

GetEncryptionKey returns the X25519 public key used for encryption

func (*Identity) GetHexHash

func (i *Identity) GetHexHash() string

func (*Identity) GetNameHash

func (i *Identity) GetNameHash() []byte

GetNameHash returns a 10-byte hash derived from the identity's public key

func (*Identity) GetPrivateKey

func (i *Identity) GetPrivateKey() ([]byte, error)

func (*Identity) GetPublicKey

func (i *Identity) GetPublicKey() []byte

func (*Identity) GetRatchetID

func (i *Identity) GetRatchetID(ratchetPubBytes []byte) []byte

func (*Identity) GetRatchetKey

func (i *Identity) GetRatchetKey(id string) ([]byte, bool)

func (*Identity) GetRatchets

func (i *Identity) GetRatchets() [][]byte

func (*Identity) GetSalt

func (i *Identity) GetSalt() []byte

func (*Identity) GetSigningKey

func (i *Identity) GetSigningKey() []byte

GetSigningKey returns the Ed25519 public key used for signing

func (*Identity) Hash

func (i *Identity) Hash() []byte

func (*Identity) Hex

func (i *Identity) Hex() string

func (*Identity) RotateRatchet

func (i *Identity) RotateRatchet() ([]byte, error)

func (*Identity) SetRatchetKey

func (i *Identity) SetRatchetKey(id string, key []byte)

func (*Identity) Sign

func (i *Identity) Sign(data []byte) ([]byte, error)

func (*Identity) String

func (i *Identity) String() string

func (*Identity) ToFile

func (i *Identity) ToFile(path string) error

func (*Identity) ToHardwareBoundFile

func (i *Identity) ToHardwareBoundFile(path string) error

ToHardwareBoundFile writes RHB1 v1 (X25519 private + Ed25519 public on disk). Requires exportable key material; fails if signing is already external-only.

func (*Identity) ValidateAnnounce

func (i *Identity) ValidateAnnounce(data []byte, destHash []byte, appData []byte) bool

ValidateAnnounce validates an announce packet's signature

func (*Identity) ValidateHMAC

func (i *Identity) ValidateHMAC(key, message, messageHMAC []byte) bool

func (*Identity) Verify

func (i *Identity) Verify(data []byte, signature []byte) bool