sidh

Documentation

Overview

Package sidh provides implementation of experimental post-quantum Supersingular Isogeny Diffie-Hellman (SIDH) as well as Supersingular Isogeny Key Encapsulation (SIKE).

It comes with implementations of 2 different field arithmetic implementations sidh.Fp503 and sidh.Fp751.

| Algorithm | Public Key Size | Shared Secret Size | Ciphertext Size |
|-----------|-----------------|--------------------|-----------------|
| SIDH/p503 |          376    |        126         | N/A             |
| SIDH/p751 |          564    |        188         | N/A             |
| SIKE/p503 |          376    |         16         | 402             |
| SIKE/p751 |          564    |         24         | 596             |

In order to instantiate SIKE/p751 KEM one needs to create a KEM object and allocate internal structures. This can be done with NewSike751 helper. After that kem can be used multiple times.

var kem = sike.NewSike751(rand.Reader)
kem.Encapsulate(ciphertext, sharedSecret, publicBob)
kem.Decapsulate(sharedSecret, privateBob, PublicBob, ciphertext)

Code is optimized for AMD64 and aarch64. Generic implementation is provided for other architectures.

References: - [SIDH] https://eprint.iacr.org/2011/506 - [SIKE] http://www.sike.org/files/SIDH-spec.pdf

Index

• Constants
• type KEM
  • func NewSike434(rng io.Reader) *KEM
  • func NewSike503(rng io.Reader) *KEM
  • func NewSike751(rng io.Reader) *KEM
  • func (c *KEM) Allocate(id uint8, rng io.Reader)
  • func (c *KEM) CiphertextSize() int
  • func (c *KEM) Decapsulate(secret []byte, prv *PrivateKey, pub *PublicKey, ciphertext []byte) error
  • func (c *KEM) Encapsulate(ciphertext, secret []byte, pub *PublicKey) error
  • func (c *KEM) PrivateKeySize() int
  • func (c *KEM) PublicKeySize() int
  • func (c *KEM) Reset()
  • func (c *KEM) SharedSecretSize() int
• type KeyVariant
• type PrivateKey
  • func NewPrivateKey(id uint8, v KeyVariant) *PrivateKey
  • func (prv *PrivateKey) DeriveSecret(ss []byte, pub *PublicKey)
  • func (prv *PrivateKey) Export(out []byte)
  • func (prv *PrivateKey) Generate(rand io.Reader) error
  • func (prv *PrivateKey) GeneratePublicKey(pub *PublicKey)
  • func (prv *PrivateKey) Import(input []byte) error
  • func (prv *PrivateKey) SharedSecretSize() int
  • func (prv *PrivateKey) Size() int
  • func (key *PrivateKey) Variant() KeyVariant
• type PublicKey
  • func NewPublicKey(id uint8, v KeyVariant) *PublicKey
  • func (pub *PublicKey) Export(out []byte)
  • func (pub *PublicKey) Import(input []byte) error
  • func (pub *PublicKey) Size() int
  • func (key *PublicKey) Variant() KeyVariant

Examples

• KEM
• PrivateKey

Constants

const (
	Fp434 = common.Fp434
	Fp503 = common.Fp503
	Fp751 = common.Fp751
)

Id's correspond to bitlength of the prime field characteristic Currently Fp751 is the only one supported by this implementation

const (

	// 001 - SIDH: corresponds to 2-torsion group
	KeyVariantSidhA KeyVariant = 1 << 0
	// 010 - SIDH: corresponds to 3-torsion group
	KeyVariantSidhB = 1 << 1
	// 110 - SIKE
	KeyVariantSike = 1<<2 | KeyVariantSidhB
)

Types

type KEM

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

SIKE KEM interface.

Example

// Allice's key pair
prvA := NewPrivateKey(Fp503, KeyVariantSike)
pubA := NewPublicKey(Fp503, KeyVariantSike)
// Bob's key pair
prvB := NewPrivateKey(Fp503, KeyVariantSike)
pubB := NewPublicKey(Fp503, KeyVariantSike)
// Generate keypair for Allice
err := prvA.Generate(rand.Reader)
if err != nil {
	panic(err)
}
prvA.GeneratePublicKey(pubA)
// Generate keypair for Bob
err = prvB.Generate(rand.Reader)
if err != nil {
	panic(err)
}
prvB.GeneratePublicKey(pubB)
// Initialize internal KEM structures
var kem = NewSike503(rand.Reader)
// Create buffers for ciphertext, shared secret received
// from encapsulation and shared secret from decapsulation
ct := make([]byte, kem.CiphertextSize())
ssE := make([]byte, kem.SharedSecretSize())
ssD := make([]byte, kem.SharedSecretSize())
// Allice performs encapsulation with Bob's public key
err = kem.Encapsulate(ct, ssE, pubB)
if err != nil {
	panic(err)
}
// Bob performs decapsulation with his key pair
err = kem.Decapsulate(ssD, prvB, pubB, ct)
if err != nil {
	panic(err)
}
fmt.Printf("%t\n", bytes.Equal(ssE, ssD))

// Bob performs encapsulation with Allices's public key
err = kem.Encapsulate(ct, ssE, pubA)
if err != nil {
	panic(err)
}
// Allice performs decapsulation with hers key pair
err = kem.Decapsulate(ssD, prvA, pubA, ct)
if err != nil {
	panic(err)
}
fmt.Printf("%t\n", bytes.Equal(ssE, ssD))

Output:

true
true

func NewSike434

func NewSike434(rng io.Reader) *KEM

NewSike434 instantiates SIKE/p434 KEM.

func NewSike503

func NewSike503(rng io.Reader) *KEM

NewSike503 instantiates SIKE/p503 KEM.

func NewSike751

func NewSike751(rng io.Reader) *KEM

NewSike751 instantiates SIKE/p751 KEM.

func (*KEM) Allocate

func (c *KEM) Allocate(id uint8, rng io.Reader)

Allocate allocates KEM object for multiple SIKE operations. The rng must be cryptographically secure PRNG.

func (*KEM) CiphertextSize

func (c *KEM) CiphertextSize() int

Returns size of resulting ciphertext.

func (*KEM) Decapsulate

func (c *KEM) Decapsulate(secret []byte, prv *PrivateKey, pub *PublicKey, ciphertext []byte) error

Decapsulate given the keypair and ciphertext as inputs, Decapsulate outputs a shared secret if plaintext verifies correctly, otherwise function outputs random value. Decapsulation may panic in case input is wrongly formatted, in particular, size of the 'ciphertext' must be exactly equal to c.CiphertextSize().

func (*KEM) Encapsulate

func (c *KEM) Encapsulate(ciphertext, secret []byte, pub *PublicKey) error

Encapsulate receives the public key and generates SIKE ciphertext and shared secret. The generated ciphertext is used for authentication. Error is returned in case PRNG fails. Function panics in case wrongly formatted input was provided.

func (*KEM) PrivateKeySize

func (c *KEM) PrivateKeySize() int

Size returns size of the private key in bytes.

func (*KEM) PublicKeySize

func (c *KEM) PublicKeySize() int

PublicKeySize returns size of the public key in bytes.

func (*KEM) Reset

func (c *KEM) Reset()

Resets internal state of KEM. Function should be used after Allocate and between subsequent calls to Encapsulate and/or Decapsulate.

func (*KEM) SharedSecretSize

func (c *KEM) SharedSecretSize() int

Returns size of resulting shared secret.

type KeyVariant

type KeyVariant uint

I keep it bool in order to be able to apply logical NOT.

type PrivateKey

type PrivateKey struct {

	// Secret key
	Scalar []byte
	// Used only by KEM
	S []byte
	// contains filtered or unexported fields
}

Defines operations on private key

Example

// import "github.com/fanym919/circl/dh/sidh"

// Allice's key pair
prvA := NewPrivateKey(Fp503, KeyVariantSidhA)
pubA := NewPublicKey(Fp503, KeyVariantSidhA)
// Bob's key pair
prvB := NewPrivateKey(Fp503, KeyVariantSidhB)
pubB := NewPublicKey(Fp503, KeyVariantSidhB)
// Generate keypair for Allice
err := prvA.Generate(rand.Reader)
if err != nil {
	fmt.Print(err)
}
prvA.GeneratePublicKey(pubA)
// Generate keypair for Bob
err = prvB.Generate(rand.Reader)
if err != nil {
	fmt.Print(err)
}
prvB.GeneratePublicKey(pubB)
// Buffers storing shared secret
ssA := make([]byte, prvA.SharedSecretSize())
ssB := make([]byte, prvA.SharedSecretSize())
// Allice calculates shared secret with hers private
// key and Bob's public key
prvA.DeriveSecret(ssA[:], pubB)
// Bob calculates shared secret with hers private
// key and Allice's public key
prvB.DeriveSecret(ssB[:], pubA)
// Check if ssA == ssB
fmt.Printf("%t\n", bytes.Equal(ssA, ssB))

Output:

true

func NewPrivateKey

func NewPrivateKey(id uint8, v KeyVariant) *PrivateKey

NewPrivateKey initializes private key. Usage of this function guarantees that the object is correctly initialized.

func (*PrivateKey) DeriveSecret

func (prv *PrivateKey) DeriveSecret(ss []byte, pub *PublicKey)

Computes a SIDH shared secret. Function requires that pub has different KeyVariant than prv. Length of returned output is 2*ceil(log_2 P)/8), where P is a prime defining finite field.

Caller must make sure key SIDH key pair is not used more than once.

func (*PrivateKey) Export

func (prv *PrivateKey) Export(out []byte)

Exports currently stored key. In case structure hasn't been filled with key data returned byte string is filled with zeros.

func (*PrivateKey) Generate

func (prv *PrivateKey) Generate(rand io.Reader) error

Generates random private key for SIDH or SIKE. Generated value is formed as little-endian integer from key-space <2^(e2-1)..2^e2 - 1> for KeyVariant_A or <2^(s-1)..2^s - 1>, where s = floor(log_2(3^e3)), for KeyVariant_B.

Returns error in case user provided RNG fails.

func (*PrivateKey) GeneratePublicKey

func (prv *PrivateKey) GeneratePublicKey(pub *PublicKey)

Generates public key.

func (*PrivateKey) Import

func (prv *PrivateKey) Import(input []byte) error

Import clears content of the private key currently stored in the structure and imports key from octet string. In case of SIKE, the random value 'S' must be prepended to the value of actual private key (see SIKE spec for details). Function doesn't import public key value to PrivateKey object.

func (*PrivateKey) SharedSecretSize

func (prv *PrivateKey) SharedSecretSize() int

Size returns size of the shared secret.

func (*PrivateKey) Size

func (prv *PrivateKey) Size() int

Size returns size of the private key in bytes.

func (*PrivateKey) Variant

func (key *PrivateKey) Variant() KeyVariant

Accessor to key variant.

type PublicKey

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

Defines operations on public key

func NewPublicKey

func NewPublicKey(id uint8, v KeyVariant) *PublicKey

NewPublicKey initializes public key. Usage of this function guarantees that the object is correctly initialized.

func (*PublicKey) Export

func (pub *PublicKey) Export(out []byte)

Exports currently stored key. In case structure hasn't been filled with key data returned byte string is filled with zeros.

func (*PublicKey) Import

func (pub *PublicKey) Import(input []byte) error

Import clears content of the public key currently stored in the structure and imports key stored in the byte string. Returns error in case byte string size is wrong. Doesn't perform any validation.

func (*PublicKey) Size

func (pub *PublicKey) Size() int

Size returns size of the public key in bytes.

func (*PublicKey) Variant

func (key *PublicKey) Variant() KeyVariant

Accessor to key variant.