# KyberEncapsulate()

Creates a shared secret using the recipient's Kyber public key.

Kyber is a post-quantum key exchange algorithm — resistant to attacks by future quantum computers. The shared secret can then be used for symmetric encryption (e.g. AES).

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

```
KyberEncapsulate( publicKey=any );
```

**Returns:** struct

# Arguments

| Argument | Type | Required | Description | Default |
|----------|------|----------|-------------|---------|
| publicKey | any | Yes | Kyber public key (PEM string or Java object) |  |

# Usage Notes

Kyber is a key encapsulation mechanism (KEM), not an encryption function. It produces a shared secret that both parties can derive independently — you then use that shared secret with a symmetric cipher like AES for actual encryption.

The shared secret is different each time you call KyberEncapsulate, even with the same public key. This is by design — each encapsulation is randomised.

Only Kyber public keys are accepted. Passing an RSA or EC key will throw an exception.

**Which variant?** Kyber768 (ML-KEM-768) is the recommended default, balancing security and performance. Kyber512 is faster with smaller keys but provides lower security. Kyber1024 provides the highest security at the cost of larger keys and ciphertexts.

# Examples

```cfml
// Kyber is a post-quantum key encapsulation mechanism (KEM)
// It lets two parties agree on a shared secret that's resistant to quantum computers
// Typical use: establish a shared secret, then use it for symmetric encryption (AES)

// Step 1: Recipient generates a Kyber key pair and shares the public key
keys = GenerateKeyPair( "Kyber768" );

// Step 2: Sender encapsulates - produces a shared secret and a ciphertext
encapResult = KyberEncapsulate( keys.public );
// encapResult.sharedSecret - binary, use this for encryption
// encapResult.ciphertext   - send this to the recipient

// Step 3: Recipient decapsulates with their private key to get the same shared secret
sharedSecret = KyberDecapsulate( keys.private, encapResult.ciphertext );
// sharedSecret == encapResult.sharedSecret

// Each encapsulation produces different ciphertext (randomised)
// but decapsulation always recovers the matching shared secret

// Use the shared secret for AES encryption
senderKey = binaryEncode( encapResult.sharedSecret, "base64" );
encrypted = Encrypt( "Hello, quantum-safe world!", senderKey, "AES/CBC/PKCS5Padding", "Base64" );

// Available Kyber variants (higher = more security, larger keys):
// Kyber512, Kyber768 (recommended), Kyber1024, ML-KEM-768 (alias)
```







# Categories

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

# See Also

[GenerateKeyPair()](generatekeypair.md), [KyberDecapsulate()](kyberdecapsulate.md)