Skip to content

std.crypto.25519.x25519

Standard libraryZig 0.17.1Official documentation
Sourcestd/crypto/25519/x25519.zig

Source line 1

std.crypto.25519.x25519.crypto

alias

Source line 2

Alias of std.crypto

std.crypto.25519.x25519.EncodingError

alias

Source line 8

Alias of std.crypto.errors.EncodingError

std.crypto.25519.x25519.fmt

alias

Source line 4

Alias of std.fmt

std.crypto.25519.x25519.htest

constant

Source line 86

std.crypto.25519.x25519.IdentityElementError

alias

Source line 9

Alias of std.crypto.errors.IdentityElementError

std.crypto.25519.x25519.mem

alias

Source line 3

Alias of std.mem

std.crypto.25519.x25519.Sha512

alias

Source line 6

Alias of std.crypto.sha2.Sha512

std.crypto.25519.x25519.std

alias

Source line 1

Alias of std

std.crypto.25519.x25519.WeakPublicKeyError

alias

Source line 10

Alias of std.crypto.errors.WeakPublicKeyError

std.crypto.25519.x25519.X25519

namespace

Source line 13

X25519 DH function.

std.crypto.25519.x25519.X25519.Curve

alias

Source line 15

The underlying elliptic curve.

Alias of std.crypto.25519.curve25519.Curve25519

std.crypto.25519.x25519.X25519.KeyPair

container

Source line 26

An X25519 key pair.

Fields

public_key: [public_length]u8

Public part.

secret_key: [secret_length]u8

Secret part.

std.crypto.25519.x25519.X25519.KeyPair.fromEd25519

function

Source line 50

Create a key pair from an Ed25519 key pair

pub fn fromEd25519(ed25519_key_pair: crypto.sign.Ed25519.KeyPair) (IdentityElementError || EncodingError)!KeyPair

Parameters

ed25519_key_pair: crypto.sign.Ed25519.KeyPair

std.crypto.25519.x25519.X25519.KeyPair.generate

function

Source line 43

Generate a new, random key pair.

pub fn generate(io: std.Io) KeyPair

Parameters

io: std.Io

std.crypto.25519.x25519.X25519.KeyPair.generateDeterministic

function

Source line 35

Deterministically derive a key pair from a cryptograpically secure secret seed.

Except in tests, applications should generally call generate() instead of this function.

pub fn generateDeterministic(seed: [seed_length]u8) KeyPair

Parameters

seed: [seed_length]u8

std.crypto.25519.x25519.X25519.public_length

constant

Source line 19

Length (in bytes) of a public key.

std.crypto.25519.x25519.X25519.publicKeyFromEd25519

function

Source line 71

Compute the X25519 equivalent to an Ed25519 public eky.

pub fn publicKeyFromEd25519(ed25519_public_key: crypto.sign.Ed25519.PublicKey) (IdentityElementError || EncodingError)![public_length]u8

Parameters

ed25519_public_key: crypto.sign.Ed25519.PublicKey

std.crypto.25519.x25519.X25519.recoverPublicKey

function

Source line 65

Compute the public key for a given private key.

pub fn recoverPublicKey(secret_key: [secret_length]u8) [public_length]u8

Parameters

secret_key: [secret_length]u8

std.crypto.25519.x25519.X25519.scalarmult

function

Source line 80

Compute the scalar product of a public key and a secret scalar. Note that the output should not be used as a shared secret without hashing it first.

pub fn scalarmult(secret_key: [secret_length]u8, public_key: [public_length]u8) IdentityElementError![shared_length]u8

Parameters

secret_key: [secret_length]u8
public_key: [public_length]u8

Errors

IdentityElement IdentityElementError

std.crypto.25519.x25519.X25519.secret_length

constant

Source line 17

Length (in bytes) of a secret key.

std.crypto.25519.x25519.X25519.seed_length

constant

Source line 23

Seed (for key pair creation) length in bytes.

std.crypto.25519.x25519.X25519.shared_length

constant

Source line 21

Length (in bytes) of the output of the DH function.

Source code

std/crypto/25519/x25519.zig

const std = @import("std");
const crypto = std.crypto;
const mem = std.mem;
const fmt = std.fmt;

const Sha512 = crypto.hash.sha2.Sha512;

const EncodingError = crypto.errors.EncodingError;
const IdentityElementError = crypto.errors.IdentityElementError;
const WeakPublicKeyError = crypto.errors.WeakPublicKeyError;

/// X25519 DH function.
pub const X25519 = struct {
    /// The underlying elliptic curve.
    pub const Curve = @import("curve25519.zig").Curve25519;
    /// Length (in bytes) of a secret key.
    pub const secret_length = 32;
    /// Length (in bytes) of a public key.
    pub const public_length = 32;
    /// Length (in bytes) of the output of the DH function.
    pub const shared_length = 32;
    /// Seed (for key pair creation) length in bytes.
    pub const seed_length = 32;

    /// An X25519 key pair.
    pub const KeyPair = struct {
        /// Public part.
        public_key: [public_length]u8,
        /// Secret part.
        secret_key: [secret_length]u8,

        /// Deterministically derive a key pair from a cryptograpically secure secret seed.
        ///
        /// Except in tests, applications should generally call `generate()` instead of this function.
        pub fn generateDeterministic(seed: [seed_length]u8) KeyPair {
            return .{
                .public_key = X25519.recoverPublicKey(seed),
                .secret_key = seed,
            };
        }

        /// Generate a new, random key pair.
        pub fn generate(io: std.Io) KeyPair {
            var random_seed: [seed_length]u8 = undefined;
            io.random(&random_seed);
            return generateDeterministic(random_seed);
        }

        /// Create a key pair from an Ed25519 key pair
        pub fn fromEd25519(ed25519_key_pair: crypto.sign.Ed25519.KeyPair) (IdentityElementError || EncodingError)!KeyPair {
            const seed = ed25519_key_pair.secret_key.seed();
            var az: [Sha512.digest_length]u8 = undefined;
            Sha512.hash(&seed, &az, .{});
            var sk = az[0..32].*;
            Curve.scalar.clamp(&sk);
            const pk = try publicKeyFromEd25519(ed25519_key_pair.public_key);
            return KeyPair{
                .public_key = pk,
                .secret_key = sk,
            };
        }
    };

    /// Compute the public key for a given private key.
    pub fn recoverPublicKey(secret_key: [secret_length]u8) [public_length]u8 {
        const q = Curve.basePoint.clampedMul(secret_key) catch unreachable;
        return q.toBytes();
    }

    /// Compute the X25519 equivalent to an Ed25519 public eky.
    pub fn publicKeyFromEd25519(ed25519_public_key: crypto.sign.Ed25519.PublicKey) (IdentityElementError || EncodingError)![public_length]u8 {
        const pk_ed = try crypto.ecc.Edwards25519.fromBytes(ed25519_public_key.bytes);
        const pk = try Curve.fromEdwards25519(pk_ed);
        return pk.toBytes();
    }

    /// Compute the scalar product of a public key and a secret scalar.
    /// Note that the output should not be used as a shared secret without
    /// hashing it first.
    pub fn scalarmult(secret_key: [secret_length]u8, public_key: [public_length]u8) IdentityElementError![shared_length]u8 {
        const q = try Curve.fromBytes(public_key).clampedMul(secret_key);
        return q.toBytes();
    }
};

const htest = @import("../test.zig");

test "public key calculation from secret key" {
    var sk: [32]u8 = undefined;
    var pk_expected: [32]u8 = undefined;
    _ = try fmt.hexToBytes(sk[0..], "8052030376d47112be7f73ed7a019293dd12ad910b654455798b4667d73de166");
    _ = try fmt.hexToBytes(pk_expected[0..], "f1814f0e8ff1043d8a44d25babff3cedcae6c22c3edaa48f857ae70de2baae50");
    const pk_calculated = X25519.recoverPublicKey(sk);
    try std.testing.expectEqual(pk_calculated, pk_expected);
}

test "rfc7748 vector1" {
    const secret_key = [32]u8{ 0xa5, 0x46, 0xe3, 0x6b, 0xf0, 0x52, 0x7c, 0x9d, 0x3b, 0x16, 0x15, 0x4b, 0x82, 0x46, 0x5e, 0xdd, 0x62, 0x14, 0x4c, 0x0a, 0xc1, 0xfc, 0x5a, 0x18, 0x50, 0x6a, 0x22, 0x44, 0xba, 0x44, 0x9a, 0xc4 };
    const public_key = [32]u8{ 0xe6, 0xdb, 0x68, 0x67, 0x58, 0x30, 0x30, 0xdb, 0x35, 0x94, 0xc1, 0xa4, 0x24, 0xb1, 0x5f, 0x7c, 0x72, 0x66, 0x24, 0xec, 0x26, 0xb3, 0x35, 0x3b, 0x10, 0xa9, 0x03, 0xa6, 0xd0, 0xab, 0x1c, 0x4c };

    const expected_output = [32]u8{ 0xc3, 0xda, 0x55, 0x37, 0x9d, 0xe9, 0xc6, 0x90, 0x8e, 0x94, 0xea, 0x4d, 0xf2, 0x8d, 0x08, 0x4f, 0x32, 0xec, 0xcf, 0x03, 0x49, 0x1c, 0x71, 0xf7, 0x54, 0xb4, 0x07, 0x55, 0x77, 0xa2, 0x85, 0x52 };

    const output = try X25519.scalarmult(secret_key, public_key);
    try std.testing.expectEqual(output, expected_output);
}

test "rfc7748 vector2" {
    const secret_key = [32]u8{ 0x4b, 0x66, 0xe9, 0xd4, 0xd1, 0xb4, 0x67, 0x3c, 0x5a, 0xd2, 0x26, 0x91, 0x95, 0x7d, 0x6a, 0xf5, 0xc1, 0x1b, 0x64, 0x21, 0xe0, 0xea, 0x01, 0xd4, 0x2c, 0xa4, 0x16, 0x9e, 0x79, 0x18, 0xba, 0x0d };
    const public_key = [32]u8{ 0xe5, 0x21, 0x0f, 0x12, 0x78, 0x68, 0x11, 0xd3, 0xf4, 0xb7, 0x95, 0x9d, 0x05, 0x38, 0xae, 0x2c, 0x31, 0xdb, 0xe7, 0x10, 0x6f, 0xc0, 0x3c, 0x3e, 0xfc, 0x4c, 0xd5, 0x49, 0xc7, 0x15, 0xa4, 0x93 };

    const expected_output = [32]u8{ 0x95, 0xcb, 0xde, 0x94, 0x76, 0xe8, 0x90, 0x7d, 0x7a, 0xad, 0xe4, 0x5c, 0xb4, 0xb8, 0x73, 0xf8, 0x8b, 0x59, 0x5a, 0x68, 0x79, 0x9f, 0xa1, 0x52, 0xe6, 0xf8, 0xf7, 0x64, 0x7a, 0xac, 0x79, 0x57 };

    const output = try X25519.scalarmult(secret_key, public_key);
    try std.testing.expectEqual(output, expected_output);
}

test "rfc7748 one iteration" {
    const initial_value = [32]u8{ 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };
    const expected_output = [32]u8{ 0x42, 0x2c, 0x8e, 0x7a, 0x62, 0x27, 0xd7, 0xbc, 0xa1, 0x35, 0x0b, 0x3e, 0x2b, 0xb7, 0x27, 0x9f, 0x78, 0x97, 0xb8, 0x7b, 0xb6, 0x85, 0x4b, 0x78, 0x3c, 0x60, 0xe8, 0x03, 0x11, 0xae, 0x30, 0x79 };

    var k: [32]u8 = initial_value;
    var u: [32]u8 = initial_value;

    var i: usize = 0;
    while (i < 1) : (i += 1) {
        const output = try X25519.scalarmult(k, u);
        u = k;
        k = output;
    }

    try std.testing.expectEqual(k, expected_output);
}

test "rfc7748 1,000 iterations" {
    // These iteration tests are slow so we always skip them. Results have been verified.
    if (true) {
        return error.SkipZigTest;
    }

    const initial_value = [32]u8{ 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };
    const expected_output = [32]u8{ 0x68, 0x4c, 0xf5, 0x9b, 0xa8, 0x33, 0x09, 0x55, 0x28, 0x00, 0xef, 0x56, 0x6f, 0x2f, 0x4d, 0x3c, 0x1c, 0x38, 0x87, 0xc4, 0x93, 0x60, 0xe3, 0x87, 0x5f, 0x2e, 0xb9, 0x4d, 0x99, 0x53, 0x2c, 0x51 };

    var k: [32]u8 = initial_value.*;
    var u: [32]u8 = initial_value.*;

    var i: usize = 0;
    while (i < 1000) : (i += 1) {
        const output = try X25519.scalarmult(&k, &u);
        u = k;
        k = output;
    }

    try std.testing.expectEqual(k, expected_output);
}

test "rfc7748 1,000,000 iterations" {
    if (true) {
        return error.SkipZigTest;
    }

    const initial_value = [32]u8{ 0x09, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00 };
    const expected_output = [32]u8{ 0x7c, 0x39, 0x11, 0xe0, 0xab, 0x25, 0x86, 0xfd, 0x86, 0x44, 0x97, 0x29, 0x7e, 0x57, 0x5e, 0x6f, 0x3b, 0xc6, 0x01, 0xc0, 0x88, 0x3c, 0x30, 0xdf, 0x5f, 0x4d, 0xd2, 0xd2, 0x4f, 0x66, 0x54, 0x24 };

    var k: [32]u8 = initial_value.*;
    var u: [32]u8 = initial_value.*;

    var i: usize = 0;
    while (i < 1000000) : (i += 1) {
        const output = try X25519.scalarmult(&k, &u);
        u = k;
        k = output;
    }

    try std.testing.expectEqual(k[0..], expected_output);
}

test "edwards25519 -> curve25519 map" {
    const ed_kp = try crypto.sign.Ed25519.KeyPair.generateDeterministic(@splat(0x42));
    const mont_kp = try X25519.KeyPair.fromEd25519(ed_kp);
    try htest.assertEqual("90e7595fc89e52fdfddce9c6a43d74dbf6047025ee0462d2d172e8b6a2841d6e", &mont_kp.secret_key);
    try htest.assertEqual("cc4f2cdb695dd766f34118eb67b98652fed1d8bc49c330b119bbfa8a64989378", &mont_kp.public_key);
}