apex-encoding-and-crypto

name	apex-encoding-and-crypto
description	Use when Apex must sign, verify, encrypt, hash, encode, or decode payloads — including HMAC for webhook signatures, RSA/ECDSA signing for JWT bearer flows, AES for stored secrets, base64/hex/URL encoding, and digest comparisons for integration integrity. Triggers: 'Crypto.sign', 'Crypto.generateMac', 'EncodingUtil.base64Encode', 'JWT signing in Apex', 'verify webhook signature'. NOT for setting up Named Credentials or OAuth flows end-to-end — use apex-named-credentials-patterns; NOT for SOQL injection defense — use soql-security.
category	apex
salesforce-version	Spring '25+
well-architected-pillars	["Security","Reliability"]
tags	["apex-encoding-and-crypto","hmac","jwt-signing","base64","encoding-util","crypto-class"]
triggers	["how do I verify an HMAC-SHA256 webhook signature in Apex","signing a JWT assertion for OAuth 2.0 JWT bearer flow from Apex","AES encrypt a secret before storing it in a custom field","EncodingUtil base64 vs urlEncode vs hex decision","compare two digests without a timing leak in Apex"]
inputs	["the payload type (bytes, string, record field) and desired algorithm","whether the key material lives in Named Credential, Protected Custom Metadata, or Certificate","the downstream consumer's expected encoding (base64, base64url, hex)"]
outputs	["a code path using Crypto / EncodingUtil with the right algorithm, key source, and encoding","review findings for weak algorithms, non-constant-time comparisons, or hardcoded keys","a test plan that pins known-answer vectors for the chosen algorithm"]
dependencies	[]
version	1.0.0
author	Pranav Nagrecha
updated	2026-04-23T00:00:00.000Z

Apex Encoding And Crypto

Use this skill when Apex code must sign, verify, hash, encrypt, or encode bytes — for integration signatures, JWT assertions, webhook verification, token obfuscation, or payload normalization. The purpose is to pick the right algorithm, pull key material from a managed source, and encode the output in the exact form the downstream consumer expects.

---

Before Starting

Gather this context before writing any Crypto or EncodingUtil call:

• What is the algorithm the other side actually uses? HMAC-SHA256, RSA-SHA256, AES-256-CBC, and SHA-512 all need different Crypto method names and payload shapes. An HMAC is not a digest; a digest is not a signature.
• Where is the key material? A hardcoded 'my-secret' literal in Apex fails every security review. Key material should come from a Named Credential (for HMAC shared secrets), a protected Custom Metadata record, or a Certificate stored in Setup (for RSA/ECDSA private keys signed via Crypto.signWithCertificate).
• What encoding does the consumer want? Base64 and base64url differ in three characters. Hex is lowercase by default. URL-form-encoded bodies need EncodingUtil.urlEncode(value, 'UTF-8'), not bare concatenation.
• Do you need a constant-time comparison? String equality (==) short-circuits and leaks bytes to an attacker timing the response. Use Crypto.getRandomInteger plus byte-wise loop, or compare full SHA-256 digests of both values instead of the raw HMACs.

---

Core Concepts

Crypto Does Symmetric And Asymmetric Work — With Different Methods

Crypto.generateDigest(algorithmName, input) produces a plain hash (MD5, SHA1, SHA-256, SHA-512). Hashes are not signatures — anyone can recompute them. Use them for integrity checks on non-adversarial payloads (deduplication, cache keys, file fingerprints).

Crypto.generateMac(algorithmName, input, privateKey) produces an HMAC keyed by a shared secret. Supported algorithms are HmacSHA1, HmacSHA256, HmacSHA384, HmacSHA512, and the weaker HmacMD5 — do not use HmacMD5 or HmacSHA1 for new work. HMACs are the right tool for webhook verification and request signing against a shared secret (Stripe, Slack, Twilio, GitHub all use HMAC-SHA256).

Crypto.sign(algorithmName, input, privateKey) produces an asymmetric signature using a raw private key blob. uses a certificate stored in Setup → Certificate and Key Management — this is the right pattern for OAuth 2.0 JWT bearer flow because the private key stays in the platform-managed certificate store and never appears as a literal in Apex.