README
¶
pgxmagic
pgxmagic is a pgx-driven implementation of certmagic.Storage designed to fit in to an existing golang+pgx codebase.
Features
- Uses an existing pgxpool: No need to maintain a separate database connection just for CertMagic
- Session-level advisory locks: Uses
pg_try_advisory_lockto handle distributed locking - Migrations are optional: Convenience method to do this for you, but only if you want.
- Focus on correctness: Complete implementation of
certmagic.Storagewith a full test suite. - Optional encryption: An
EncryptedStorageadapter exists to allow for encryption of values.
Usage
Create table
Optionally, add the following as a database migration.
If you'd prefer not to, you can call storage.Migrate() to do this idempotently instead.
CREATE TABLE IF NOT EXISTS certmagic_data (
key TEXT PRIMARY KEY,
value bytea,
modified timestamptz DEFAULT NOW()
);
Without encryption
Certificates are stored in the clear in the database
storage := pgxmagic.NewStorage(pool)
err := storage.Migrate(context.Background()) // Optional, or manually create table.
With encryption
Certificates are stored encrypted in the database -- in this case, encrypted with AES-256.
storage := pgxmagic.NewEncryptedStorage(
pool,
pgxmagic.NewAES256Encrypter("correct horse battery staple"),
)
Not supported yet
- No Caddy plugin: This was built to slot into an existing go codebase that's using CertMagic directly. A plugin could easily be created if needed though.
Documentation
¶
Index ¶
- type AES256Encrypter
- type EncryptedStorage
- type Encrypter
- type Locker
- type Storage
- func (s *Storage) Delete(ctx context.Context, key string) error
- func (s *Storage) Exists(ctx context.Context, key string) bool
- func (s *Storage) List(ctx context.Context, path string, recursive bool) ([]string, error)
- func (s *Storage) Load(ctx context.Context, key string) ([]byte, error)
- func (s *Storage) Lock(ctx context.Context, name string) error
- func (s *Storage) Migrate(ctx context.Context) error
- func (s *Storage) Stat(ctx context.Context, key string) (certmagic.KeyInfo, error)
- func (s *Storage) Store(ctx context.Context, key string, value []byte) error
- func (s *Storage) Unlock(ctx context.Context, name string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AES256Encrypter ¶
type AES256Encrypter struct {
// contains filtered or unexported fields
}
func NewAES256Encrypter ¶
func NewAES256Encrypter(key string) *AES256Encrypter
NewAES256Encrypter returns an Encrypter that uses AES-256. If "key" is not 32 bytes, it is hashed into a 32 byte value using sha256.
func (*AES256Encrypter) Encrypt ¶
func (e *AES256Encrypter) Encrypt(src []byte) []byte
type EncryptedStorage ¶
func NewEncryptedStorage ¶
func NewEncryptedStorage(source certmagic.Storage, encrypter Encrypter) *EncryptedStorage
type Locker ¶
type Locker struct {
// contains filtered or unexported fields
}
Locker implements a basic distributed lock using session-level advisory locks, which have useful properties: (1) Locks are auto-released if a connection session ends, e.g. the client crashes, and (2) Locking and unlocking don't write, and so rule out any risk of table bloat.
As with any distributed lock, there are trade-offs: Locks can end up "held" by multiple instances (from the perspective of that instance) if the connection to the postgres server is lost after acquisition, as locks are auto-released at the end of a connection session, and there is no way to know when a session has failed short of trying to use it.
In the real world this should be fine -- CertMagic uses locks to reduce redundant expensive work rather than to prevent data races, and postgres connections tend to be extremely stable.
func (*Locker) Lock ¶
Lock acquires the lock 'name', blocking until it can do so. If the lock is already held, its status is polled every 1s.
type Storage ¶
type Storage struct {
// contains filtered or unexported fields
}
func NewStorage ¶
func (*Storage) Delete ¶
Delete "deletes the named key. If the name is a directory (i.e. prefix of other keys), all keys prefixed by this key should be deleted. An error should be returned only if the key still exists when the method returns."
func (*Storage) Exists ¶
Exists "returns true if the key exists either as a directory (prefix to other keys) or a file, and there was no error checking."
func (*Storage) List ¶
List returns all keys in the given path. If recursive is true, non-terminal keys will be enumerated (i.e. "directories" should be walked); otherwise, only keys prefixed exactly by prefix will be listed.
func (*Storage) Load ¶
Load "Uses exact key match because "Keys passed into Load and Store always have "file" semantics"
func (*Storage) Migrate ¶
Migrate can be manually invoked to ensure the certmagic_data table exists. It is not invoked automatically to allow for table setup to be part of whatever existing migration system you might have. Idempotent, so can be run as part of initialization.
Table structure matches that of travisjeffery/certmagic-sqlstorage and yroc92/postgres-storage
Source Files