subtle

Documentation

Overview

Package subtle implements the key wrapping primitive KWP defined in NIST SP 800 38f.

The same encryption mode is also defined in RFC 5649. The NIST document is used here as a primary reference, since it contains a security analysis and further recommendations. In particular, Section 8 of NIST SP 800 38f suggests that the allowed key sizes may be restricted. The implementation in this package requires that the key sizes are in the range MinWrapSize and MaxWrapSize.

The minimum of 16 bytes has been chosen, because 128 bit keys are the smallest key sizes used in tink. Additionally, wrapping short keys with KWP does not use the function W and hence prevents using security arguments based on the assumption that W is a strong pseudorandom. One consequence of using a strong pseudorandom permutation as an underlying function is that leaking partial information about decrypted bytes is not useful for an attack.

The upper bound for the key size is somewhat arbitrary. Setting an upper bound is motivated by the analysis in section A.4 of NIST SP 800 38f: forgery of long messages is simpler than forgery of short messages.

Index

• Constants
• type KWP
  • func NewKWP(wrappingKey []byte) (*KWP, error)
  • func (kwp *KWP) Unwrap(data []byte) ([]byte, error)
  • func (kwp *KWP) Wrap(data []byte) ([]byte, error)

Constants

const (
	// MinWrapSize is the smallest key byte length that may be wrapped.
	MinWrapSize = 16
	// MaxWrapSize is the largest key byte length that may be wrapped.
	MaxWrapSize = 8192
)

Types

type KWP

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

KWP is an implementation of an AES-KWP key wrapping cipher.

func NewKWP

func NewKWP(wrappingKey []byte) (*KWP, error)

NewKWP returns a KWP instance.

The key argument should be the AES wrapping key, either 16 or 32 bytes to select AES-128 or AES-256.

func (*KWP) Unwrap

func (kwp *KWP) Unwrap(data []byte) ([]byte, error)

Unwrap unwraps a wrapped key.

func (*KWP) Wrap

func (kwp *KWP) Wrap(data []byte) ([]byte, error)

Wrap wraps the provided key material.