feat: CRP-2797 Add functions to access the production master key (#171)

This allows performing key derivation completely offline, without having
to interact with the IC.

Author: randombit

Cargo.lock

@@ -1,5 +1,11 @@
 # Change Log
 
+## [0.3.1] - Not Yet Released
+
+### Added
+
+- Added MasterPublicKey::production_key which allows accessing the production public keys
+
 ## [0.3.0] - 2025-06-30
 
 ### Added
@@ -27,4 +33,4 @@
 
 ## [0.1.0] - 2025-05-27
 
-Initial release
+Initial release

backend/rs/ic_vetkeys/CHANGELOG.md

@@ -35,7 +35,7 @@ ic_bls12_381 = { version = "0.10.1", default-features = false, features = [
 ] }
 hkdf = { version = "0.12" }
 futures = "0.3.31"
-hex = { workspace = true }
+hex-literal = { version = "1" }
 ic-cdk = { workspace = true }
 ic-cdk-macros = { workspace = true }
 ic-stable-structures = { workspace = true }

backend/rs/ic_vetkeys/Cargo.toml

@@ -6,6 +6,7 @@
 #![warn(rust_2018_idioms)]
 #![forbid(missing_docs)]
 
+use hex_literal::hex;
 use ic_bls12_381::{
     hash_to_curve::{ExpandMsgXmd, HashToCurve},
     G1Affine, G1Projective, G2Affine, G2Prepared, Gt, Scalar,
@@ -17,8 +18,15 @@ use std::array::TryFromSliceError;
 use std::ops::Neg;
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
+const MASTER_PUBLIC_KEY_BYTES_KEY_1 : [u8; 96] = hex!("a9caf9ae8af0c7c7272f8a122133e2e0c7c0899b75e502bda9e109ca8193ded3ef042ed96db1125e1bdaad77d8cc60d917e122fe2501c45b96274f43705edf0cfd455bc66c3c060faa2fcd15486e76351edf91fecb993797273bbc8beaa47404");
+
+const MASTER_PUBLIC_KEY_BYTES_TEST_KEY_1 : [u8; 96] = hex!("ad86e8ff845912f022a0838a502d763fdea547c9948f8cb20ea7738dd52c1c38dcb4c6ca9ac29f9ac690fc5ad7681cb41922b8dffbd65d94bff141f5fb5b6624eccc03bf850f222052df888cf9b1e47203556d7522271cbb879b2ef4b8c2bfb1");
+
 lazy_static::lazy_static! {
     static ref G2PREPARED_NEG_G : G2Prepared = G2Affine::generator().neg().into();
+
+    static ref G2_KEY_1: G2Affine = G2Affine::from_compressed(&MASTER_PUBLIC_KEY_BYTES_KEY_1).expect("Hardcoded master public key not a valid point");
+    static ref G2_TEST_KEY_1: G2Affine = G2Affine::from_compressed(&MASTER_PUBLIC_KEY_BYTES_TEST_KEY_1).expect("Hardcoded master public key not a valid point");
 }
 
 const G1AFFINE_BYTES: usize = 48; // Size of compressed form
@@ -146,6 +154,15 @@ pub enum PublicKeyDeserializationError {
     InvalidPublicKey,
 }
 
+/// Enumeration identifying the production master public key
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum MasterPublicKeyId {
+    /// The production key created in June 2025
+    Key1,
+    /// The test key created in May 2025
+    TestKey1,
+}
+
 #[derive(Clone, Debug, Eq, PartialEq)]
 /// A master VetKD public key
 pub struct MasterPublicKey {
@@ -155,9 +172,6 @@ pub struct MasterPublicKey {
 impl MasterPublicKey {
     const BYTES: usize = G2AFFINE_BYTES;
 
-    // TODO(CRP-2797) add
-    // pub fn production_key(key_id: SomeEnum) -> Self
-
     /// Deserializes a (derived) public key.
     ///
     /// Only compressed points are supported.
@@ -200,6 +214,18 @@ impl MasterPublicKey {
     pub fn serialize(&self) -> Vec<u8> {
         self.point.to_compressed().to_vec()
     }
+
+    /// Return the hardcoded master public key used on IC
+    ///
+    /// This allows performing public key derivation offline
+    pub fn production_key(key_id: MasterPublicKeyId) -> Self {
+        match key_id {
+            MasterPublicKeyId::Key1 => Self { point: *G2_KEY_1 },
+            MasterPublicKeyId::TestKey1 => Self {
+                point: *G2_TEST_KEY_1,
+            },
+        }
+    }
 }
 
 #[derive(Clone, Debug, Eq, PartialEq)]

backend/rs/ic_vetkeys/src/utils/mod.rs

@@ -2,6 +2,7 @@ use ic_bls12_381::*;
 use ic_vetkeys::*;
 use ic_vetkeys_test_utils::*;
 use rand::Rng;
+use hex_literal::hex;
 
 #[test]
 fn test_hkdf_test_vector() {
@@ -76,6 +77,52 @@ fn test_bls_signature_verification_using_identity() {
     assert!(!verify_bls_signature(&dpk, msg, &signature));
 }
 
+#[test]
+fn test_derivation_using_test_key_1() {
+    // This test data was generated on mainnet using test_key_1
+
+    let test_key1 = MasterPublicKey::production_key(MasterPublicKeyId::TestKey1);
+
+    let canister_id = hex!("0000000000c0a0d00101");
+
+    let canister_key = test_key1.derive_canister_key(&canister_id);
+
+    assert_eq!(
+        hex::encode(canister_key.serialize()),
+        "8b961f06d392367e84136088971c4808b434e5d6b928b60fa6177f811db9930e4f2a911ef517db40f7e7897588ae0e2316500dbef3abf08ad7f63940af0cf816c2c1c234943c9bb6f4d53da121dceed093d118d0bd5552740da315eac3b59b0f",
+    );
+
+    let derived_key = canister_key.derive_sub_key(b"context-string");
+
+    assert_eq!(
+        hex::encode(derived_key.serialize()),
+        "958a2700438db39cf848f99c80d4d1c0f42b5e6783c35abffe5acda4fdb09548a025fdf85aad8980fcf6e20c1082596310c2612a3f3034c56445ddfc32a0c3cd34a7d0fea8df06a2996c54e21e3f8361a6e633d706ff58e979858fe436c7edf3",
+    );
+}
+
+#[test]
+fn test_derivation_using_production_key() {
+    // This test data was generated on mainnet using key_1
+
+    let key1 = MasterPublicKey::production_key(MasterPublicKeyId::Key1);
+
+    let canister_id = hex!("0000000000c0a0d00101");
+
+    let canister_key = key1.derive_canister_key(&canister_id);
+
+    assert_eq!(
+        hex::encode(canister_key.serialize()),
+        "a4df5fb733dc53ba0b3f8dab3f7538b2f345052072f69a5749d630d9c2b2b1c4b00af09fa1d993e1ce533996961575ad027e058e2a279ab05271c115ef27d750b6b233f12bc9f1973b203e338d43b6a7617be58d5c7195dfb809d756413bc006",
+    );
+
+    let derived_key = canister_key.derive_sub_key(b"context-string");
+
+    assert_eq!(
+        hex::encode(derived_key.serialize()),
+        "aa45fccb82432315e39fedb1b1f150d2e895fb1f7399cc593b826ac151b519f0966b92aef49a89efe60570ef325f0f7e1974ac3519d2e127a52c013e246aedbff2158bdd0bb9f26c763c88c0b8ec796f401d057eab276d0a34384a8a97b1937f",
+    );
+}
+
 #[test]
 fn test_second_level_public_key_derivation() {
     let canister_key = DerivedPublicKey::deserialize(&hex::decode("8bf165ea580742abf5fd5123eb848aa116dcf75c3ddb3cd3540c852cf99f0c5394e72dfc2f25dbcb5f9220f251cd04040a508a0bcb8b2543908d6626b46f09d614c924c5deb63a9949338ae4f4ac436bd77f8d0a392fd29de0f392a009fa61f3").unwrap()).unwrap();

backend/rs/ic_vetkeys/tests/utils.rs

@@ -1,5 +1,11 @@
 # Change Log
 
+## [0.3.1] - Not Yet Released
+
+### Added
+
+- Added MasterPublicKey.productionKey which allows accessing the production public keys
+
 ## [0.3.0] - 2025-06-30
 
 ### Changed

frontend/ic_vetkeys/CHANGELOG.md

@@ -4,6 +4,7 @@ import {
     IbeIdentity,
     IbeCiphertext,
     MasterPublicKey,
+    MasterPublicKeyId,
     IbeSeed,
     TransportSecretKey,
     VetKey,
@@ -74,20 +75,49 @@ test("parsing DerivedPublicKey", () => {
     assertEqual(valid, key.publicKeyBytes());
 });
 
-test("MasterPublicKey derivation", () => {
-    const masterKey = MasterPublicKey.deserialize(
-        hexToBytes(
-            "9183b871aa141d15ba2efc5bc58a49cb6a167741364804617f48dfe11e0285696b7018f172dad1a87ed81abf27ea4c320995041e2ee4a47b2226a2439d92a38557a7e2acc72fd157283b20f1f37ba872be235214c6a9cbba1eb2ef39deec72a5",
-        ),
+test("MasterPublicKey derivation using test key", () => {
+    const masterKey = MasterPublicKey.productionKey(
+        MasterPublicKeyId.TEST_KEY_1,
+    );
+
+    const canisterId = hexToBytes("0000000000c0a0d00101");
+
+    const canisterKey = masterKey.deriveCanisterKey(canisterId);
+
+    assertEqual(
+        bytesToHex(canisterKey.publicKeyBytes()),
+        "8b961f06d392367e84136088971c4808b434e5d6b928b60fa6177f811db9930e4f2a911ef517db40f7e7897588ae0e2316500dbef3abf08ad7f63940af0cf816c2c1c234943c9bb6f4d53da121dceed093d118d0bd5552740da315eac3b59b0f",
+    );
+
+    const derivedKey = canisterKey.deriveSubKey(
+        new TextEncoder().encode("context-string"),
+    );
+
+    assertEqual(
+        bytesToHex(derivedKey.publicKeyBytes()),
+        "958a2700438db39cf848f99c80d4d1c0f42b5e6783c35abffe5acda4fdb09548a025fdf85aad8980fcf6e20c1082596310c2612a3f3034c56445ddfc32a0c3cd34a7d0fea8df06a2996c54e21e3f8361a6e633d706ff58e979858fe436c7edf3",
     );
+});
+
+test("MasterPublicKey derivation using prod key", () => {
+    const masterKey = MasterPublicKey.productionKey();
 
-    const canisterId = new TextEncoder().encode("test-canister-id");
+    const canisterId = hexToBytes("0000000000c0a0d00101");
 
-    const derivedKey = masterKey.deriveKey(canisterId);
+    const canisterKey = masterKey.deriveCanisterKey(canisterId);
+
+    assertEqual(
+        bytesToHex(canisterKey.publicKeyBytes()),
+        "a4df5fb733dc53ba0b3f8dab3f7538b2f345052072f69a5749d630d9c2b2b1c4b00af09fa1d993e1ce533996961575ad027e058e2a279ab05271c115ef27d750b6b233f12bc9f1973b203e338d43b6a7617be58d5c7195dfb809d756413bc006",
+    );
+
+    const derivedKey = canisterKey.deriveSubKey(
+        new TextEncoder().encode("context-string"),
+    );
 
     assertEqual(
         bytesToHex(derivedKey.publicKeyBytes()),
-        "af78a908589d332fc8b9d042807c483e73872e2aea7620bdb985b9289d5a99ebfd5ac0ec4844a4c542f6d0f12a716d941674953cef4f38dde601ce9792db8832557eaa051733c5541fa5017465d69b62cc4d93f2079fb8c050b4bd735ef75859",
+        "aa45fccb82432315e39fedb1b1f150d2e895fb1f7399cc593b826ac151b519f0966b92aef49a89efe60570ef325f0f7e1974ac3519d2e127a52c013e246aedbff2158bdd0bb9f26c763c88c0b8ec796f401d057eab276d0a34384a8a97b1937f",
     );
 });
 
@@ -100,7 +130,7 @@ test("DerivedPublicKey subderivation", () => {
 
     const context = new TextEncoder().encode("test-context");
 
-    const derivedKey = canisterKey.deriveKey(context);
+    const derivedKey = canisterKey.deriveSubKey(context);
 
     assertEqual(
         bytesToHex(derivedKey.publicKeyBytes()),

frontend/ic_vetkeys/src/utils/utils.test.ts

@@ -110,6 +110,27 @@ function prefixWithLen(input: Uint8Array): Uint8Array {
     return result;
 }
 
+/**
+ * Enumeration identifying possible master public keys
+ */
+export enum MasterPublicKeyId {
+    /** The production key generated in June 2025 */
+    KEY_1 = "key_1",
+    /** The test key generated in May 2025 */
+    TEST_KEY_1 = "test_key_1",
+}
+
+/**
+ * @internal helper to perform hex decoding
+ */
+function hexToBytes(hex: string): Uint8Array {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < hex.length; i += 2) {
+        bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16);
+    }
+    return bytes;
+}
+
 /**
  * VetKD master key
  *
@@ -141,7 +162,7 @@ export class MasterPublicKey {
      * plus the canister identity. This avoids having to interact with the IC for performing this
      * computation.
      */
-    deriveKey(canisterId: Uint8Array): DerivedPublicKey {
+    deriveCanisterKey(canisterId: Uint8Array): DerivedPublicKey {
         const dst = "ic-vetkd-bls12-381-g2-canister-id";
         const pkbytes = this.publicKeyBytes();
         const randomOracleInput = new Uint8Array([
@@ -161,9 +182,31 @@ export class MasterPublicKey {
     }
 
     /**
-     * TODO CRP-2797 add getter for the production subnet key once this has been
-     * generated.
+     * Return the hardcoded master public key used on IC
+     *
+     * This allows performing public key derivation offline
      */
+    static productionKey(
+        keyId: MasterPublicKeyId = MasterPublicKeyId.KEY_1,
+    ): MasterPublicKey {
+        if (keyId == MasterPublicKeyId.KEY_1) {
+            return MasterPublicKey.deserialize(
+                hexToBytes(
+                    "a9caf9ae8af0c7c7272f8a122133e2e0c7c0899b75e502bda9e109ca8193ded3ef042ed96db1125e1bdaad77d8cc60d917e122fe2501c45b96274f43705edf0cfd455bc66c3c060faa2fcd15486e76351edf91fecb993797273bbc8beaa47404",
+                ),
+            );
+        } else if (keyId == MasterPublicKeyId.TEST_KEY_1) {
+            return MasterPublicKey.deserialize(
+                hexToBytes(
+                    "ad86e8ff845912f022a0838a502d763fdea547c9948f8cb20ea7738dd52c1c38dcb4c6ca9ac29f9ac690fc5ad7681cb41922b8dffbd65d94bff141f5fb5b6624eccc03bf850f222052df888cf9b1e47203556d7522271cbb879b2ef4b8c2bfb1",
+                ),
+            );
+        } else {
+            throw new Error(
+                "Unknown MasterPublicKeyId value for productionKey",
+            );
+        }
+    }
 
     /**
      * @internal constructor
@@ -210,7 +253,7 @@ export class DerivedPublicKey {
      * If `context` is empty, then this simply returns the underlying key. This matches the behavior
      * of `vetkd_public_key`
      */
-    deriveKey(context: Uint8Array): DerivedPublicKey {
+    deriveSubKey(context: Uint8Array): DerivedPublicKey {
         if (context.length === 0) {
             return this;
         } else {