Web5 SDK Documentation/web5.sdk.crypto/Secp256k1

Secp256k1

A cryptographic object responsible for key generation, signature creation, and signature verification utilizing the SECP256K1 elliptic curve, widely used for Bitcoin and Ethereum transactions.

The object uses the Nimbus JOSE+JWT library and implements the KeyGenerator and Signer interfaces, providing specific implementation details for SECP256K1.

Key Points:

Utilizes the ES256K algorithm for signing JWTs.
Utilizes BouncyCastle as the underlying security provider.
Public and private keys can be encoded with PUB_MULTICODEC and PRIV_MULTICODEC respectively.

Example Usage:

val privateKey = Secp256k1.generatePrivateKey()
val publicKey = Secp256k1.getPublicKey(privateKey)

Key Generation and Management:

generatePrivateKey: Generates a private key for the SECP256K1 curve.
getPublicKey: Derives the corresponding public key from a private key.

Signing and Verification:

sign: Generates a digital signature.
verify: Verifies a digital signature.

Properties

algorithm

open override val algorithm: Jwa

Indicates the algorithm intended to be used with the key.

COMP_KEY_EVEN_Y_ID

const val COMP_KEY_EVEN_Y_ID: Byte = 2

Compressed key leading byte that indicates whether the Y coordinate is even.

COMP_KEY_ODD_Y_ID

const val COMP_KEY_ODD_Y_ID: Byte = 3

Compressed key leading byte that indicates whether the Y coordinate is odd.

COMPRESSED_KEY_SIZE

const val COMPRESSED_KEY_SIZE: Int = 33

The byte size of a compressed public key.

curve

open override val curve: JwaCurve

The curve used for the key generation.

keyType

open override val keyType: String

KeyType in String format (OKP, EC, etc.).

PRIV_MULTICODEC

const val PRIV_MULTICODEC: Int = 4865

reference.

PUB_MULTICODEC

const val PUB_MULTICODEC: Int = 231

reference.

publicKeyXRange

val publicKeyXRange: IntRange

Range that defines the position of the X coordinate in an uncompressed public key byte array.

publicKeyYRange

val publicKeyYRange: IntRange

Range that defines the position of the Y coordinate in an uncompressed public key byte array.

SIG_SIZE

const val SIG_SIZE: Int = 64

UNCOMPRESSED_KEY_ID

const val UNCOMPRESSED_KEY_ID: Byte = 4

uncompressed key leading byte.

UNCOMPRESSED_KEY_SIZE

const val UNCOMPRESSED_KEY_SIZE: Int = 65

Size of an uncompressed public key in bytes.

Functions

bytesToPrivateKey

open override fun bytesToPrivateKey(privateKeyBytes: ByteArray): Jwk

Converts a private key as bytes into a Jwk.

bytesToPublicKey

open override fun bytesToPublicKey(publicKeyBytes: ByteArray): Jwk

Converts a public key as bytes into a Jwk. Applicable for asymmetric Key Generators only. Implementers of symmetric key generators should throw an UnsupportedOperation Exception

compressPublicKey

fun compressPublicKey(publicKeyBytes: ByteArray): ByteArray

Compresses a public key represented by its X and Y coordinates concatenated in a single byte array.

computePublicKey

open override fun computePublicKey(privateKey: Jwk): Jwk

Derives a public key from the private key provided. Applicable for asymmetric Key Generators only. Implementers of symmetric key generators should throw an UnsupportedOperation Exception

generatePrivateKey

open override fun generatePrivateKey(options: KeyGenOptions?): Jwk

Generates a private key using the SECP256K1 curve and ES256K algorithm.

inflatePublicKey

fun inflatePublicKey(publicKeyBytes: ByteArray): ByteArray

Inflates a compressed public key.

privateKeyToBytes

open override fun privateKeyToBytes(privateKey: Jwk): ByteArray

Converts a private key to bytes.

publicKeyToBytes

open override fun publicKeyToBytes(publicKey: Jwk): ByteArray

Converts a public key to bytes. Applicable for asymmetric KeyGenerator implementations only. Implementers of symmetric key generators should throw an UnsupportedOperation Exception

sign

open override fun sign(privateKey: Jwk, payload: ByteArray, options: SignOptions?): ByteArray

Deterministically signs the provided payload using the ECDSA (Elliptic Curve Digital Signature Algorithm) with the curve secp256k1.

validateKey

fun validateKey(key: Jwk)

Validates the provided Jwk (JSON Web Key) to ensure it conforms to the expected key type and format.

verify

open override fun verify(publicKey: Jwk, signedPayload: ByteArray, signature: ByteArray, options: VerifyOptions?)

Verifies a signature against a given payload using the ECDSA (Elliptic Curve Digital Signature Algorithm) with the curve secp256k1. This function supports deterministic k-value generation through HMAC and SHA-256, ensuring consistent verification outcomes for identical payloads and signatures.