ssss

Documentation

Index

• Variables
• type Algorithm
• type DefaultSecretStorageKeyContent
• type EncryptedAccountDataEventContent
  • func (ed *EncryptedAccountDataEventContent) Decrypt(eventType string, key *Key) ([]byte, error)
• type EncryptedKeyData
• type Key
  • func NewKey(passphrase string) (*Key, error)
  • func (key *Key) Decrypt(eventType string, data EncryptedKeyData) ([]byte, error)
  • func (key *Key) Encrypt(eventType string, data []byte) EncryptedKeyData
  • func (key *Key) RecoveryKey() string
• type KeyMetadata
  • func (kd *KeyMetadata) VerifyKey(key []byte) bool
  • func (kd *KeyMetadata) VerifyPassphrase(passphrase string) (*Key, error)
  • func (kd *KeyMetadata) VerifyRecoveryKey(recoverKey string) (*Key, error)
• type Machine
  • func NewSSSSMachine(client *mautrix.Client) *Machine
  • func (mach *Machine) GenerateAndUploadKey(ctx context.Context, passphrase string) (key *Key, err error)
  • func (mach *Machine) GetDecryptedAccountData(ctx context.Context, eventType event.Type, key *Key) ([]byte, error)
  • func (mach *Machine) GetDefaultKeyData(ctx context.Context) (keyID string, keyData *KeyMetadata, err error)
  • func (mach *Machine) GetDefaultKeyID(ctx context.Context) (string, error)
  • func (mach *Machine) GetKeyData(ctx context.Context, keyID string) (keyData *KeyMetadata, err error)
  • func (mach *Machine) SetDefaultKeyID(ctx context.Context, keyID string) error
  • func (mach *Machine) SetEncryptedAccountData(ctx context.Context, eventType event.Type, data []byte, keys ...*Key) error
  • func (mach *Machine) SetKeyData(ctx context.Context, keyID string, keyData *KeyMetadata) error
• type PassphraseAlgorithm
• type PassphraseMetadata
  • func (pd *PassphraseMetadata) GetKey(passphrase string) ([]byte, error)

Variables

var (
	ErrNoDefaultKeyID               = errors.New("could not find default key ID")
	ErrNoDefaultKeyAccountDataEvent = fmt.Errorf("%w: no %s event in account data", ErrNoDefaultKeyID, event.AccountDataSecretStorageDefaultKey.Type)
	ErrNoKeyFieldInAccountDataEvent = fmt.Errorf("%w: missing key field in account data event", ErrNoDefaultKeyID)
	ErrNoKeyGiven                   = errors.New("must provide at least one key to encrypt for")

	ErrNotEncryptedForKey             = errors.New("data is not encrypted for given key ID")
	ErrKeyDataMACMismatch             = errors.New("key data MAC mismatch")
	ErrNoPassphrase                   = errors.New("no passphrase data has been set for the default key")
	ErrUnsupportedPassphraseAlgorithm = errors.New("unsupported passphrase KDF algorithm")
	ErrIncorrectSSSSKey               = errors.New("incorrect SSSS key")
	ErrInvalidRecoveryKey             = errors.New("invalid recovery key")
)

Types

type Algorithm

type Algorithm string

Algorithm is the identifier for an SSSS encryption algorithm.

const (
	// AlgorithmAESHMACSHA2 is the current main algorithm.
	AlgorithmAESHMACSHA2 Algorithm = "m.secret_storage.v1.aes-hmac-sha2"
	// AlgorithmCurve25519AESSHA2 is the old algorithm
	AlgorithmCurve25519AESSHA2 Algorithm = "m.secret_storage.v1.curve25519-aes-sha2"
)

type DefaultSecretStorageKeyContent

type DefaultSecretStorageKeyContent struct {
	KeyID string `json:"key"`
}

type EncryptedAccountDataEventContent

type EncryptedAccountDataEventContent struct {
	Encrypted map[string]EncryptedKeyData `json:"encrypted"`
}

func (*EncryptedAccountDataEventContent) Decrypt

func (ed *EncryptedAccountDataEventContent) Decrypt(eventType string, key *Key) ([]byte, error)

type EncryptedKeyData

type EncryptedKeyData struct {
	// Note: as per https://spec.matrix.org/v1.9/client-server-api/#msecret_storagev1aes-hmac-sha2-1,
	// these fields are "maybe padded" base64, so both unpadded and padded values must be supported.
	Ciphertext string `json:"ciphertext"`
	IV         string `json:"iv"`
	MAC        string `json:"mac"`
}

type Key

type Key struct {
	ID       string       `json:"-"`
	Key      []byte       `json:"-"`
	Metadata *KeyMetadata `json:"-"`
}

Key represents a SSSS private key and related metadata.

func NewKey

func NewKey(passphrase string) (*Key, error)

NewKey generates a new SSSS key, optionally based on the given passphrase.

Errors are only returned if crypto/rand runs out of randomness.

func (*Key) Decrypt

func (key *Key) Decrypt(eventType string, data EncryptedKeyData) ([]byte, error)

Decrypt decrypts the given encrypted data with this key.

func (*Key) Encrypt

func (key *Key) Encrypt(eventType string, data []byte) EncryptedKeyData

Encrypt encrypts the given data with this key.

func (*Key) RecoveryKey

func (key *Key) RecoveryKey() string

RecoveryKey gets the recovery key for this SSSS key.

type KeyMetadata

type KeyMetadata struct {
	Name      string    `json:"name"`
	Algorithm Algorithm `json:"algorithm"`

	// Note: as per https://spec.matrix.org/v1.9/client-server-api/#msecret_storagev1aes-hmac-sha2,
	// these fields are "maybe padded" base64, so both unpadded and padded values must be supported.
	IV  string `json:"iv"`
	MAC string `json:"mac"`

	Passphrase *PassphraseMetadata `json:"passphrase,omitempty"`
	// contains filtered or unexported fields
}

KeyMetadata represents server-side metadata about a SSSS key. The metadata can be used to get the actual SSSS key from a passphrase or recovery key.

func (*KeyMetadata) VerifyKey

func (kd *KeyMetadata) VerifyKey(key []byte) bool

VerifyKey verifies the SSSS key is valid by calculating and comparing its MAC.

func (*KeyMetadata) VerifyPassphrase

func (kd *KeyMetadata) VerifyPassphrase(passphrase string) (*Key, error)

VerifyRecoveryKey verifies that the given passphrase is valid and returns the computed SSSS key.

func (*KeyMetadata) VerifyRecoveryKey

func (kd *KeyMetadata) VerifyRecoveryKey(recoverKey string) (*Key, error)

VerifyRecoveryKey verifies that the given recovery key is valid and returns the decoded SSSS key.

type Machine

type Machine struct {
	Client *mautrix.Client
}

Machine contains utility methods for interacting with SSSS data on the server.

func NewSSSSMachine

func NewSSSSMachine(client *mautrix.Client) *Machine

func (*Machine) GenerateAndUploadKey

func (mach *Machine) GenerateAndUploadKey(ctx context.Context, passphrase string) (key *Key, err error)

GenerateAndUploadKey generates a new SSSS key and stores the metadata on the server.

func (*Machine) GetDecryptedAccountData

func (mach *Machine) GetDecryptedAccountData(ctx context.Context, eventType event.Type, key *Key) ([]byte, error)

GetDecryptedAccountData gets the account data event with the given event type and decrypts it using the given key.

func (*Machine) GetDefaultKeyData

func (mach *Machine) GetDefaultKeyData(ctx context.Context) (keyID string, keyData *KeyMetadata, err error)

GetDefaultKeyData gets the details about the default key ID (see GetDefaultKeyID).

func (*Machine) GetDefaultKeyID

func (mach *Machine) GetDefaultKeyID(ctx context.Context) (string, error)

GetDefaultKeyID retrieves the default key ID for this account from SSSS.

func (*Machine) GetKeyData

func (mach *Machine) GetKeyData(ctx context.Context, keyID string) (keyData *KeyMetadata, err error)

GetKeyData gets the details about the given key ID.

func (*Machine) SetDefaultKeyID

func (mach *Machine) SetDefaultKeyID(ctx context.Context, keyID string) error

SetDefaultKeyID sets the default key ID for this account on the server.

func (*Machine) SetEncryptedAccountData

func (mach *Machine) SetEncryptedAccountData(ctx context.Context, eventType event.Type, data []byte, keys ...*Key) error

SetEncryptedAccountData encrypts the given data with the given keys and stores it on the server.

func (*Machine) SetKeyData

func (mach *Machine) SetKeyData(ctx context.Context, keyID string, keyData *KeyMetadata) error

SetKeyData stores SSSS key metadata on the server.

type PassphraseAlgorithm

type PassphraseAlgorithm string

PassphraseAlgorithm is the identifier for an algorithm used to derive a key from a passphrase for SSSS.

const (
	// PassphraseAlgorithmPBKDF2 is the current main algorithm
	PassphraseAlgorithmPBKDF2 PassphraseAlgorithm = "m.pbkdf2"
)

type PassphraseMetadata

type PassphraseMetadata struct {
	Algorithm  PassphraseAlgorithm `json:"algorithm"`
	Iterations int                 `json:"iterations"`
	Salt       string              `json:"salt"`
	Bits       int                 `json:"bits"`
}

PassphraseMetadata represents server-side metadata about a SSSS key passphrase.

func (*PassphraseMetadata) GetKey

func (pd *PassphraseMetadata) GetKey(passphrase string) ([]byte, error)

GetKey gets the SSSS key from the passphrase.