package s2k

import "github.com/ProtonMail/go-crypto/openpgp/s2k"

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, memoryExp 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) Mode() Mode
• 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
	// Memory specifies the desired Argon2 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) Mode ¶

func (params *Params) Mode() Mode

func (*Params) Serialize ¶

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

Source Files ¶

s2k.go s2k_cache.go s2k_config.go