Cryptography Best Practices for Developers

Chapter 1 · Practice 1 of 4

Never design your own algorithm, mode or protocol

From Choosing the right tool and library

Why it matters

OWASP's Cryptographic Storage Cheat Sheet answers the question of custom algorithms in three words: "Don't do this." The same applies to custom modes, padding schemes, token formats and handshakes built from raw primitives. Cryptographic designs fail in ways that tests do not catch: the code encrypts and decrypts correctly while leaking keys through timing, accepting forged messages or repeating nonces.

"Rolling your own" includes things that feel harmless:

  • XOR-ing data with a key, or "encrypting" with base64
  • Concatenating a secret and a message and hashing it as a signature (sha256(secret + body))
  • Inventing a token format that encrypts a user ID with AES-ECB
  • Picking a cipher, mode, IV size and MAC yourself from a low-level API when a one-call AEAD exists

What to do instead:

  1. Name the property you need (see the next practice).
  2. Use a maintained, high-level library that offers that property directly.
  3. Use standard formats and protocols (TLS, JWT with a vetted library, HPKE, age, PASETO) rather than designing message layouts.

Do

  • Use standard protocols and formats instead of inventing message layouts
  • Get a second review for any code that touches raw primitives
  • Treat "it decrypts fine" as no evidence of security

Avoid

  • Home-made ciphers, XOR schemes or encoding as encryption
  • Hashing a secret plus a message as a signature
  • Copying crypto snippets from forums without understanding the mode