smsg

Documentation

Overview

Package smsg implements Secure Message encryption using password-based ChaCha20-Poly1305. SMSG (Secure Message) enables encrypted message exchange where the recipient decrypts using a pre-shared password. Useful for secure support replies, confidential documents, and any scenario requiring password-protected content.

Index

• Constants
• Variables
• func DeriveKey(password string) []byte
• func Encrypt(msg *Message, password string) ([]byte, error)
• func EncryptBase64(msg *Message, password string) (string, error)
• func EncryptWithHint(msg *Message, password, hint string) ([]byte, error)
• func QuickDecrypt(encoded, password string) (string, error)
• func QuickEncrypt(body, password string) (string, error)
• func Validate(data []byte) error
• type Attachment
• type Header
  • func GetInfo(data []byte) (*Header, error)
  • func GetInfoBase64(encoded string) (*Header, error)
• type Message
  • func Decrypt(data []byte, password string) (*Message, error)
  • func DecryptBase64(encoded, password string) (*Message, error)
  • func NewMessage(body string) *Message
  • func (m *Message) AddAttachment(name, content, mimeType string) *Message
  • func (m *Message) GetAttachment(name string) *Attachment
  • func (m *Message) SetMeta(key, value string) *Message
  • func (m *Message) WithFrom(from string) *Message
  • func (m *Message) WithReplyKey(publicKeyB64 string) *Message
  • func (m *Message) WithReplyKeyInfo(pki *PKIInfo) *Message
  • func (m *Message) WithSubject(subject string) *Message
  • func (m *Message) WithTimestamp(ts int64) *Message
• type PKIInfo

Constants

const Magic = "SMSG"

Magic bytes for SMSG format

const Version = "1.0"

Version of the SMSG format

Variables

var (
	ErrInvalidMagic     = errors.New("invalid SMSG magic")
	ErrInvalidPayload   = errors.New("invalid SMSG payload")
	ErrDecryptionFailed = errors.New("decryption failed (wrong password?)")
	ErrPasswordRequired = errors.New("password is required")
	ErrEmptyMessage     = errors.New("message cannot be empty")
)

Errors

Functions

func DeriveKey

func DeriveKey(password string) []byte

DeriveKey derives a 32-byte key from a password using SHA-256.

func Encrypt

func Encrypt(msg *Message, password string) ([]byte, error)

Encrypt encrypts a message with a password. Returns the encrypted SMSG container bytes.

func EncryptBase64

func EncryptBase64(msg *Message, password string) (string, error)

EncryptBase64 encrypts and returns base64-encoded result

func EncryptWithHint

func EncryptWithHint(msg *Message, password, hint string) ([]byte, error)

EncryptWithHint encrypts with an optional password hint in the header

func QuickDecrypt

func QuickDecrypt(encoded, password string) (string, error)

QuickDecrypt is a convenience function for simple message decryption

func QuickEncrypt

func QuickEncrypt(body, password string) (string, error)

QuickEncrypt is a convenience function for simple message encryption

func Validate

func Validate(data []byte) error

Validate checks if data is a valid SMSG container (without decrypting)

Types

type Attachment

type Attachment struct {
	Name     string `json:"name"`
	Content  string `json:"content"` // base64-encoded
	MimeType string `json:"mime,omitempty"`
	Size     int    `json:"size,omitempty"`
}

Attachment represents a file attached to the message

type Header

type Header struct {
	Version   string `json:"version"`
	Algorithm string `json:"algorithm"`
	Hint      string `json:"hint,omitempty"` // optional password hint
}

Header represents the SMSG container header

func GetInfo

func GetInfo(data []byte) (*Header, error)

GetInfo extracts header info without decrypting

func GetInfoBase64

func GetInfoBase64(encoded string) (*Header, error)

GetInfoBase64 extracts header info from base64-encoded SMSG

type Message

type Message struct {
	// Core message content
	Subject string `json:"subject,omitempty"`
	Body    string `json:"body"`

	// Optional attachments
	Attachments []Attachment `json:"attachments,omitempty"`

	// PKI for authenticated replies
	ReplyKey *PKIInfo `json:"reply_key,omitempty"`

	// Metadata
	From      string            `json:"from,omitempty"`
	Timestamp int64             `json:"timestamp,omitempty"`
	Meta      map[string]string `json:"meta,omitempty"`
}

Message represents the decrypted message content

func Decrypt

func Decrypt(data []byte, password string) (*Message, error)

Decrypt decrypts an SMSG container with a password

func DecryptBase64

func DecryptBase64(encoded, password string) (*Message, error)

DecryptBase64 decrypts a base64-encoded SMSG

func NewMessage

func NewMessage(body string) *Message

NewMessage creates a new message with the given body

func (*Message) AddAttachment

func (m *Message) AddAttachment(name, content, mimeType string) *Message

AddAttachment adds a file attachment

func (*Message) GetAttachment

func (m *Message) GetAttachment(name string) *Attachment

GetAttachment finds an attachment by name

func (*Message) SetMeta

func (m *Message) SetMeta(key, value string) *Message

SetMeta sets a metadata value

func (*Message) WithFrom

func (m *Message) WithFrom(from string) *Message

WithFrom sets the sender

func (*Message) WithReplyKey

func (m *Message) WithReplyKey(publicKeyB64 string) *Message

WithReplyKey sets the PKI public key for authenticated replies

func (*Message) WithReplyKeyInfo

func (m *Message) WithReplyKeyInfo(pki *PKIInfo) *Message

WithReplyKeyInfo sets full PKI information

func (*Message) WithSubject

func (m *Message) WithSubject(subject string) *Message

WithSubject sets the message subject

func (*Message) WithTimestamp

func (m *Message) WithTimestamp(ts int64) *Message

WithTimestamp sets the timestamp

type PKIInfo

type PKIInfo struct {
	PublicKey   string `json:"public_key"`            // base64-encoded X25519 public key
	KeyID       string `json:"key_id,omitempty"`      // optional key identifier
	Algorithm   string `json:"algorithm,omitempty"`   // e.g., "x25519"
	Fingerprint string `json:"fingerprint,omitempty"` // SHA256 fingerprint of public key
}

PKIInfo contains public key information for authenticated replies