kyber

package module
v0.0.0-...-a270899 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 30, 2018 License: CC0-1.0 Imports: 5 Imported by: 0

README

Kyber - IND-CCA2-secure Key Encapsulation Mechanism

Yawning Angel (yawning at schwanenlied dot me)

GoDoc

This package implements the Kyber IND-CCA2-secure key encapsulation mechanism (KEM), based on the hardness of solving the learning-with-errors (LWE) problem over module lattices as submitted to the NIST Post-Quantum Cryptography project.

This implementation is a port of the Public Domain reference implementation by Joppe Bos, Léo Ducas, Eike Kiltz , Tancrède Lepoint, Vadim Lyubashevsky, John Schanck, Peter Schwabe, Gregor Seiler, and Damien Stehlé.

Additionally implementations of Kyber.AKE and Kyber.UAKE as presented in the Kyber paper are included for users that seek an authenticated key exchange.

Note that the algorithm is not finalized yet, and may change in a backward incompatible manner in the future. The designers currently recommend combining Kyber with an established pre-quantum algorithm like ECDH, and using the Kyber-768 parameter set.

For more information, see the project home page.

Documentation

Overview

Package kyber implements the Kyber IND-CCA2-secure key encapsulation mechanism (KEM), based on the hardness of solving the learning-with-errors (LWE) problem over module lattices as submitted to the NIST Post-Quantum Cryptography project.

This implementation is a port of the Public Domain reference implementation by Joppe Bos, Léo Ducas, Eike Kiltz , Tancrède Lepoint, Vadim Lyubashevsky, John Schanck, Peter Schwabe, Gregor Seiler, and Damien Stehlé.

Additionally implementations of Kyber.AKE and Kyber.UAKE as presented in the Kyber paper are included for users that seek an authenticated key exchange.

Note that the algorithm is not finalized yet, and may change in a backward incompatible manner in the future. The designers currently recommend combining Kyber with an established pre-quantum algorithm like ECDH, and using the Kyber-768 parameter set.

For more information, see https://pq-crystals.org/kyber/index.shtml.

Example (KeyEncapsulationMechanism) 
// Unauthenticated Key Encapsulation Mechanism (KEM)

// Alice, step 1: Generate a key pair.
alicePublicKey, alicePrivateKey, err := Kyber768.GenerateKeyPair(rand.Reader)
if err != nil {
	panic(err)
}

// Alice, step 2: Send the public key to Bob (Not shown).

// Bob, step 1: Deserialize Alice's public key from the binary encoding.
peerPublicKey, err := Kyber768.PublicKeyFromBytes(alicePublicKey.Bytes())
if err != nil {
	panic(err)
}

// Bob, step 2: Generate the KEM cipher text and shared secret.
cipherText, bobSharedSecret, err := peerPublicKey.KEMEncrypt(rand.Reader)
if err != nil {
	panic(err)
}

// Bob, step 3: Send the cipher text to Alice (Not shown).

// Alice, step 3: Decrypt the KEM cipher text.
aliceSharedSecret := alicePrivateKey.KEMDecrypt(cipherText)

// Alice and Bob have identical values for the shared secrets.
if bytes.Equal(aliceSharedSecret, bobSharedSecret) {
	panic("Shared secrets mismatch")
}

Output:
Example (KeyExchangeMutualAuth) 
// Authenticated Key Exchange (AKE)

// Alice, Bob: Generate a long-term (static) key pair, for authentication,
// the public component of which is shared with the peer prior to the
// actual key exchange.
aliceStaticPublicKey, aliceStaticPrivateKey, err := Kyber768.GenerateKeyPair(rand.Reader)
if err != nil {
	panic(err)
}
bobStaticPublicKey, bobStaticPrivateKey, err := Kyber768.GenerateKeyPair(rand.Reader)
if err != nil {
	panic(err)
}

// Bob, step 1: Initialize the key exchange.
//
// WARNING: The state MUST NOT be use for more than one key exchange,
// successful or not.
bobState, err := aliceStaticPublicKey.NewAKEInitiatorState(rand.Reader)
if err != nil {
	panic(err)
}

// Bob, step 2: Send the key exchange message to Alice (Not shown).

// Alice, step 1: Generates a responder message and shared secret.
aliceMessage, aliceSharedSecret := aliceStaticPrivateKey.AKEResponderShared(rand.Reader, bobState.Message, bobStaticPublicKey)

// Alice, step 2: Send the responder message to Bob (Not shown).

// Bob, step 3: Generate the shared secret.
bobSharedSecret := bobState.Shared(aliceMessage, bobStaticPrivateKey)

// Alice and Bob have identical values for the shared secrets, and each
// party is certain that the peer posesses the appropriate long-term
// private key.
if bytes.Equal(aliceSharedSecret, bobSharedSecret) {
	panic("Shared secrets mismatch")
}

Output:
Example (KeyExchangeUnilateralAuth) 
// Unilaterally-Authenticated Key Exchange (UAKE)

// Alice, step 0: Generate a long-term (static) key pair, the public
// component of which is shared with Bob prior to the actual key exchange.
aliceStaticPublicKey, aliceStaticPrivateKey, err := Kyber768.GenerateKeyPair(rand.Reader)
if err != nil {
	panic(err)
}

// Bob, step 1: Initialize the key exchange.
//
// WARNING: The state MUST NOT be use for more than one key exchange,
// successful or not.
bobState, err := aliceStaticPublicKey.NewUAKEInitiatorState(rand.Reader)
if err != nil {
	panic(err)
}

// Bob, step 2: Send the key exchange message to Alice (Not shown).

// Alice, step 1: Generates a responder message and shared secret.
aliceMessage, aliceSharedSecret := aliceStaticPrivateKey.UAKEResponderShared(rand.Reader, bobState.Message)

// Alice, step 2: Send the responder message to Bob (Not shown).

// Bob, step 3: Generate the shared secret.
bobSharedSecret := bobState.Shared(aliceMessage)

// Alice and Bob have identical values for the shared secrets, and Bob is
// certain that the peer posesses aliceStaticPrivateKey.
if bytes.Equal(aliceSharedSecret, bobSharedSecret) {
	panic("Shared secrets mismatch")
}

Output:

Index

Examples

Constants

View Source 
const (
	// SymSize is the size of the shared key (and certain internal parameters
	// such as hashes and seeds) in bytes.
	SymSize = 32
)

Variables

View Source 
var (
	// ErrInvalidKeySize is the error returned when a byte serailized key is
	// an invalid size.
	ErrInvalidKeySize = errors.New("kyber: invalid key size")

	// ErrInvalidCipherTextSize is the error thrown via a panic when a byte
	// serialized ciphertext is an invalid size.
	ErrInvalidCipherTextSize = errors.New("kyber: invalid ciphertext size")

	// ErrInvalidPrivateKey is the error returned when a byte serialized
	// private key is malformed.
	ErrInvalidPrivateKey = errors.New("kyber: invalid private key")
)
View Source 
var (
	// ErrInvalidMessageSize is the error thrown via a panic when a initator
	// or responder message is an invalid size.
	ErrInvalidMessageSize = errors.New("kyber: invalid message size")

	// ErrParameterSetMismatch is the error thrown via a panic when there
	// is a mismatch between parameter sets.
	ErrParameterSetMismatch = errors.New("kyber: parameter set mismatch")
)
View Source 
var (
	// Kyber512 is the Kyber-512 parameter set, which aims to provide security
	// equivalent to AES-128.
	//
	// This parameter set has a 1632 byte private key, 736 byte public key,
	// and a 800 byte cipher text.
	Kyber512 = newParameterSet("Kyber-512", 2)

	// Kyber768 is the Kyber-768 parameter set, which aims to provide security
	// equivalent to AES-192.
	//
	// This parameter set has a 2400 byte private key, 1088 byte public key,
	// and a 1152 byte cipher text.
	Kyber768 = newParameterSet("Kyber-768", 3)

	// Kyber1024 is the Kyber-1024 parameter set, which aims to provide
	// security equivalent to AES-256.
	//
	// This parameter set has a 3168 byte private key, 1440 byte public key,
	// and a 1504 byte cipher text.
	Kyber1024 = newParameterSet("Kyber-1024", 4)
)

Functions

func IsHardwareAccelerated 

func IsHardwareAccelerated() bool

IsHardwareAccelerated returns true iff the Kyber implementation will use hardware acceleration (eg: AVX2).

Types

type AKEInitiatorState 

type AKEInitiatorState struct {
	// Message is the AKE message to send to the responder.
	Message []byte
	// contains filtered or unexported fields
}

AKEInitiatorState is a initiator AKE instance. Each instance MUST only be used for one key exchange and never reused.

func (*AKEInitiatorState) Shared 

func (s *AKEInitiatorState) Shared(recv []byte, initiatorPrivateKey *PrivateKey) (sharedSecret []byte)

Shared generates a shared secret for the given AKE instance, responder message, and long term initiator private key.

On failures sharedSecret will contain a randomized value. Providing a malformed responder message, or a private key that uses a different ParamterSet than the AKEInitiatorState will result in a panic.

type ParameterSet 

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

ParameterSet is a Kyber parameter set.

func (*ParameterSet) AKEInitiatorMessageSize 

func (p *ParameterSet) AKEInitiatorMessageSize() int

AKEInitiatorMessageSize returns the size of the initiator AKE message in bytes.

func (*ParameterSet) AKEResponderMessageSize 

func (p *ParameterSet) AKEResponderMessageSize() int

AKEResponderMessageSize returns the size of the responder AKE message in bytes.

func (*ParameterSet) CipherTextSize 

func (p *ParameterSet) CipherTextSize() int

CipherTextSize returns the size of a cipher text in bytes.

func (*ParameterSet) GenerateKeyPair 

func (p *ParameterSet) GenerateKeyPair(rng io.Reader) (*PublicKey, *PrivateKey, error)

GenerateKeyPair generates a private and public key parameterized with the given ParameterSet.

func (*ParameterSet) Name 

func (p *ParameterSet) Name() string

Name returns the name of a given ParameterSet.

func (*ParameterSet) PrivateKeyFromBytes 

func (p *ParameterSet) PrivateKeyFromBytes(b []byte) (*PrivateKey, error)

PrivateKeyFromBytes deserializes a byte serialized PrivateKey.

func (*ParameterSet) PrivateKeySize 

func (p *ParameterSet) PrivateKeySize() int

PrivateKeySize returns the size of a private key in bytes.

func (*ParameterSet) PublicKeyFromBytes 

func (p *ParameterSet) PublicKeyFromBytes(b []byte) (*PublicKey, error)

PublicKeyFromBytes deserializes a byte serialized PublicKey.

func (*ParameterSet) PublicKeySize 

func (p *ParameterSet) PublicKeySize() int

PublicKeySize returns the size of a public key in bytes.

func (*ParameterSet) UAKEInitiatorMessageSize 

func (p *ParameterSet) UAKEInitiatorMessageSize() int

UAKEInitiatorMessageSize returns the size of the initiator UAKE message in bytes.

func (*ParameterSet) UAKEResponderMessageSize 

func (p *ParameterSet) UAKEResponderMessageSize() int

UAKEResponderMessageSize returns the size of the responder UAKE message in bytes.

type PrivateKey 

type PrivateKey struct {
	PublicKey
	// contains filtered or unexported fields
}

PrivateKey is a Kyber private key.

func (*PrivateKey) AKEResponderShared 

func (sk *PrivateKey) AKEResponderShared(rng io.Reader, recv []byte, peerPublicKey *PublicKey) (message, sharedSecret []byte)

AKEResponderShared generates a responder message and shared secret given a initiator AKE message and long term initiator public key.

On failures sharedSecret will contain a randomized value. Providing a malformed responder message, or a private key that uses a different ParamterSet than the AKEInitiatorState will result in a panic.

func (*PrivateKey) Bytes 

func (sk *PrivateKey) Bytes() []byte

Bytes returns the byte serialization of a PrivateKey.

func (*PrivateKey) KEMDecrypt 

func (sk *PrivateKey) KEMDecrypt(cipherText []byte) (sharedSecret []byte)

KEMDecrypt generates shared secret for given cipher text via the CCA-secure Kyber key encapsulation mechanism.

On failures, sharedSecret will contain a randomized value. Providing a cipher text that is obviously malformed (too large/small) will result in a panic.

func (*PrivateKey) UAKEResponderShared 

func (sk *PrivateKey) UAKEResponderShared(rng io.Reader, recv []byte) (message, sharedSecret []byte)

UAKEResponderShared generates a responder message and shared secret given a initiator UAKE message.

On failures, sharedSecret will contain a randomized value. Providing a cipher text that is obviously malformed (too large/small) will result in a panic.

type PublicKey 

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

PublicKey is a Kyber public key.

func (*PublicKey) Bytes 

func (pk *PublicKey) Bytes() []byte

Bytes returns the byte serialization of a PublicKey.

func (*PublicKey) KEMEncrypt 

func (pk *PublicKey) KEMEncrypt(rng io.Reader) (cipherText []byte, sharedSecret []byte, err error)

KEMEncrypt generates cipher text and shared secret via the CCA-secure Kyber key encapsulation mechanism.

func (*PublicKey) NewAKEInitiatorState 

func (pk *PublicKey) NewAKEInitiatorState(rng io.Reader) (*AKEInitiatorState, error)

NewAKEInitiatorState creates a new initiator AKE instance.

func (*PublicKey) NewUAKEInitiatorState 

func (pk *PublicKey) NewUAKEInitiatorState(rng io.Reader) (*UAKEInitiatorState, error)

NewUAKEInitiatorState creates a new initiator UAKE instance.

type UAKEInitiatorState 

type UAKEInitiatorState struct {
	// Message is the UAKE message to send to the responder.
	Message []byte
	// contains filtered or unexported fields
}

UAKEInitiatorState is a initiator UAKE instance. Each instance MUST only be used for one key exchange and never reused.

func (*UAKEInitiatorState) Shared 

func (s *UAKEInitiatorState) Shared(recv []byte) (sharedSecret []byte)

Shared generates a shared secret for the given UAKE instance and responder message.

On failures, sharedSecret will contain a randomized value. Providing a cipher text that is obviously malformed (too large/small) will result in a panic.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.