# WebCryptoP256

Utility functions for [NIST P256](https://csrc.nist.gov/csrc/media/events/workshop-on-elliptic-curve-cryptography-standards/documents/papers/session6-adalier-mehmet.pdf) ECDSA cryptography using the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API)

## Examples

Below are some examples demonstrating common usages of the `WebCryptoP256` module:

* [Creating Key Pairs](#creating-key-pairs)

* [Signing Payloads](#signing-payloads)

* [Verifying Signatures](#verifying-signatures)

### Creating Key Pairs

Key pairs can be created using [`WebCryptoP256.createKeyPair`](/api/WebCryptoP256/createKeyPair):

```ts twoslash
import { WebCryptoP256 } from 'ox'

const { publicKey, privateKey } =
  await WebCryptoP256.createKeyPair()
// @log: {
// @log:   privateKey: CryptoKey {},
// @log:   publicKey: {
// @log:     x: '0x8318535b54105d4a7aae60c08fc45f9687181b4fdfc625bd1a753fa7397fed75',
// @log:     y: '0x3547f11ca8696646f2f3acb08e31016afac23e630c5d11f59f61fef57b0d2aa5',
// @log:     prefix: 4,
// @log:   },
// @log: }
```

### Signing Payloads

Payloads can be signed using [`WebCryptoP256.sign`](/api/WebCryptoP256/sign):

```ts twoslash
import { WebCryptoP256 } from 'ox'

const { privateKey } = await WebCryptoP256.createKeyPair()

const signature = await WebCryptoP256.sign({
  // [!code focus]
  payload: '0xdeadbeef', // [!code focus]
  privateKey // [!code focus]
}) // [!code focus]
// @log: {
// @log:   r: 151231...4423n,
// @log:   s: 516123...5512n,
// @log: }
```

### Verifying Signatures

Signatures can be verified using [`WebCryptoP256.verify`](/api/WebCryptoP256/verify):

```ts twoslash
import { WebCryptoP256 } from 'ox'

const { privateKey, publicKey } =
  await WebCryptoP256.createKeyPair()
const signature = await WebCryptoP256.sign({
  payload: '0xdeadbeef',
  privateKey
})

const verified = await WebCryptoP256.verify({
  // [!code focus]
  payload: '0xdeadbeef', // [!code focus]
  publicKey, // [!code focus]
  signature // [!code focus]
}) // [!code focus]
// @log: true
```

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`WebCryptoP256.createKeyPair`](/api/WebCryptoP256/createKeyPair) | Generates an ECDSA P256 key pair that includes: |
| [`WebCryptoP256.createKeyPairECDH`](/api/WebCryptoP256/createKeyPairECDH) | Generates an ECDH P256 key pair for key agreement that includes: |
| [`WebCryptoP256.getSharedSecret`](/api/WebCryptoP256/getSharedSecret) | Computes a shared secret using ECDH (Elliptic Curve Diffie-Hellman) between a private key and a public key using Web Crypto APIs. |
| [`WebCryptoP256.sign`](/api/WebCryptoP256/sign) | Signs a payload with the provided `CryptoKey` private key and returns a P256 signature. |
| [`WebCryptoP256.verify`](/api/WebCryptoP256/verify) | Verifies a payload was signed by the provided public key. |

## Errors

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`WebCryptoP256.InvalidPrivateKeyAlgorithmError`](/api/WebCryptoP256/errors#webcryptop256invalidprivatekeyalgorithmerror) | Thrown when an ECDSA private key is supplied to [`WebCryptoP256.getSharedSecret`](/api/WebCryptoP256/getSharedSecret). Only ECDH private keys are valid for shared secret derivation. |