Skip to content

PATTERN Cited by 1 source

Crypto-API guardrails

Shape

Prevent the creation of new cryptographic usages vulnerable to a known-coming weakness (typically: quantum-vulnerable primitives ahead of a PQC migration) by applying friction at the point of creation, not just at the point of deprecation. The pattern has three layered controls, increasing in enforcement strength:

1. Update crypto guidelines      ← awareness, no enforcement
2. Friction on key generation    ← warn when creating new vulnerable keys
3. Friction on API use           ← warn during code review on call sites

Each layer closes a different creation pathway. Together they bound the size of the future migration: old usages will be migrated by the forward programme, but new ones shouldn't accumulate while the programme is underway.

Meta's explicit articulation:

Besides migrating existing applications, we should also prevent applications from being designed with quantum vulnerable cryptographic algorithms in mind. This can be done by adding friction to any new use case trying to use quantum vulnerable algorithms. (Source: sources/2026-04-16-meta-post-quantum-cryptography-migration-at-meta-framework-lesson)

The three layers

1. Update internal cryptography guidelines

The lowest-enforcement layer:

Update internal cryptography guidelines documents to warn teams about the risks of adopting quantum vulnerable public-key cryptography, and the need to eventually migrate to PQC.

This is pure documentation. Necessary because teams referencing guidelines for new-design decisions will see the warning, but insufficient because:

  • Many teams don't consult guidelines.
  • "Warning" is easy to dismiss.
  • No record of who saw what when.

Guidelines are the floor, not the wall.

2. Discourage new quantum-vulnerable key creation

Enforcement at the key-generation tool layer:

If the organization controls the tools to generate keys, those tools should warn teams when they request the creation of new quantum vulnerable keys. This wouldn't fully prevent teams from generating such keys using other interfaces but would likely require them to engage with the internal crypto team.

Mechanism: the central key-generation tooling (Meta's internal crypto tools, sibling KMS-equivalent systems elsewhere) emits a warning or requires justification when asked for a quantum- vulnerable key type. Teams that truly need one must engage the crypto team and document the need.

Why this layer matters:

  • Captures intent at creation: the team that asks for the key knows why they need it.
  • Creates an engagement touchpoint: crypto team gets visibility into new use cases, can suggest PQ alternatives.
  • Forces explicit override: engineering has to choose to bypass by using another interface — that choice is attributable.

Limit: "wouldn't fully prevent teams from generating such keys using other interfaces" — teams can use raw libraries, HSMs via alternate paths, third-party services. Defence in depth requires layer 3.

3. Discourage use of affected APIs during code review

The highest-enforcement layer, gated by build-system policy:

If the organization benefits from a centrally managed source code repository with tightly controlled building system (e.g., Buck system), it can create rules that prevent the usage of potentially affected APIs (e.g., RSA or ECDH APIs), and thus warn teams during code review if they try to use them.

Mechanism: build-system rules that flag import + reference to quantum-vulnerable crypto APIs during CI + code review. Teams trying to use RSA / ECDH / other classical primitives see the warning at review time and must either:

  • Use the PQ alternative instead.
  • Add an exemption annotation (auditable record).
  • Get crypto-team sign-off.

This is the code-review-gating posture Meta uses for other policy-enforcement surfaces — e.g. Sapling + Glean-based diff-based static analysis on source changes — adapted to cryptographic APIs specifically.

Prerequisites: monorepo + centrally-managed build system (Buck, Bazel, Pants; not easily bolted onto fragmented per-repo setups). For organisations without this substrate, layer 2 is the highest layer typically reachable.

Why friction, not hard prohibition

Hard prohibition "you can't use RSA" would:

  • Block legitimate interop — external services, legacy protocols, non-negotiable APIs still require classical primitives.
  • Force shadow usage — teams would circumvent by forking, by using external services, by copy-paste.
  • Create unnecessary reviews — not every RSA usage is a migration risk.

Friction + annotation gives:

  • New-usage discoverability — every new classical-crypto usage is flagged and reviewable.
  • Auditable trail — exemptions are recorded.
  • Natural forcing function — teams see the PQ alternative in the review warning, sometimes adopt it voluntarily.

Feedback into inventory

Guardrails aren't separate from inventory — they augment it:

  • New usages discovered at build/review time are added to the inventory.
  • Exemption records provide the "why" intent that automated discovery alone can't capture.
  • Build-rule violations are a leading indicator of migration scope changes.

Complement to existing migration work

Guardrails are the forward-looking complement to the backward-looking migration of existing call-sites. Without guardrails, the migration programme is running on a treadmill: you migrate old usages while new ones are added faster than you can catch up. With guardrails, the migration scope stops growing (modulo exempted cases) and the programme actually converges.

Wiki-canonical instance

Meta's 2026-04-16 PQC migration post is the canonical wiki instance, but the pattern generalises:

  • Classical deprecation (TLS 1.0, SHA-1, RSA-1024) — same three-layer discipline.
  • FIPS compliance — same three-layer discipline for non-FIPS-approved primitives.
  • Vendor API lock-in prevention — same shape applied to any category of "new usages should not accumulate".

Seen in

Last updated · 319 distilled / 1,201 read