# GenerateKeyPair()

Generates a cryptographic key pair (public/private) for the specified algorithm.

**Requires Extension:** [Crypto Extension](https://download.lucee.org/#17AB52DE-B300-A94B-E058FC978BE4542D)

```
GenerateKeyPair( algorithm=string, options=struct );
```

**Returns:** struct

# Arguments

| Argument | Type | Required | Description | Default |
|----------|------|----------|-------------|---------|
| algorithm | string | Yes | Algorithm string. For RSA, append key size: RSA (default 2048), RSA-4096. For EC, use curve name: EC (default P-256), P-384, P-521. For EdDSA: Ed25519, Ed448. For post-quantum: Kyber768, Dilithium3. |  |
| options | struct | No | Optional struct with: format (PEM\|DER\|Base64, default PEM) |  |

# Usage Notes

**Which key type?**

- **P-256 (EC)** — Best default for most applications. Small keys, fast operations, widely supported. Use for JWT (ES256), TLS, and general-purpose signing.
- **RSA-2048** — Use when you need compatibility with older systems, Adobe ColdFusion, or SAML. Larger keys and slower than EC.
- **Ed25519** — Modern alternative to EC. Fastest signatures, smallest keys, but less ecosystem support than P-256. Only supports PKCS8 format (no traditional/OpenSSL format).
- **Kyber768** — Post-quantum key encapsulation. Use with [KyberEncapsulate()](kyberencapsulate.md) for quantum-resistant key exchange.
- **Dilithium3** — Post-quantum signatures. Use with [GenerateSignature()](generatesignature.md) for quantum-resistant signing.

**Output formats:**

- **PEM / PKCS8** (default) — Standard PEM with `-----BEGIN PRIVATE KEY-----` headers. Most compatible.
- **traditional / OPENSSL** — OpenSSL legacy format with algorithm-specific headers (e.g. `-----BEGIN RSA PRIVATE KEY-----`). Not available for Ed25519.
- **Base64** — Raw Base64-encoded key bytes without PEM headers.
- **DER** — Raw binary key bytes.

# Examples

```cfml
// Generate an RSA key pair - default is 2048-bit, PKCS#8 PEM format
keyPair = GenerateKeyPair( "RSA" );
// keyPair.private starts with "-----BEGIN PRIVATE KEY-----"
// keyPair.public starts with "-----BEGIN PUBLIC KEY-----"

// Specify key size explicitly
keyPair = GenerateKeyPair( "RSA-4096" );

// Elliptic curve key pairs - smaller and faster than RSA
keyPair = GenerateKeyPair( "P-256" );  // NIST P-256 (secp256r1)
keyPair = GenerateKeyPair( "P-384" );  // NIST P-384
keyPair = GenerateKeyPair( "P-521" );  // NIST P-521

// Ed25519 - modern, fast, compact signatures
keyPair = GenerateKeyPair( "Ed25519" );

// Output format options
keyPair = GenerateKeyPair( "RSA", { format: "PEM" } );         // PKCS#8 (default)
keyPair = GenerateKeyPair( "RSA", { format: "traditional" } );  // OpenSSL traditional format
// private starts with "-----BEGIN RSA PRIVATE KEY-----"

keyPair = GenerateKeyPair( "P-256", { format: "traditional" } ); // EC traditional
// private starts with "-----BEGIN EC PRIVATE KEY-----"

keyPair = GenerateKeyPair( "RSA", { format: "Base64" } );  // raw Base64 (no PEM headers)
keyPair = GenerateKeyPair( "RSA", { format: "DER" } );     // binary DER format

// Format aliases: PKCS8 = PEM, OPENSSL = traditional
// Note: Ed25519 only supports PKCS8/PEM format (no traditional)
```







# Categories

[Cryptography](../../categories/crypto.md)

# See Also

[GenerateCSR()](generatecsr.md), [GenerateSelfSignedCertificate()](generateselfsignedcertificate.md), [GenerateSignature()](generatesignature.md), [JwtSign()](jwtsign.md), [KeyToJwk()](keytojwk.md), [KeyToPem()](keytopem.md), [KyberDecapsulate()](kyberdecapsulate.md), [KyberEncapsulate()](kyberencapsulate.md), [ValidateKeyPair()](validatekeypair.md), [VerifySignature()](verifysignature.md)