Cryptography Inventory

This page lists the gateway code paths that use cryptography, what primitive or protocol is involved, and whether the implementation is delegated to a vetted library or assembled in gateway code.

Summary

Gateway code should not implement cryptographic primitives. The code may assemble protocol-specific inputs, choose encodings, and call platform/library APIs. Private-key PEM parsing must stay centralized in PemPrivateKeys.

Area	Location	Primitive/protocol	Implemented by libraries	Implemented by gateway
Apple Pay token decrypt	services/online-txn/.../ApplePayTokenDecryptor.kt	CMS signature, X.509 path validation, ECDH P-256, SHA-256 KDF, AES-256-GCM	BouncyCastle CMS, Java cert APIs, JCA KeyAgreement, JCA Cipher, JCA MessageDigest	Token JSON extraction, Apple signed-content byte assembly, Apple KDF input assembly, Apple OID enforcement
Apple Pay mTLS session validation	services/online-txn/.../WalletService.kt	TLS client certificate auth	Java KeyStore, KeyManagerFactory, TrustManagerFactory, SSLContext, HttpsURLConnection	Loads configured cert/key, validates Apple validation URL policy, builds Apple request JSON
Apple Pay merchant registration	services/management/.../WalletProvisioningService.kt	TLS client certificate auth	Java TLS/key APIs	Loads configured cert/key, builds Apple registration JSON
Private-key PEM parsing	libs/security/.../PemPrivateKeys.kt	RSA PKCS#8, EC P-256 SEC 1/PKCS#8	BouncyCastle PEMParser/JcaPEMKeyConverter, JCA KeyFactory	Centralized type enforcement and SEC 1 P-256 normalization
Webhook delivery signatures	libs/security/.../SignedWebhookDeliveryClient.kt	HMAC-SHA256	JCA Mac	Builds timestamp.payload, encodes Pinpoint as Base64 and Peak as lower hex
TypeScript SDK webhook verification	sdks/typescript/gateway-sdk/.../webhook-verifier.ts	HMAC-SHA256	Web Crypto API	Builds timestamp.payload, lower-hex encoding, constant-time string compare
Kotlin SDK webhook verification	sdks/kotlin/gateway-sdk-core/.../WebhookVerifier.kt	HMAC-SHA256	Platform JCA/CommonCrypto actuals	Builds timestamp.payload, constant-time string compare
Webhook secret storage	libs/security/.../KmsEncryptionService.kt	Envelope encryption, AES-256-GCM, Cloud KMS key wrapping	JCA Cipher, SecureRandom, Google Cloud KMS	wrappedDEK:iv:ciphertext storage format, legacy plaintext fallback metric
OAuth signing key loading	services/auth/.../AuthorizationServerConfig.kt	RSA signing key material	PemPrivateKeys, JCA KeyFactory, Spring Authorization Server/Nimbus JWT stack	Derives public key from private key and stable kid
Device proof of possession	services/auth/.../DeviceEnrollmentService.kt	ECDSA/RSA signature verification	JCA Signature, JCA KeyFactory	Chooses algorithm from public key type, decodes SPKI public key
XTMS vendor auth	libs/xtms-client/.../XtmsAuthSigner.kt	Vendor SHA-256 signature scheme	JCA MessageDigest	Builds vendor-specified sorted parameter string
Gift card lookup hashing	services/processing/.../GiftCardSupport.kt	HMAC-SHA256, BCrypt	JCA Mac, Spring BCryptPasswordEncoder	Organization-scoped key derivation string for card hash
Android SmartConnect local storage	sdks/kotlin/gateway-sdk-android/.../EncryptedSnapshotStorage.kt	AES-256-GCM local snapshot encryption	JCA Cipher, SecureRandom	Local wrapper format and file persistence
Operational fingerprints	TokenHasher, PiiRedactor, idempotency/rate limiting	SHA-256 hashes	JCA MessageDigest	Truncation/hex encoding for logs and identifiers

Guardrails

• New private-key parsing must go through PemPrivateKeys.
• The pre-commit hook centralized-private-key-parsing blocks direct PKCS8EncodedKeySpec, PEMParser, or JcaPEMKeyConverter use outside PemPrivateKeys.
• Webhook signatures must use HMAC-SHA256 over timestamp.payload.
• Peak webhook signatures are lower hex. Pinpoint compatibility signatures remain Base64.
• KMS legacy plaintext decrypts increment gateway.kms.decrypt_legacy_plaintext.total; any non-zero value means stored secrets still need rotation.

Review Checklist

When adding or changing crypto code:

1. Identify the external protocol or standard being implemented.
2. Use JCA, BouncyCastle, Web Crypto, Cloud KMS, TLS, or Spring security primitives; do not hand-roll primitives.
3. Keep key parsing, hex encoding, and constant-time comparisons in shared helpers where module boundaries allow it.
4. Add a regression test with the real protocol shape, including optional fields that affect signed content.
5. Document any compatibility encoding, such as Base64 versus hex signatures.