imapsql

package module
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 9, 2019 License: MIT Imports: 27 Imported by: 1

README

go-imap-sql Travis CI CodeCov Reference stability-unstable

SQL-based storage backend for go-imap library.

Building

Go 1.11.4 is required because we are using modules. Things may work on older versions but these configurations will not be supported.

RDBMS support

go-imap-sql is known to work with (and constantly being tested against) following RDBMS:

  • SQLite 3.25.0
  • MySQL 8.0 (or MariaDB 10.2)
  • PostgreSQL 9.6

IMAP Extensions Supported

Due to go-imap architecture, some extensions require support from used backend. Here are extensions supported by go-imap-sql:

Passwords hashing

go-imap-sql uses bcrypt hash function for account passwords. This makes passwords hard to brute-force, but also significantly increases CPU load.

Backend users should either change hash function to sha3-512 (see Opts structure documentation) or implement restrictions on authentication attempts that will block access after certain number of attempts.

secure_delete

You may want to overwrite deleted messages and theirs meta-data with zeroes for security/privacy reasons. For MySQL, PostgreSQL - consult documentation (AFAIK, there is no such option).

For SQLite3, you should build go-imap-sql with sqlite3_secure_delete build tag. It will enable corresponding SQLite3 feature by default for all databases.

If you want to enable it per-database - you can use file:PATH?_secure_delete=ON in DSN.

UIDVALIDITY

go-imap-sql never invalidates UIDs in an existing mailbox. If mailbox is DELETE'd then UIDVALIDITY value changes.

Unlike many popular IMAP server implementations, go-imap-sql uses randomly generated UIDVALIDITY values instead of timestamps.

This makes several things easier to implement with less edge cases. And answer to the question you are already probably asked: To make go-imap-sql malfunction you need to get Go's PRNG to generate two equal integers in range of [1, 2^32-1] just at right moment (seems unlikely enough to ignore it). Even then, it will not cause much problems due to the way most client implementations work.

go-imap-sql uses separate math/rand.Rand instance and seeds it with system time on initialization (in New).

You can provide custom pre-seeded struct implementing math/rand.Source in Opts struct (PRNG field).

Internal/External BLOBs

go-imap-sql can store message bodies in two ways: In database rows (works well with SQLite3) or in "external" key-value store (works better with any server-based RDBMS). By default former approach is used.

To switch to "external store", set Opts.ExternalStore field before passing Opts object to New.

If you switch already populated database to "external store", all new messages will be stored in the external store, but old ones will be still in DB.

This repository provides simple filesystem-based key-value store implementation, see fsstore package.

Maddy

You can use go-imap-sql as part of the maddy mail server.

imapsql-ctl

For direct access to database you can use imapsql-ctl console utility. See more information in separate README here.

go install github.com/foxcpp/go-imap-sql/cmd/imapsql-ctl

Documentation

Index

Constants

View Source 
const MailboxPathSep = "."
View Source 
const SchemaVersion = 3

SchemaVersion is incremented each time DB schema changes.

View Source 
const VersionStr = "0.3.1"

VersionStr is a string value representing go-imap-sql version.

Meant for debug logs, you may want to know which go-imap-sql version users have.

Variables

View Source 
var (
	ErrUserAlreadyExists = errors.New("imap: user already exists")
	ErrUserDoesntExists  = errors.New("imap: user doesn't exists")
)

Functions

This section is empty.

Types

type Backend added in v0.2.0 

type Backend struct {

	// Opts structure used to construct this Backend object.
	//
	// For most cases it is safe to change options while backend is serving
	// requests.
	// Options that should NOT be changed while backend is processing commands:
	// - ExternalStore
	// - PRNG
	// Changes for the following options have no effect after backend initialization:
	// - AllowSchemaUpgrade
	// - ExclusiveLock
	// - CacheSize
	// - NoWAL
	// - UpdatesChan
	Opts Opts

	// database/sql.DB object created by New.
	DB *sql.DB
	// contains filtered or unexported fields
}

func New added in v0.2.0 

func New(driver, dsn string, opts Opts) (*Backend, error)

New creates new Backend instance using provided configuration.

driver and dsn arguments are passed directly to sql.Open.

Note that it is not safe to create multiple Backend instances working with the single database as they need to keep some state synchronized and there is no measures for this implemented in go-imap-sql.

func (*Backend) CheckPlain added in v0.2.0 

func (b *Backend) CheckPlain(username, password string) bool

CheckPlain checks the credentials of the user account.

func (*Backend) Close added in v0.2.0 

func (b *Backend) Close() error

func (*Backend) CreateMessageLimit added in v0.2.0 

func (b *Backend) CreateMessageLimit() *uint32

func (*Backend) CreateUser added in v0.2.0 

func (b *Backend) CreateUser(username, password string) error

CreateUser creates user account with specified credentials.

This method can fail if used crypto/rand fails to create enough entropy. It is error to create account with username that already exists. ErrUserAlreadyExists will be returned in this case.

func (*Backend) CreateUserNoPass added in v0.3.0 

func (b *Backend) CreateUserNoPass(username string) error

CreateUserNoPass creates new user account without a password set.

It will be unable to log in until SetUserPassword is called for it.

func (*Backend) CreateUserWithHash added in v0.3.0 

func (b *Backend) CreateUserWithHash(username, hashAlgo, password string) error

func (*Backend) DeleteUser added in v0.2.0 

func (b *Backend) DeleteUser(username string) error

DeleteUser deleted user account with specified username.

It is error to delete account that doesn't exist, ErrUserDoesntExists will be returned in this case.

func (*Backend) EnableChildrenExt added in v0.2.0 

func (b *Backend) EnableChildrenExt() bool

EnableChildrenExt enables generation of /HasChildren and /HasNoChildren attributes for mailboxes. It should be used only if server advertises CHILDREN extension support (see children subpackage).

func (*Backend) EnableHashAlgo added in v0.3.0 

func (b *Backend) EnableHashAlgo(name string,
	hashFunc func(saltedPass []byte) []byte,
	checkFunc func(saltedPass, hash []byte) bool)

EnableHashAlgo enables support for additional hash algorithm using two provided callback functions.

Note that generated hash should be ASCII-encoded.

func (*Backend) GetOrCreateUser added in v0.2.0 

func (b *Backend) GetOrCreateUser(username string) (backend.User, error)

GetOrCreateUser is a convenience wrapper for GetUser and CreateUser.

Users are created with invalid password such that CheckPlain and Login will always return "invalid credentials" error.

All database operations are executed within one transaction so this method is atomic as defined by used RDBMS.

func (*Backend) GetUser added in v0.2.0 

func (b *Backend) GetUser(username string) (backend.User, error)

GetUser creates backend.User object without for the user credentials.

If you want to check user credentials, you should use Login or CheckPlain.

func (*Backend) ListUsers added in v0.2.0 

func (b *Backend) ListUsers() ([]string, error)

ListUsers returns list of existing usernames.

It may return nil slice if no users are registered.

func (*Backend) Login added in v0.2.0 

func (b *Backend) Login(_ *imap.ConnInfo, username, password string) (backend.User, error)

func (*Backend) ResetPassword added in v0.3.0 

func (b *Backend) ResetPassword(username string) error

ResetPassword sets user account password to invalid value such that Login and CheckPlain will always return "invalid credentials" error.

func (*Backend) SetMessageLimit added in v0.2.0 

func (b *Backend) SetMessageLimit(val *uint32) error

Change global APPEND limit, Opts.MaxMsgBytes.

Provided to implement interfaces used by go-imap-backend-tests.

func (*Backend) SetUserPassword added in v0.2.0 

func (b *Backend) SetUserPassword(username, newPassword string) error

SetUserPassword changes password associated with account with specified username.

Opts.DefaultHashAlgo is used for password hashing. This method can fail if crypto/rand fails to generate enough entropy.

It is error to change password for account that doesn't exist, ErrUserDoesntExists will be returned in this case.

func (*Backend) SetUserPasswordWithHash added in v0.3.0 

func (b *Backend) SetUserPasswordWithHash(hashAlgo, username, newPassword string) error

SetUserPasswordWithHash is a version of SetUserPassword that allows to specify any supported hash algorithm instead of Opts.DefaultHashAlgo.

func (*Backend) Updates added in v0.2.0 

func (b *Backend) Updates() <-chan backend.Update

func (*Backend) UserCreds added in v0.2.0 

func (b *Backend) UserCreds(username string) (id uint64, hashAlgo string, passHash []byte, passSalt []byte, err error)

UserCreds returns internal identifier and credentials for user named username.

It is exported for use by extensions and is not considered part of the public API. Hence it can be changed between minor releases.

type ExternalStore added in v0.2.0 

type ExternalStore interface {
	Create(key string) (io.WriteCloser, error)
	Open(key string) (io.ReadCloser, error)
	Delete(keys []string) error
}

ExternalStore is an interface used by go-imap-sql to store message bodies outside of main database.

type Mailbox added in v0.2.0 

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

func (*Mailbox) Check added in v0.2.0 

func (m *Mailbox) Check() error

func (*Mailbox) CopyMessages added in v0.2.0 

func (m *Mailbox) CopyMessages(uid bool, seqset *imap.SeqSet, dest string) error

func (*Mailbox) CreateMessage added in v0.2.0 

func (m *Mailbox) CreateMessage(flags []string, date time.Time, fullBody imap.Literal) error

func (*Mailbox) CreateMessageLimit added in v0.2.0 

func (m *Mailbox) CreateMessageLimit() *uint32

func (*Mailbox) DelMessages added in v0.2.0 

func (m *Mailbox) DelMessages(uid bool, seqset *imap.SeqSet) error

func (*Mailbox) Expunge added in v0.2.0 

func (m *Mailbox) Expunge() error

func (*Mailbox) Info added in v0.2.0 

func (m *Mailbox) Info() (*imap.MailboxInfo, error)

func (*Mailbox) ListMessages added in v0.2.0 

func (m *Mailbox) ListMessages(uid bool, seqset *imap.SeqSet, items []imap.FetchItem, ch chan<- *imap.Message) error

func (*Mailbox) MoveMessages added in v0.2.0 

func (m *Mailbox) MoveMessages(uid bool, seqset *imap.SeqSet, dest string) error

func (*Mailbox) Name added in v0.2.0 

func (m *Mailbox) Name() string

func (*Mailbox) SearchMessages added in v0.2.0 

func (m *Mailbox) SearchMessages(uid bool, criteria *imap.SearchCriteria) ([]uint32, error)

func (*Mailbox) SetMessageLimit added in v0.2.0 

func (m *Mailbox) SetMessageLimit(val *uint32) error

func (*Mailbox) SetSubscribed added in v0.2.0 

func (m *Mailbox) SetSubscribed(subscribed bool) error

func (*Mailbox) Status added in v0.2.0 

func (m *Mailbox) Status(items []imap.StatusItem) (*imap.MailboxStatus, error)

func (*Mailbox) UpdateMessagesFlags added in v0.2.0 

func (m *Mailbox) UpdateMessagesFlags(uid bool, seqset *imap.SeqSet, operation imap.FlagsOp, flags []string) error

type Opts added in v0.2.0 

type Opts struct {

	// Maximum amount of bytes that backend will accept.
	// Intended for use with APPENDLIMIT extension.
	// nil value means no limit, 0 means zero limit (no new messages allowed)
	MaxMsgBytes *uint32

	// Controls when channel returned by Updates should be created.
	// If set to false - channel will be created before NewBackend returns.
	// If set to true - channel will be created upon first call to Updates.
	// Second is useful for tests that don't consume values from Updates
	// channel.
	LazyUpdatesInit bool

	// UpdatesChan allows to pass custom channel object used for unilateral
	// updates dispatching.
	//
	// You can use this to change default updates buffer size (20) or to split
	// initializaton into phases (which allows to break circular dependencies
	// if you need updates channel before database initialization).
	UpdatesChan chan backend.Update

	// Custom randomness source for UIDVALIDITY values generation.
	PRNG Rand

	// (SQLite3 only) Don't force WAL journaling mode.
	NoWAL bool

	// (SQLite3 only) Use different value for busy_timeout. Default is 50000.
	// To set to 0, use -1 (you probably don't want this).
	BusyTimeout int

	// (SQLite3 only) Use EXCLUSIVE locking mode.
	ExclusiveLock bool

	// (SQLite3 only) Change page cache size. Positive value indicates cache
	// size in pages, negative in KiB. If set 0 - SQLite default will be used.
	CacheSize int

	// (SQLite3 only) Repack database file into minimal amount of disk space on
	// Close.
	// It runs VACUUM and PRAGMA wal_checkpoint(TRUNCATE).
	// Failures of these operations are ignored and don't affect return value
	// of Close.
	MinimizeOnClose bool

	// External storage to use to store message bodies. If specified - all new messages
	// will be saved to it. However, already existing messages stored in DB
	// directly will not be moved.
	ExternalStore ExternalStore

	// Automatically update database schema on imapsql.New.
	AllowSchemaUpgrade bool

	// Hash algorithm to use for authentication passwords when no algorithm is
	// explicitly specified.
	// "sha3-512" and "bcrypt" are supported out of the box. "bcrypt" is used
	// by default.
	// Support for aditional algoritms can be enabled using EnableHashAlgo.
	DefaultHashAlgo string

	// Bcrypt cost value to use when computing password hashes.
	// Default is 10. Can't be smaller than 4, can't be bigger than 31.
	//
	// It is safe to change it, existing records will not be affected.
	BcryptCost int
	// contains filtered or unexported fields
}

Opts structure specifies additional settings that may be set for backend.

Please use names to reference structure members on creation, fields may be reordered or added without major version increment.

type Rand added in v0.2.0 

type Rand interface {
	Uint32() uint32
}

type User added in v0.2.0 

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

func (*User) CreateMailbox added in v0.2.0 

func (u *User) CreateMailbox(name string) error

func (*User) CreateMessageLimit added in v0.2.0 

func (u *User) CreateMessageLimit() *uint32

func (*User) DeleteMailbox added in v0.2.0 

func (u *User) DeleteMailbox(name string) error

func (*User) GetMailbox added in v0.2.0 

func (u *User) GetMailbox(name string) (backend.Mailbox, error)

func (*User) ID added in v0.2.0 

func (u *User) ID() uint64

func (*User) ListMailboxes added in v0.2.0 

func (u *User) ListMailboxes(subscribed bool) ([]backend.Mailbox, error)

func (*User) Logout added in v0.2.0 

func (u *User) Logout() error

func (*User) RenameMailbox added in v0.2.0 

func (u *User) RenameMailbox(existingName, newName string) error

func (*User) SetMessageLimit added in v0.2.0 

func (u *User) SetMessageLimit(val *uint32) error

func (*User) Username added in v0.2.0 

func (u *User) Username() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
imapsql-ctl command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.