# P256

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.

:::info
The `P256` module is a friendly wrapper over [`@noble/curves/p256`](https://github.com/paulmillr/noble-curves), an **audited** implementation of [P256](https://www.secg.org/sec2-v2.pdf)
:::

## Examples

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

* [Computing a Random Private Key](#computing-a-random-private-key)

* [Getting a Public Key](#getting-a-public-key)

* [Signing a Payload](#signing-a-payload)

* [Verifying a Signature](#verifying-a-signature)

### Computing a Random Private Key

A random private key can be computed using [`P256.randomPrivateKey`](/api/P256/randomPrivateKey):

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

const privateKey = P256.randomPrivateKey()
// @log: '0x...'
```

### Getting a Public Key

A public key can be derived from a private key using [`P256.getPublicKey`](/api/P256/getPublicKey):

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

const privateKey = P256.randomPrivateKey()

const publicKey = P256.getPublicKey({ privateKey }) // [!code focus]
// @log: { x: 3251...5152n, y: 1251...5152n }
```

### Signing a Payload

A payload can be signed using [`P256.sign`](/api/P256/sign):

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

const privateKey = P256.randomPrivateKey()

const signature = P256.sign({
  payload: '0xdeadbeef',
  privateKey
}) // [!code focus]
// @log: { r: 1251...5152n, s: 1251...5152n, yParity: 1 }
```

### Verifying a Signature

A signature can be verified using [`P256.verify`](/api/P256/verify):

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

const privateKey = P256.randomPrivateKey()
const publicKey = P256.getPublicKey({ privateKey })
const signature = P256.sign({
  payload: '0xdeadbeef',
  privateKey
})

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

## Functions

| Name                | Description                         |
| ------------------- | ----------------------------------- |
| [`P256.createKeyPair`](/api/P256/createKeyPair) | Creates a new P256 ECDSA key pair consisting of a private key and its corresponding public key. |
| [`P256.getPublicKey`](/api/P256/getPublicKey) | Computes the P256 ECDSA public key from a provided private key. |
| [`P256.getSharedSecret`](/api/P256/getSharedSecret) | Computes a shared secret using ECDH (Elliptic Curve Diffie-Hellman) between a private key and a public key. |
| [`P256.randomPrivateKey`](/api/P256/randomPrivateKey) | Generates a random P256 ECDSA private key. |
| [`P256.recoverPublicKey`](/api/P256/recoverPublicKey) | Recovers the signing public key from the signed payload and signature. |
| [`P256.sign`](/api/P256/sign) | Signs the payload with the provided private key and returns a P256 signature. |
| [`P256.verify`](/api/P256/verify) | Verifies a payload was signed by the provided public key. |