openpgp

README

Use with caution

While this middleware is mostly complete, it has not been properly tested by a large user base and their corresponding edge-cases. Please keep this in mind when using this middlware. work, you will need the main branch of the go-mail package. The latest releases do not provide all the functionality required for this middleware to work.

OpenPGP middleware

This middleware allows to encrypt the mail body and the attachments of a go-mail *Msg before sending it.

PGP Schme support

This middleware supports two PGP encoding schemes:

• PGP/Inline
• PGP/MIME

Please note, that PGP/Inline does only work with plain text mails. Any mail message (alternative) body part of type text/html will be discarded in the final output of the mail.

Example

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/wneessen/go-mail"
	"github.com/wneessen/go-mail-middleware/openpgp"
)

const pubKey = `-----BEGIN PGP PUBLIC KEY BLOCK-----
[...]
-----END PGP PUBLIC KEY BLOCK-----`

func main() {
	// First we need a config for our OpenPGP middleware
	//
	// In case your public key is in byte slice format or even a file, we provide two
	// helper methods:
	// - openpgp.NewConfigFromPubKeyBytes()
	// - openpgp.NewConfigFromPubKeyFile()
	mc, err := openpgp.NewConfig(pubKey, openpgp.WithScheme(openpgp.SchemePGPInline))
	if err != nil {
		fmt.Printf("failed to create new config: %s\n", err)
		os.Exit(1)
	}
	mw := openpgp.NewMiddleware(mc)

	// Finally we create a new mail.Msg with our middleware assigned
	m := mail.NewMsg(mail.WithMiddleware(mw))
	if err := m.From("toni.sender@example.com"); err != nil {
		log.Fatalf("failed to set From address: %s", err)
	}
	if err := m.To("tina.recipient@example.com"); err != nil {
		log.Fatalf("failed to set To address: %s", err)
	}
	m.Subject("This is my first mail with go-mail!")
	m.SetBodyString(mail.TypeTextPlain, "Do you like this mail? I certainly do!")
	c, err := mail.NewClient("smtp.example.com", mail.WithPort(25),
		mail.WithSMTPAuth(mail.SMTPAuthPlain),
		mail.WithUsername("my_username"), mail.WithPassword("extremely_secret_pass"))
	if err != nil {
		log.Fatalf("failed to create mail client: %s", err)
	}
	if err := c.DialAndSend(m); err != nil {
		log.Fatalf("failed to send mail: %s", err)
	}
}

Documentation

Overview

Package openpgp implements a go-mail middleware to encrypt mails via OpenPGP

Index

• Constants
• Variables
• type Action
  • func (a Action) String() string
• type Config
  • func NewConfig(pr, pu string, o ...Option) (*Config, error)
  • func NewConfigFromKeyFiles(pr, pu string, o ...Option) (*Config, error)
  • func NewConfigFromKeysByteSlices(pr, pu []byte, o ...Option) (*Config, error)
  • func NewConfigFromPrivKeyByteSlice(p []byte, o ...Option) (*Config, error)
  • func NewConfigFromPrivKeyFile(f string, o ...Option) (*Config, error)
  • func NewConfigFromPubKeyByteSlice(p []byte, o ...Option) (*Config, error)
  • func NewConfigFromPubKeyFile(f string, o ...Option) (*Config, error)
• type Middleware
  • func NewMiddleware(c *Config) *Middleware
  • func (m *Middleware) Handle(msg *mail.Msg) *mail.Msg
  • func (m *Middleware) Type() mail.MiddlewareType
• type Option
  • func WithAction(a Action) Option
  • func WithLogger(l *log.Logger) Option
  • func WithPrivKeyPass(p string) Option
  • func WithScheme(s PGPScheme) Option
• type PGPScheme
  • func (s PGPScheme) String() string

Constants

const (
	// Type is the type of Middleware
	Type mail.MiddlewareType = "openpgp"
	// Version is the version number of the Middleware
	Version = "0.0.1"
)

Variables

var (
	// ErrNoPrivKey should be returned if a private key is needed but not provided
	ErrNoPrivKey = errors.New("no private key provided")
	// ErrNoPubKey should be returned if a public key is needed but not provided
	ErrNoPubKey = errors.New("no public key provided")
	// ErrUnsupportedAction should be returned if a not supported action is set
	ErrUnsupportedAction = errors.New("unsupported action")
)

Types

type Action

type Action int

Action is an alias type for an int

const (
	// ActionEncrypt will only encrypt the mail body but not sign the outcome
	ActionEncrypt Action = iota
	// ActionEncryptAndSign will encrypt the mail body and sign the the outcome accordingly
	ActionEncryptAndSign
	// ActionSign will only sign the mail body but not encrypt any data
	ActionSign
)

func (Action) String

func (a Action) String() string

String satisfies the fmt.Stringer interface for the Action type

type Config

type Config struct {
	// Action represents the encryption/signing action that the Middlware should perform
	Action Action
	// Logger represents a log that satisfies the log.Logger interface
	Logger *log.Logger
	// PrivKey represents the OpenPGP/GPG private key part used for signing the mail
	PrivKey string
	// PublicKey represents the OpenPGP/GPG public key used for encrypting the mail
	PublicKey string
	// Schema represents one of the supported PGP encryption schemes
	Scheme PGPScheme
	// contains filtered or unexported fields
}

Config is the confiuration to use in Middleware creation

func NewConfig

func NewConfig(pr, pu string, o ...Option) (*Config, error)

NewConfig returns a new Config struct. All values can be prefilled/overriden using the With*() Option methods

func NewConfigFromKeyFiles

func NewConfigFromKeyFiles(pr, pu string, o ...Option) (*Config, error)

NewConfigFromKeyFiles returns a new Config from a given OpenPGP/GPG private and public key files.

func NewConfigFromKeysByteSlices

func NewConfigFromKeysByteSlices(pr, pu []byte, o ...Option) (*Config, error)

NewConfigFromKeysByteSlices returns a new Config from a given OpenPGP/GPG public and private keys byte slices.

func NewConfigFromPrivKeyByteSlice

func NewConfigFromPrivKeyByteSlice(p []byte, o ...Option) (*Config, error)

NewConfigFromPrivKeyByteSlice returns a new Config from a given OpenPGP/GPG private key byte slice.

func NewConfigFromPrivKeyFile

func NewConfigFromPrivKeyFile(f string, o ...Option) (*Config, error)

NewConfigFromPrivKeyFile returns a new Config from a given OpenPGP/GPG private key file.

func NewConfigFromPubKeyByteSlice

func NewConfigFromPubKeyByteSlice(p []byte, o ...Option) (*Config, error)

NewConfigFromPubKeyByteSlice returns a new Config from a given OpenPGP/GPG public key byte slice.

func NewConfigFromPubKeyFile

func NewConfigFromPubKeyFile(f string, o ...Option) (*Config, error)

NewConfigFromPubKeyFile returns a new Config from a given OpenPGP/GPG public key file.

type Middleware

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

Middleware is the middleware struct for the openpgp middleware

func NewMiddleware

func NewMiddleware(c *Config) *Middleware

NewMiddleware returns a new Middleware from a given Config. The returned Middleware satisfies the mail.Middleware interface

func (*Middleware) Handle

func (m *Middleware) Handle(msg *mail.Msg) *mail.Msg

Handle is the handler method that satisfies the mail.Middleware interface

func (*Middleware) Type

func (m *Middleware) Type() mail.MiddlewareType

Type returns the MiddlewareType for this Middleware

type Option

type Option func(cfg *Config)

Option returns a function that can be used for grouping SignerConfig options

func WithAction

func WithAction(a Action) Option

WithAction sets a Action for the Config

func WithLogger

func WithLogger(l *log.Logger) Option

WithLogger sets a slog.Logger for the Config

func WithPrivKeyPass

func WithPrivKeyPass(p string) Option

WithPrivKeyPass sets a passphrase for the PrivKey in the Config

func WithScheme

func WithScheme(s PGPScheme) Option

WithScheme sets a PGPScheme for the Config

type PGPScheme

type PGPScheme int

PGPScheme is an alias type for an int

const (
	// SchemePGPInline represents the PGP/Inline scheme
	//
	// Note: Inline PGP only supports plain text mails. Content bodies of type
	// HTML (or alternative body parts of the same type) will be ignored
	SchemePGPInline PGPScheme = iota
	// SchemePGPMIME represents the OpenPGP/MIME (RFC 4880 and 3156) scheme
	SchemePGPMIME // Not supported yet
)

func (PGPScheme) String

func (s PGPScheme) String() string

String satisfies the fmt.Stringer interface for the PGPScheme type