devicecert

Documentation

Overview

Package devicecert implements Freizone's device certificate and device revocation records: statements signed by an account's root Ed25519 key that authorize (or revoke) a device's identity key.

The signing byte layout is a cross-repo wire-format contract shared with the mobile client -- see docs/PROTOCOL.md.

Index

• func NewDeviceID() (string, error)
• type DHIdentityCertificate
  • func SignDHIdentityCertificate(accountID, deviceID string, dhPubKey []byte, issuedAt time.Time, ...) (*DHIdentityCertificate, error)
  • func (c *DHIdentityCertificate) Verify(devicePubKey ed25519.PublicKey) error
• type DeviceCertificate
  • func SignDeviceCertificate(accountID, deviceID string, devicePubKey ed25519.PublicKey, issuedAt time.Time, ...) (*DeviceCertificate, error)
  • func (c *DeviceCertificate) Verify(rootPubKey ed25519.PublicKey) error
• type DeviceRevocation
  • func SignDeviceRevocation(accountID, deviceID string, revokedAt time.Time, rootPriv ed25519.PrivateKey) (*DeviceRevocation, error)
  • func (r *DeviceRevocation) Verify(rootPubKey ed25519.PublicKey) error
• type SignedPrekeyCertificate
  • func SignSignedPrekeyCertificate(accountID, deviceID string, keyID uint32, ...) (*SignedPrekeyCertificate, error)
  • func (c *SignedPrekeyCertificate) Verify(devicePubKey ed25519.PublicKey) error

Functions

func NewDeviceID

func NewDeviceID() (string, error)

NewDeviceID generates a new random device ID, hex-encoded (16 characters).

Types

type DHIdentityCertificate

type DHIdentityCertificate struct {
	AccountID string    `json:"account_id"`
	DeviceID  string    `json:"device_id"`
	DHPubKey  []byte    `json:"dh_pub_key"` // X25519, 32 bytes
	IssuedAt  time.Time `json:"issued_at"`
	Signature []byte    `json:"signature"`
}

DHIdentityCertificate binds a device's X25519 Diffie-Hellman identity key (used for X3DH/Double Ratchet key agreement) to that device. Unlike DeviceCertificate, this is signed by the device's own Ed25519 private key, not the account's root key -- a device already certified by the root is vouching for its own X3DH key material.

func SignDHIdentityCertificate

func SignDHIdentityCertificate(accountID, deviceID string, dhPubKey []byte, issuedAt time.Time, devicePriv ed25519.PrivateKey) (*DHIdentityCertificate, error)

SignDHIdentityCertificate builds and signs a new DH identity certificate with the device's own Ed25519 private key.

func (*DHIdentityCertificate) Verify

func (c *DHIdentityCertificate) Verify(devicePubKey ed25519.PublicKey) error

Verify checks the certificate's structure and its signature against the device's Ed25519 public key.

type DeviceCertificate

type DeviceCertificate struct {
	AccountID    string            `json:"account_id"`
	DeviceID     string            `json:"device_id"`
	DevicePubKey ed25519.PublicKey `json:"device_pub_key"`
	IssuedAt     time.Time         `json:"issued_at"`
	Signature    []byte            `json:"signature"`
}

DeviceCertificate authorizes a device's identity key under an account's root key.

func SignDeviceCertificate

func SignDeviceCertificate(accountID, deviceID string, devicePubKey ed25519.PublicKey, issuedAt time.Time, rootPriv ed25519.PrivateKey) (*DeviceCertificate, error)

SignDeviceCertificate builds and signs a new device certificate with the given account's root private key.

func (*DeviceCertificate) Verify

func (c *DeviceCertificate) Verify(rootPubKey ed25519.PublicKey) error

Verify checks the certificate's structure and its signature against the given root public key. A nil error means the certificate is valid.

type DeviceRevocation

type DeviceRevocation struct {
	AccountID string    `json:"account_id"`
	DeviceID  string    `json:"device_id"`
	RevokedAt time.Time `json:"revoked_at"`
	Signature []byte    `json:"signature"`
}

DeviceRevocation revokes a previously certified device, signed by the account's root key.

func SignDeviceRevocation

func SignDeviceRevocation(accountID, deviceID string, revokedAt time.Time, rootPriv ed25519.PrivateKey) (*DeviceRevocation, error)

SignDeviceRevocation builds and signs a new device revocation with the given account's root private key.

func (*DeviceRevocation) Verify

func (r *DeviceRevocation) Verify(rootPubKey ed25519.PublicKey) error

Verify checks the revocation's structure and its signature against the given root public key.

type SignedPrekeyCertificate

type SignedPrekeyCertificate struct {
	AccountID        string    `json:"account_id"`
	DeviceID         string    `json:"device_id"`
	KeyID            uint32    `json:"key_id"`
	DHIdentityPubKey []byte    `json:"dh_identity_pub_key"` // X25519, 32 bytes -- must match the device's DHIdentityCertificate
	PrekeyPubKey     []byte    `json:"prekey_pub_key"`      // X25519, 32 bytes
	IssuedAt         time.Time `json:"issued_at"`
	Signature        []byte    `json:"signature"`
}

SignedPrekeyCertificate binds a rotatable X3DH signed prekey to a specific DH identity key (DHIdentityPubKey), so the signature can't be replayed against a substituted identity key. Signed by the device's own Ed25519 private key, same as DHIdentityCertificate.

func SignSignedPrekeyCertificate

func SignSignedPrekeyCertificate(accountID, deviceID string, keyID uint32, dhIdentityPubKey, prekeyPubKey []byte, issuedAt time.Time, devicePriv ed25519.PrivateKey) (*SignedPrekeyCertificate, error)

SignSignedPrekeyCertificate builds and signs a new signed-prekey certificate with the device's own Ed25519 private key.

func (*SignedPrekeyCertificate) Verify

func (c *SignedPrekeyCertificate) Verify(devicePubKey ed25519.PublicKey) error

Verify checks the certificate's structure and its signature against the device's Ed25519 public key.