NOTES · · 1 min read
What API design tells developers about cryptography
Function names, defaults and error codes are documentation too. Here is what they quietly teach.
This is example text to show the note layout. Replace it in the CMS.
Every cryptographic library teaches its users something, whether it means to or not. A function called encrypt that silently accepts a reused nonce teaches that nonces don't matter.
Defaults are decisions
When a parameter is optional, the library has made a security decision on the developer's behalf. Good defaults are the cheapest security control there is.
// Easy to misuse: the caller chooses everything
encrypt(key, nonce, plaintext, aad, tag_len);
// Hard to misuse: the library chooses the dangerous parts
sealed = box.seal(plaintext);Errors should be loud
A decryption failure returned as an integer is easy to ignore. A failure that makes the plaintext unavailable is not.
Three questions for any crypto API
- What happens if I call it with the wrong arguments?
- What does the shortest working example look like, and is it safe?
- Which mistakes does the type system catch for me?