giftcrypt 1.0.0

Encryption and decryption primitives for gift card data (physical and virtual)

giftcrypt

Encryption and decryption of 16-digit gift card numbers (physical and virtual).

Version: 1.0.0

---

Overview

giftcrypt is a Python package used by the GC Activation Orchestrator to encrypt a plain 16-digit gift card number before writing it to Vault DB, and to decrypt it when reading back.

Two backends are supported:

Backend	Mechanism	When to use
gcm	AES-256-GCM local key	Local development and testing
kms_wrapped	AWS KMS envelope encryption	Production (recommended)

---

Installation

pip install cryptography          # for gcm backend
pip install cryptography boto3    # for kms_wrapped backend

---

Usage

The only function the Orchestrator needs to call is in vault.py:

from giftcrypt.vault import encrypt_card_number, decrypt_card_number

---

Local / dev testing (GCM backend)

No AWS needed. Uses a local secret key.

from giftcrypt.vault import encrypt_card_number, decrypt_card_number

key = "my-secret-encryption-key"

# Encrypt — after SVS activates the card (PGC or VGC)
ciphertext = encrypt_card_number(
    "1234567890123456",
    backend="gcm",
    key=key,
)
# → store ciphertext in Vault DB

# Decrypt — when reading back from Vault DB
card_number = decrypt_card_number(ciphertext, backend="gcm", key=key)
assert card_number == "1234567890123456"

---

Production (KMS wrapped backend)

Requires AWS account and KMS key. Card number never leaves your Lambda.

from giftcrypt.vault import encrypt_card_number, decrypt_card_number

KEY_ALIAS = "alias/giftcard-key"
REGION    = "us-east-1"

# PGC — card number from KIBO shipment swipe
# VGC — card number freshly issued by SVS
# Both use the exact same call:

ciphertext = encrypt_card_number(
    "1234567890123456",
    backend="kms_wrapped",
    key_alias=KEY_ALIAS,
    region=REGION,
)
# → store ciphertext in Vault DB

card_number = decrypt_card_number(ciphertext, backend="kms_wrapped", region=REGION)
assert card_number == "1234567890123456"

---

Input formats accepted

Dashes and spaces are stripped automatically before encryption:

encrypt_card_number("1234567890123456")      # plain
encrypt_card_number("1234-5678-9012-3456")   # dashes stripped
encrypt_card_number("1234 5678 9012 3456")   # spaces stripped
# all three store the same normalised value: "1234567890123456"

---

Package structure

giftcrypt/
├── giftcrypt/
│   ├── __init__.py       # package entry point
│   ├── vault.py          # primary interface — validate, normalise, route
│   ├── gcm.py            # AES-256-GCM local encryption
│   └── kms_wrapped.py    # AWS KMS envelope encryption
└── tests/
    ├── test_gcm.py        # 10 tests
    └── test_vault.py      # 21 tests

---

Running tests

No AWS account needed — KMS is fully mocked:

py -m pytest tests/ -v

Expected output:

31 passed in 0.82s

---

AWS KMS setup (for production)

1. Create an AWS account at https://aws.amazon.com/free
2. Create a KMS key in AWS Console → KMS → Create key
3. Set alias to alias/giftcard-key
4. Run aws configure on your machine to set up credentials
5. Create conf/test.yml:

aws:
  profile: your_aws_profile
  region: us-east-1
  key_alias: alias/giftcard-key

6. Run the KMS smoke test:

py kms_smoke_test.py

---

Ciphertext envelope formats

GCM envelope — pipe-separated, base64url-encoded:

v1|<iv>|<tag>|<aad>|<ciphertext>

KMS wrapped envelope — base64-encoded JSON:

{
  "version": "kms-wrapped-v1",
  "key_id": "arn:aws:kms:us-east-1:...",
  "wrapped_data_key": "...",
  "iv": "...",
  "ciphertext": "..."
}

---

License

MIT