...
▽

Package sidh

import "github.com/cloudflare/circl/dh/sidh"
Overview
Index
Examples
Subdirectories

Overview ▾

Package sidh is deprecated, it provides SIDH and SIKE key encapsulation mechanisms.

DEPRECATION NOTICE

SIDH and SIKE are deprecated as were shown vulnerable to a key recovery attack by Castryck-Decru's paper (https://eprint.iacr.org/2022/975). New systems should not rely on this package. This package is frozen.

SIDH and SIKE

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

It comes with implementations of three different field arithmetic implementations sidh.Fp434, sidh.Fp503, and sidh.Fp751. 

| Algorithm | Public Key Size | Shared Secret Size | Ciphertext Size |
|-----------|-----------------|--------------------|-----------------|
| SIDH/p434 |          330    |        110         |       N/A       |
| SIDH/p503 |          378    |        126         |       N/A       |
| SIDH/p751 |          564    |        188         |       N/A       |
| SIKE/p434 |          330    |         16         |       346       |
| SIKE/p503 |          378    |         24         |       402       |
| SIKE/p751 |          564    |         32         |       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, the kem variable 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:

Constants

Identifiers correspond to the bitlength of the prime field characteristic. 

const (
    Fp434 = common.Fp434
    Fp503 = common.Fp503
    Fp751 = common.Fp751
)
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
)

type KEM

SIKE KEM interface.

Deprecated: not cryptographically secure. 

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

▾ Example

Code:

// Alice'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 Alice
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
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())
// Alice 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 Alice's public key
err = kem.Encapsulate(ct, ssE, pubA)
if err != nil {
    panic(err)
}
// Alice 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.

Deprecated: not cryptographically secure.

func NewSike503 

func NewSike503(rng io.Reader) *KEM

NewSike503 instantiates SIKE/p503 KEM.

Deprecated: not cryptographically secure.

func NewSike751 

func NewSike751(rng io.Reader) *KEM

NewSike751 instantiates SIKE/p751 KEM.

Deprecated: not cryptographically secure.

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

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

Deprecated: not cryptographically secure. 

type KeyVariant uint

type PrivateKey

Defines operations on private key

Deprecated: not cryptographically secure. 

type PrivateKey struct {

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

▾ Example

Code:

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

// Alice'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 Alice
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())
// Alice 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 Alice'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.

Deprecated: not cryptographically secure.

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

Defines operations on public key

Deprecated: not cryptographically secure. 

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

func NewPublicKey 

func NewPublicKey(id uint8, v KeyVariant) *PublicKey

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

Deprecated: not cryptographically secure.

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.

Subdirectories

Name Synopsis
..