crypt

Documentation

Overview

Copyright 2020 CYBERCRYPT

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Package kwp 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.

Copyright 2020 CYBERCRYPT

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Index

• Constants
• func AESGCMDecrypt(data, aad, nonce, key []byte, tagLen int) error
• func AESGCMEncrypt(data, aad, nonce, key []byte, tagLen int) error
• func NewKMAC128(key []byte, tagSize int, customizationString []byte) hash.Hash
• func NewKMAC256(key []byte, tagSize int, customizationString []byte) hash.Hash
• func Random(n int) ([]byte, error)
• type Crypter
  • func (c *Crypter) Decrypt(ciphertext, aad, key []byte) ([]byte, error)
  • func (c *Crypter) Encrypt(plaintext, aad, key []byte) ([]byte, error)
• type KWP
  • func NewKWP(wrappingKey []byte) (*KWP, error)
  • func (kwp *KWP) Unwrap(data []byte) ([]byte, error)
  • func (kwp *KWP) Wrap(data []byte) ([]byte, error)
• type MessageAuthenticator
  • func NewMessageAuthenticator(ask []byte) (*MessageAuthenticator, error)
  • func (s *MessageAuthenticator) Tag(domain MessageAuthenticatorDomainType, msg []byte) ([]byte, error)
  • func (s *MessageAuthenticator) Verify(domain MessageAuthenticatorDomainType, msg, msgTag []byte) (bool, error)
• type MessageAuthenticatorDomainType

Examples

• NewKMAC256

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
)

const Overhead = int(tagLength + nonceLength)

Functions

func AESGCMDecrypt

func AESGCMDecrypt(data, aad, nonce, key []byte, tagLen int) error

AESGCMDecrypt decrypties and verifies ciphertext and additional data using the standard AES GCM mode

func AESGCMEncrypt

func AESGCMEncrypt(data, aad, nonce, key []byte, tagLen int) error

AESGCMEncrypt encrypts and authenticates plaintext and additional data using the standard AES GCM mode

func NewKMAC128

func NewKMAC128(key []byte, tagSize int, customizationString []byte) hash.Hash

NewKMAC128 returns a new KMAC hash providing 128 bits of security using the given key, which must have 16 bytes or more, generating the given tagSize bytes output and using the given customizationString. Note that unlike other hash implementations in the standard library, the returned Hash does not implement encoding.BinaryMarshaler or encoding.BinaryUnmarshaler.

func NewKMAC256

func NewKMAC256(key []byte, tagSize int, customizationString []byte) hash.Hash

NewKMAC256 returns a new KMAC hash providing 256 bits of security using the given key, which must have 32 bytes or more, generating the given tagSize bytes output and using the given customizationString. Note that unlike other hash implementations in the standard library, the returned Hash does not implement encoding.BinaryMarshaler or encoding.BinaryUnmarshaler.

Example

key := []byte("this is a secret key; you should generate a strong random key that's at least 32 bytes long")
tag := make([]byte, 16)
msg := []byte("The quick brown fox jumps over the lazy dog")
// Example 1: Simple KMAC
k := NewKMAC256(key, len(tag), []byte("Partition1"))
//nolint: errcheck
k.Write(msg)
k.Sum(tag[:0])
fmt.Println(hex.EncodeToString(tag))
// Example 2: Different customization string produces different digest
k = NewKMAC256(key, 16, []byte("Partition2"))
//nolint: errcheck
k.Write(msg)
k.Sum(tag[:0])
fmt.Println(hex.EncodeToString(tag))

Output:

3814d78758add078334b8ab9e5c4f942
3762371e99e1e01ab17742b95c0360da

func Random

func Random(n int) ([]byte, error)

Random returns n cryptographically secure random bytes

Types

type Crypter

type Crypter struct {
}

func (*Crypter) Decrypt

func (c *Crypter) Decrypt(ciphertext, aad, key []byte) ([]byte, error)

Decrypt decrypts a ciphertext with additional associated data (aad) using the provided key returning the resulting plaintext. ciphertext is modified during this operation.

func (*Crypter) Encrypt

func (c *Crypter) Encrypt(plaintext, aad, key []byte) ([]byte, error)

Encrypt encrypts a plaintext with additional associated data (aad) using the provided key returning the resulting ciphertext. The backing array of plaintext is likely modified during this operation.

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.

type MessageAuthenticator

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

MessageAuthenticator encapsulates a symmetric key used for tagging msgs and verifying msgs + tags

func NewMessageAuthenticator

func NewMessageAuthenticator(ask []byte) (*MessageAuthenticator, error)

NewMessageAuthenticator creates a new MessageAuthenticator and derives all domain keys

func (*MessageAuthenticator) Tag

func (s *MessageAuthenticator) Tag(domain MessageAuthenticatorDomainType, msg []byte) ([]byte, error)

Tag returns a tag for the msg

func (*MessageAuthenticator) Verify

func (s *MessageAuthenticator) Verify(domain MessageAuthenticatorDomainType, msg, msgTag []byte) (bool, error)

Verify returns if a msg and its tags are valid

type MessageAuthenticatorDomainType

type MessageAuthenticatorDomainType uint64

MessageAuthenticatorDomainType represents the different tagging Domains of the MessageAuthenticator

const (
	UsersDomain MessageAuthenticatorDomainType = iota
	AccessObjectsDomain
	TokenDomain
	DomainLimit
)