s2k

Documentation

Overview

Package s2k implements the various OpenPGP string-to-key transforms as specified in RFC 4800 section 3.7.1, and Argon2 specified in draft-ietf-openpgp-crypto-refresh-08 section 3.7.1.4.

Index

• Constants
• func Argon2(out []byte, in []byte, salt []byte, passes uint8, paralellism uint8, ...)
• func Iterated(out []byte, h hash.Hash, in []byte, salt []byte, count int)
• func Parse(r io.Reader) (f func(out, in []byte), err error)
• func Salted(out []byte, h hash.Hash, in []byte, salt []byte)
• func Serialize(w io.Writer, key []byte, rand io.Reader, passphrase []byte, c *Config) error
• func Simple(out []byte, h hash.Hash, in []byte)
• type Argon2Config
  • func (c *Argon2Config) EncodedMemory() uint8
  • func (c *Argon2Config) Parallelism() uint8
  • func (c *Argon2Config) Passes() uint8
• type Cache
  • func (c *Cache) GetOrComputeDerivedKey(passphrase []byte, params *Params, expectedKeySize int) ([]byte, error)
• type Config
  • func (c *Config) Argon2() *Argon2Config
  • func (c *Config) EncodedCount() uint8
  • func (c *Config) Mode() Mode
• type Mode
• type Params
  • func Generate(rand io.Reader, c *Config) (*Params, error)
  • func ParseIntoParams(r io.Reader) (params *Params, err error)
  • func (params *Params) Dummy() bool
  • func (params *Params) Function() (f func(out, in []byte), err error)
  • func (params *Params) Serialize(w io.Writer) (err error)

Constants

const Argon2SaltSize int = 16

Functions

func Argon2

func Argon2(out []byte, in []byte, salt []byte, passes uint8, paralellism uint8, memoryExp uint8)

Argon2 writes to out the key derived from the password (in) with the Argon2 function (the crypto refresh, section 3.7.1.4)

func Iterated

func Iterated(out []byte, h hash.Hash, in []byte, salt []byte, count int)

Iterated writes to out the result of computing the Iterated and Salted S2K function (RFC 4880, section 3.7.1.3) using the given hash, input passphrase, salt and iteration count.

func Parse

func Parse(r io.Reader) (f func(out, in []byte), err error)

Parse reads a binary specification for a string-to-key transformation from r and returns a function which performs that transform. If the S2K is a special GNU extension that indicates that the private key is missing, then the error returned is errors.ErrDummyPrivateKey.

func Salted

func Salted(out []byte, h hash.Hash, in []byte, salt []byte)

Salted writes to out the result of computing the Salted S2K function (RFC 4880, section 3.7.1.2) using the given hash, input passphrase and salt.

func Serialize

func Serialize(w io.Writer, key []byte, rand io.Reader, passphrase []byte, c *Config) error

Serialize salts and stretches the given passphrase and writes the resulting key into key. It also serializes an S2K descriptor to w. The key stretching can be configured with c, which may be nil. In that case, sensible defaults will be used.

func Simple

func Simple(out []byte, h hash.Hash, in []byte)

Simple writes to out the result of computing the Simple S2K function (RFC 4880, section 3.7.1.1) using the given hash and input passphrase.

Types

type Argon2Config

type Argon2Config struct {
	NumberOfPasses      uint8
	DegreeOfParallelism uint8
	// The memory parameter for Argon2 specifies desired memory usage in kibibytes.
	// For example memory=64*1024 sets the memory cost to ~64 MB.
	Memory uint32
}

Argon2Config stores the Argon2 parameters A nil *Argon2Config is valid and results in all default

func (*Argon2Config) EncodedMemory

func (c *Argon2Config) EncodedMemory() uint8

func (*Argon2Config) Parallelism

func (c *Argon2Config) Parallelism() uint8

func (*Argon2Config) Passes

func (c *Argon2Config) Passes() uint8

type Cache

type Cache map[Params][]byte

Cache stores keys derived with s2k functions from one passphrase to avoid recomputation if multiple items are encrypted with the same parameters.

func (*Cache) GetOrComputeDerivedKey

func (c *Cache) GetOrComputeDerivedKey(passphrase []byte, params *Params, expectedKeySize int) ([]byte, error)

GetOrComputeDerivedKey tries to retrieve the key for the given s2k parameters from the cache. If there is no hit, it derives the key with the s2k function from the passphrase, updates the cache, and returns the key.

type Config

type Config struct {
	// S2K (String to Key) mode, used for key derivation in the context of secret key encryption
	// and passphrase-encrypted data. Either s2k.Argon2S2K or s2k.IteratedSaltedS2K may be used.
	// If the passphrase is a high-entropy key, indicated by setting PassphraseIsHighEntropy to true,
	// s2k.SaltedS2K can also be used.
	// Note: Argon2 is the strongest option but not all OpenPGP implementations are compatible with it
	//(pending standardisation).
	// 0 (simple), 1(salted), 3(iterated), 4(argon2)
	// 2(reserved) 100-110(private/experimental).
	S2KMode Mode
	// Only relevant if S2KMode is not set to s2k.Argon2S2K.
	// Hash is the default hash function to be used. If
	// nil, SHA256 is used.
	Hash crypto.Hash
	// Argon2 parameters for S2K (String to Key).
	// Only relevant if S2KMode is set to s2k.Argon2S2K.
	// If nil, default parameters are used.
	// For more details on the choice of parameters, see https://tools.ietf.org/html/rfc9106#section-4.
	Argon2Config *Argon2Config
	// Only relevant if S2KMode is set to s2k.IteratedSaltedS2K.
	// Iteration count for Iterated S2K (String to Key). It
	// determines the strength of the passphrase stretching when
	// the said passphrase is hashed to produce a key. S2KCount
	// should be between 65536 and 65011712, inclusive. If Config
	// is nil or S2KCount is 0, the value 16777216 used. Not all
	// values in the above range can be represented. S2KCount will
	// be rounded up to the next representable value if it cannot
	// be encoded exactly. When set, it is strongly encrouraged to
	// use a value that is at least 65536. See RFC 4880 Section
	// 3.7.1.3.
	S2KCount int
	// Indicates whether the passphrase passed by the application is a
	// high-entropy key (e.g. it's randomly generated or derived from
	// another passphrase using a strong key derivation function).
	// When true, allows the S2KMode to be s2k.SaltedS2K.
	// When the passphrase is not a high-entropy key, using SaltedS2K is
	// insecure, and not allowed by draft-ietf-openpgp-crypto-refresh-08.
	PassphraseIsHighEntropy bool
}

Config collects configuration parameters for s2k key-stretching transformations. A nil *Config is valid and results in all default values.

func (*Config) Argon2

func (c *Config) Argon2() *Argon2Config

func (*Config) EncodedCount

func (c *Config) EncodedCount() uint8

EncodedCount get encoded count

func (*Config) Mode

func (c *Config) Mode() Mode

type Mode

type Mode uint8

const (
	SimpleS2K         Mode = 0
	SaltedS2K         Mode = 1
	IteratedSaltedS2K Mode = 3
	Argon2S2K         Mode = 4
	GnuS2K            Mode = 101
)

Defines the default S2KMode constants

0 (simple), 1(salted), 3(iterated), 4(argon2)

type Params

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

Params contains all the parameters of the s2k packet

func Generate

func Generate(rand io.Reader, c *Config) (*Params, error)

Generate generates valid parameters from given configuration. It will enforce the Iterated and Salted or Argon2 S2K method.

func ParseIntoParams

func ParseIntoParams(r io.Reader) (params *Params, err error)

ParseIntoParams reads a binary specification for a string-to-key transformation from r and returns a struct describing the s2k parameters.

func (*Params) Dummy

func (params *Params) Dummy() bool

func (*Params) Function

func (params *Params) Function() (f func(out, in []byte), err error)

func (*Params) Serialize

func (params *Params) Serialize(w io.Writer) (err error)