Before you begin

Requirement	Details
Python	3.10 or newer
C compiler	Optional — enables the fast native backend
Operating system	Linux · macOS · Windows (pure-Python path)
Runtime dependencies	None

Step 1 · Install

From PyPI

pip install vortex-pqc

From source

git clone https://github.com/bajpai-labs/vortex-pqc.git
cd vortex-pqc
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Which backend am I using?

import vortex_pqc
print(vortex_pqc.native_backend())

Output	Meaning
vortex-pqc-native-aarch64	C extension active (fast)
vortex-pqc-native-x86_64	C extension active (fast)
vortex-pqc-pure-python	Reference implementation (always correct)

Step 2 · Your first key exchange

from vortex_pqc import generate_keypair, encapsulate, decapsulate

# Alice generates a key pair
alice = generate_keypair()

# Bob encapsulates a shared secret to Alice's public key
bob = encapsulate(alice.public_key)

# Bob sends bob.data (768 bytes) over the network …

# Alice recovers the same secret
alice_secret = decapsulate(bob.data, alice.private_key)

assert alice_secret == bob.shared_secret

Step 3 · Object sizes

from vortex_pqc import (
    PUBLIC_KEY_BYTES,     # 800
    PRIVATE_KEY_BYTES,    # 1248
    CIPHERTEXT_BYTES,     # 768
    SHARED_SECRET_BYTES,  # 32
)

Object	Bytes	Who holds it
Public key	800	Alice (published)
Private key	1248	Alice (secret)
Ciphertext	768	Sent by Bob → Alice
Shared secret	32	Both parties (derived)

Step 4 · PEM key files

VORTEX uses standard Base64 PEM — not hex — so it works with ordinary PEM tooling.

from vortex_pqc import (
    PEMKind,
    generate_keypair,
    encapsulate,
    write_pem_file,
    read_pem_file,
)

alice = generate_keypair()
bob   = encapsulate(alice.public_key)

write_pem_file("alice_pub.pem",   PEMKind.PUBLIC_KEY,    alice.public_key)
write_pem_file("alice_key.pem",   PEMKind.PRIVATE_KEY,   alice.private_key)
write_pem_file("ciphertext.pem",  PEMKind.CIPHERTEXT,    bob.data)
write_pem_file("secret.pem",      PEMKind.SHARED_SECRET, bob.shared_secret)

# Read back
sk = read_pem_file("alice_key.pem", PEMKind.PRIVATE_KEY)

A private key file looks like:

-----BEGIN VORTEX256 PRIVATE KEY-----
AQDQABAAABAAAA0AAAAAAPDP/gzQAhAAAAAAAA3QAA0AAPDPAQAAASAAAADQ/wwA
AAAAAA//zPAC0AAO3PARAAAQAAAP3PAQDQAPDPAiAAABAAAA0A/wzQARAAARAA
...
-----END VORTEX256 PRIVATE KEY-----

Private key files are written with permissions 0600.

→ Full spec: PEM Format

Step 5 · C library

cd c
make lib      # → build/libvortex_pqc.a
make test     # unit tests
make demo     # Alice–Bob CLI demo

#include "vortex_pqc.h"
#include <stdio.h>
#include <string.h>

int main(void) {
    uint8_t pk[VORTEX_PUBLIC_KEY_BYTES];
    uint8_t sk[VORTEX_PRIVATE_KEY_BYTES];
    uint8_t ct[VORTEX_CIPHERTEXT_BYTES];
    uint8_t ss_enc[VORTEX_SHARED_SECRET_BYTES];
    uint8_t ss_dec[VORTEX_SHARED_SECRET_BYTES];

    vortex_keypair(pk, sk);
    vortex_enc(pk, ct, ss_enc);
    vortex_dec(ct, sk, ss_dec);

    printf("Match: %s\n",
           memcmp(ss_enc, ss_dec, 32) == 0 ? "yes" : "no");
    return 0;
}

Benchmarking

from vortex_pqc import benchmark_throughput

stats = benchmark_throughput(operations=50)
for op, result in stats.items():
    print(f"{op:8s}  {result['mean_ops']:,.0f} ops/s")

Optional extras:

pip install "vortex-pqc[benchmark]"

Troubleshooting

Error	Cause	Fix
Invalid public key length	Wrong byte count to encapsulate	Pass exactly 800 bytes
Invalid ciphertext length	Wrong byte count to decapsulate	Pass exactly 768 bytes
invalid data length for PEM	Data size doesn't match PEMKind	Check kind matches your bytes
Shared secrets don't match	Mismatched keys or tampered ciphertext	Verify pk/sk/ct belong together

What's next?

Integrating into your app? → API Reference Need the math? → Cryptography

Contributing? → Development Guide Understanding the codebase? → Architecture