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
- type KWP
- type MessageAuthenticator
- type MessageAuthenticatorDomainType
Examples ¶
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)
Variables ¶
This section is empty.
Functions ¶
func AESGCMDecrypt ¶
AESGCMDecrypt decrypties and verifies ciphertext and additional data using the standard AES GCM mode
func AESGCMEncrypt ¶
AESGCMEncrypt encrypts and authenticates plaintext and additional data using the standard AES GCM mode
func NewKMAC128 ¶
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 ¶
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
Types ¶
type Crypter ¶
type Crypter struct {
}
type KWP ¶
type KWP struct {
// contains filtered or unexported fields
}
KWP is an implementation of an AES-KWP key wrapping cipher.
func NewKWP ¶
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.
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 )
Source Files