Overview

The @icp-sdk/core/identity/secp256k1 module provides an implementation of the SignIdentity interface for the secp256k1 elliptic curve. It allows you to create and manage key pairs for signing and verification of messages.

Usage

Here’s an example of how to use the Secp256k1KeyIdentity class to generate a new key pair and sign and verify a message:

import { Secp256k1KeyIdentity } from '@icp-sdk/core/identity/secp256k1';

// Generate a new key pair
const identity = Secp256k1KeyIdentity.generate();

// Sign a message
const message = 'Hello, world!';
const signature = identity.sign(message);

// Verify the signature
const isValid = identity.verify(message, signature);

console.log(`Signature is ${isValid ? 'valid' : 'invalid'}`);

You can also use a seed to generate deterministic key pairs:

import { Secp256k1KeyIdentity } from '@icp-sdk/core/identity/secp256k1';

const seed = Buffer.from('my-secret-seed', 'utf8');
const identity = Secp256k1KeyIdentity.generate(seed);

The Secp256k1KeyIdentity class also provides methods for converting the key pair to and from JSON-serializable objects:

import { Secp256k1KeyIdentity } from '@icp-sdk/core/identity/secp256k1';

// Generate a new key pair
const identity = Secp256k1KeyIdentity.generate();

// Convert the key pair to a JSON-serializable object
const json = identity.toJson();

// Convert the JSON-serializable object back to a key pair
const restoredIdentity = Secp256k1KeyIdentity.fromJson(json);

Classes

Secp256k1KeyIdentity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:108

An Identity that can sign blobs.

Extends

SignIdentity

Constructors

Constructor

protected new Secp256k1KeyIdentity(publicKey, _privateKey): Secp256k1KeyIdentity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:229

Parameters

publicKey

Secp256k1PublicKey

_privateKey

Uint8Array

Returns

Secp256k1KeyIdentity

Overrides

SignIdentity.constructor

Properties

_principal

protected _principal: Principal | undefined

Defined in: packages/core/src/agent/auth.ts:58

Inherited from

SignIdentity._principal

_privateKey

protected _privateKey: Uint8Array

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:231

_publicKey

_publicKey: Secp256k1PublicKey

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:227

Methods

getKeyPair()

getKeyPair(): KeyPair

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:249

Return a copy of the key pair.

Returns

KeyPair

KeyPair

getPrincipal()

getPrincipal(): Principal

Defined in: packages/core/src/agent/auth.ts:74

Get the principal represented by this identity. Normally should be a Principal.selfAuthenticating().

Returns

Principal

Inherited from

SignIdentity.getPrincipal

getPublicKey()

getPublicKey(): Required<PublicKey>

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:260

Return the public key.

Returns

Required<PublicKey>

Required

Overrides

SignIdentity.getPublicKey

sign()

sign(data): Promise<Signature>

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:269

Signs a blob of data, with this identity’s private key.

Parameters

data

Uint8Array

bytes to hash and sign with this identity’s secretKey, producing a signature

Returns

Promise<Signature>

signature

Overrides

SignIdentity.sign

toJSON()

toJSON(): JsonableSecp256k1Identity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:241

Serialize this key to JSON-serializable object.

Returns

JsonableSecp256k1Identity

JsonableSecp256k1Identity

transformRequest()

transformRequest(request): Promise<unknown>

Defined in: packages/core/src/agent/auth.ts:87

Transform a request into a signed version of the request. This is done last after the transforms on the body of a request. The returned object can be anything, but must be serializable to CBOR.

Parameters

request

HttpAgentRequest

internet computer request to transform

Returns

Promise<unknown>

Inherited from

SignIdentity.transformRequest

fromJSON()

static fromJSON(json): Secp256k1KeyIdentity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:151

Parameters

json

string

Returns

Secp256k1KeyIdentity

fromKeyPair()

static fromKeyPair(publicKey, privateKey): Secp256k1KeyIdentity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:168

generates an identity from a public and private key. Please ensure that you are generating these keys securely and protect the user’s private key

Parameters

publicKey

Uint8Array

Uint8Array

privateKey

Uint8Array

Uint8Array

Returns

Secp256k1KeyIdentity

Secp256k1KeyIdentity

fromParsedJson()

static fromParsedJson(obj): Secp256k1KeyIdentity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:143

Parameters

obj

JsonableSecp256k1Identity

Returns

Secp256k1KeyIdentity

fromPem()

static fromPem(pemKey): Secp256k1KeyIdentity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:222

Utility method to create a Secp256k1KeyIdentity from a PEM-encoded key.

Parameters

pemKey

string

PEM-encoded key as a string

Returns

Secp256k1KeyIdentity

Secp256k1KeyIdentity

fromSecretKey()

static fromSecretKey(secretKey): Secp256k1KeyIdentity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:177

generates an identity from an existing secret key, and is the correct method to generate an identity from a seed phrase. Please ensure you protect the user’s private key.

Parameters

secretKey

Uint8Array

Uint8Array

Returns

Secp256k1KeyIdentity

Secp256k1KeyIdentity

fromSeedPhrase()

static fromSeedPhrase(seedPhrase, password?): Secp256k1KeyIdentity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:189

Generates an identity from a seed phrase. Use carefully - seed phrases should only be used in secure contexts, and you should avoid having users copying and pasting seed phrases as much as possible.

Parameters

seedPhrase

string | string[]

either an array of words or a string of words separated by spaces.

password?

string

optional password to be used by bip39

Returns

Secp256k1KeyIdentity

Secp256k1KeyIdentity

generate()

static generate(seed?): Secp256k1KeyIdentity

Defined in: packages/core/src/identity/secp256k1/secp256k1.ts:117

Generates an identity. If a seed is provided, the keys are generated from the seed according to BIP 0032. Otherwise, the key pair is randomly generated. This method throws an error in case the seed is not 32 bytes long or invalid for use as a private key.