API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2...
Transcript of API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2...
![Page 1: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/1.jpg)
API design for cryptography
Frank Denis - @jedisct1
![Page 2: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/2.jpg)
Who’s that creepy guy?Frank Denis@jedisct1
https://primulinus.com
Application security, cryptography, malware analysis, protocol design, computer vision/digital image processing…
OSS zealot
Spends way too much time on Twitter
![Page 3: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/3.jpg)
Crypto is everywhereAnd its domain extends way beyond mere encryption.
![Page 4: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/4.jpg)
![Page 5: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/5.jpg)
![Page 6: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/6.jpg)
![Page 7: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/7.jpg)
![Page 8: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/8.jpg)
![Page 9: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/9.jpg)
![Page 10: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/10.jpg)
![Page 11: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/11.jpg)
![Page 12: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/12.jpg)
![Page 13: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/13.jpg)
![Page 14: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/14.jpg)
AES
Blowfish
CAST-128
Camellia
DESGOST
IDEARC2
RC4
RC5RC6
SEED
3DES
Twofish
![Page 15: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/15.jpg)
AES
Blowfish
CAST-128
Camellia
DESGOST
IDEARC2
RC4
RC5RC6
SEED
3DES
Twofish
CBC
CCM
CFB
CTR
EAX
ECBGCM
OCB
OFB
XTS
![Page 16: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/16.jpg)
AES
Blowfish
CAST-128
Camellia
DESGOST
IDEARC2
RC4
RC5RC6
SEED
3DES
Twofish
CBC
CCM
CFB
CTR
EAX
ECBGCM
OCB
OFB
XTS
56 bits
128 bits
192 bits
256 bits
![Page 17: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/17.jpg)
AES
Blowfish
CAST-128
Camellia
DESGOST
IDEARC2
RC4
RC5RC6
SEED
3DES
Twofish
CBC
CCM
CFB
CTR
EAX
ECBGCM
OCB
OFB
XTS
56 bits
128 bits
192 bits
256 bits
MACPadding
Yadi Yada
![Page 18: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/18.jpg)
![Page 19: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/19.jpg)
How to encrypt stuff in PHP?
![Page 20: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/20.jpg)
![Page 21: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/21.jpg)
Reference documentation
![Page 22: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/22.jpg)
![Page 23: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/23.jpg)
*USING* crypto is hard, too
Crypto is hard
![Page 24: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/24.jpg)
Developers are not to blame
This leads to security disasters.
![Page 25: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/25.jpg)
Crypto is often a necessary, but tiny piece
in an application
Developers expect things to just work.Like all other pieces their application depends on.
![Page 26: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/26.jpg)
Webcrypto API
![Page 27: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/27.jpg)
Noooooo…
…ooo…
…ooo…
…ooo…
…ooo…
…ooo…
…ooo…
…ooo…
…ooo…
…ooooooo!
…ooo……ooo…
![Page 28: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/28.jpg)
NaClFunded by the European Commission, released in 2010.
Focused on high-speed cryptographyand improving usability.
Restricted to a small set of primitives and parameters chosen by experts
High-level APIs for common operations
Optimized for the host it was compiled on, using tricks of the C language to save extra CPU cycles
![Page 29: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/29.jpg)
3 years later: adoption rate remains very low
State-of-the-start, simple, highly secure, high-speed cryptography!
![Page 30: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/30.jpg)
2013: libsodium
![Page 31: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/31.jpg)
Warning: this is not a talk about libsodium
Libsodium just happens to be a good case to look at, because its API has evolved a lot over time.
Let’s see why, how,and some takeaways from the past 4 years
![Page 32: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/32.jpg)
Slow version of NaCl:Instant success!
![Page 33: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/33.jpg)
Usability was the #1 problem to solve in cryptography
Not speed
Not security
¯\_(ツ)_/¯
![Page 34: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/34.jpg)
Cryptography makes devices communicate securely.
Cross-platform support is no more an option.
Today’s minimum expectations:
Linux MacOS
iOS Android
Windows (Visual Studio) Embedded systems
Javascript / WebAssembly
![Page 35: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/35.jpg)
Today’s applications are written using a combination of programming languages.
APIs designed for a specific language are problematic.
Macros and pointer arithmetic don’t play well with (not(C | C++))
![Page 36: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/36.jpg)
Expose everything as a function
crypto_box_KEYBYTES -> crypto_box_keybytes()
![Page 37: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/37.jpg)
Package maintainers are your best friends
![Page 38: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/38.jpg)
How developers want to install dependencies today:
pkg_add, apt-get, brew, pacman, choco…
One pre-built, universal package.
Mainstream build systems suck. All of them.
But package maintainers know how to use them.
And adoption of your project depends on package maintainers.
![Page 39: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/39.jpg)
Key idea behind NaCl/libsodium: expose high-level APIs for common operations
“I want to encrypt a message”
“I want to verify that a messagehasn’t been tampered with”
“I want to store a password”(and stay cool if my company name ever ends up on haveibeenpwned.com)
![Page 40: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/40.jpg)
Simple functions that keep the amount of user-supplied
parameters down to a minimum
crypto_box_seal(c, “message”, 7, secret_key)
![Page 41: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/41.jpg)
Nobody reads the f* documentation
What experts want: all the gory details about the chosen primitives, constructions and parameters
What everybody else want: example code, code snippets to copy/paste
Also keep in mind that for most people,a “secret key” means “a password”
![Page 42: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/42.jpg)
Provide examples, *then* explain:
![Page 43: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/43.jpg)
Watch how people use your APIs in their own
projects
Watch yourself struggle when using that very API
in your own projects
![Page 44: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/44.jpg)
How libraries are used in real-world projects
crypto_box(): everybody writes wrappers.
crypto_sign(): everybody writes wrappers.Vulnerability in early Golang bindings due to a
misunderstanding of the API.
OpenSSL: libtls + a bazillion incompatible abstraction layers in all programming languages. Either close to the metal and
dangerous, or completely different from the original API.
![Page 45: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/45.jpg)
If people write wrappers, your API could be improved
![Page 46: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/46.jpg)
Watch what people are building with your APIs
Watch for recurring questions on Github, Stackoverflow, etc.
![Page 47: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/47.jpg)
If something is not available out of the box, people will reinvent it.
So, implement it.
![Page 48: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/48.jpg)
“It’s only 1 or 2 trivial lines of code, I’m not gonna add yet
another set of APIs just for that [very common feature request]”
/me, not so long ago.
![Page 49: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/49.jpg)
Reality check
• Adding a trivial function is not always bloat. It can be well worth it.
• It will improve code clarity, prevent bugs.
• It will save you from having to answer the same questions over and over again.
• It will make users aware that this operation is actually possible.
![Page 50: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/50.jpg)
Libsodium examples• crypto_box_keygen() to create a secret key.
• crypto_box_seal() to delete the secret key after encryption.
• crypto_kdf() for key derivation.
• randombytes_deterministic() for deterministic random numbers.
All of these are small and trivial functions, yet turned out to be welcome additions.
![Page 51: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/51.jpg)
High-level APIs frustrate power users
Expose low-level APIs as well, with access to more parameters.
Documentation should remain focused on high-level APIs.
Do not expose specific implementations,
or you’ll be screwed later.
![Page 52: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/52.jpg)
Does it solve a common problem impossible to
solve with the current APIs?
Adding new primitives, new constructions:
![Page 53: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/53.jpg)
Adding new operations
Build a distinct project, maintained independently. Experiment with new APIs. Wait for feedback. Watch how
these APIs are being used.
Or if people use them at all.
Look at how people solved similar problems. Tweak the prototype. Use-it in your own apps. Tweak it again.
Eventually, port it to the main project (or not).
Example: blobcrypt
![Page 54: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/54.jpg)
Watch how people use your APIs in their own
projects
Watch yourself struggle when using that very API
in your own projects
Again:
![Page 55: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/55.jpg)
Nonces (IVs)Supplement the secret key.
Must be unique for a given key.
The security of most nonce-based ciphers can be totally destroyed if not.
Shall a crypto API require nonces from applications?
![Page 56: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/56.jpg)
Yes:• Some protocols mandate specific nonces •Nonces can be used to avoid replay attacks/associate
questions with responses in non-pipelined protocols •Come on, anyone can generate random data and
maintain counters!
No:•Users are too stupid to generate nonces (that’s what
“misuse resistance” stands for, right?)— Not exactly.
![Page 57: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/57.jpg)
Why “No” should be the answer today:
• Requires redundant code, that APIs could avoid.
• People don’t have time to read documentation. Documentation can be misleading or incomplete.
• Maintaining counters is complicated in today’s world where apps run in the cloud, in multiple containers sharing the same secret keys.
• Different ciphers have different requirements and security guarantees. Random nonces may not be secure. Ditto for counters. Protocols defining nonce constructions may be broken. APIs should hide these details and do the right thing instead of blaming users for “misuse”.
• iOT/embedded systems: safely generating unique/random numbers may not be possible at all.
![Page 58: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/58.jpg)
Krack
CVE-2017-13077
CVE-2017-13078
CVE-2017-13079
CVE-2017-13080CVE-2017-13081
CVE-2017-13082
CVE-2017-13083
CVE-2017-13084
CVE-2017-13085
CVE-2017-13086
CVE-2017-13087
CVE-2017-13088
![Page 59: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/59.jpg)
Context separation
Reusing a secret key for different purposes can have catastrophic implications.
Applications will not do that, right?
![Page 60: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/60.jpg)
It may not be obvious at all:
![Page 61: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/61.jpg)
Shall we blame the developers?
Or could APIs prevent that?
Modern crypto APIs should consider context separation.
As of today, no major library does.
![Page 62: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/62.jpg)
Key exchangeInsufficient: provide a DH function.
Actually worse: provide a DH function + a lot of documentation about how to use it right.
Better in theory: use TLS.
Hell’s kitchen: reimplement a well-known AKE.
Playing with fire: invent a custom protocol.
Juggling with unlocked hand grenades blind-folded: reimplement TLS.
![Page 63: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/63.jpg)
Limitations
![Page 64: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/64.jpg)
LimitationsNo Practical
(from an API perspective)
Documentation make library developers feel guilt-free, but doesn’t fix actual problems.
![Page 65: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/65.jpg)
libhydrogen
Started as a lightweight crypto library for microcontrollers/constrained
environments.
Also an opportunity to design new APIs based on lessons from the past, and
current trends in cryptography.
![Page 66: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/66.jpg)
Key concepts:• Everything is built upon only two modern cryptographic building
blocks: the Gimli permutation and the Curve25519 elliptic curve.
• Concise, consistent, easy-to-use, hard-to-misuse high-level API.
• One key size for all operations.
• Context (domain separation) required by virtually all APIs. One context size for all operations.
• Do not assume that a CSPRNG is available, or works as expected.
• Implement what applications frequently use in other libraries.
![Page 67: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/67.jpg)
A single API for all your hashing needs
HMAC construction Hash function for short messages Hash function with 128 bit output Hash function with 256 bit output Hash function with 512 bit output XOF or KDF + stream cipher
One generic hashing API
Initial libhydrogen prototype: siphash128 + blake2S + blake2SX
Today: one sponge function
Zero changes to the API
![Page 68: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/68.jpg)
Encryption
Don’t ask applications for a nonce
Automatically attach a synthetic nonce to the ciphertext
“misuse” resistant
![Page 69: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/69.jpg)
EncryptionWhy do applications need explicit nonces/AD?
• Check that if we expect the 3rd message in sequence, what we just received actually is the 3rd message.
• Check a message id, to reorder fragmented, unordered messages (e.g. UDP datagrams).
• Check that a message is not older than a given timestamp.
• Check a protocol version.
![Page 70: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/70.jpg)
EncryptionWhy do applications need explicit nonces/AD?
• Check that a value attached to a message is the one we expect
• Check that a value attached to a message is the one we expect
• Check that a value attached to a message is the one we expect
• Check that a value attached to a message is the one we expect
From an API perspective: no AD, no nonce, but a 64 bit integer
![Page 71: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/71.jpg)
Encryptionhydro_secretbox_keygen(key);
hydro_secretbox_encrypt(ciphertext, MESSAGE, MESSAGE_LEN, 1, CONTEXT, key);
hydro_secretbox_decrypt(decrypted, ciphertext, CIPHERTEXT_LEN, 1, CONTEXT, key)
![Page 72: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/72.jpg)
Be consistentHKDF parameters:
hash function, salt, key information.
Salt -> contextKey information -> 64 bit value
One vocabulary, same types used across all the APIs.
Even if the underlying primitives are more flexible, simplify their interface to what most real-world projects actually need.
![Page 73: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/73.jpg)
Key exchange
Protocol independent
Transport independent
Can be extended
Hard to get wrong
![Page 74: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/74.jpg)
Key exchangeBob:
hydro_kx_xx1() -> packet1
Alice:
hydro_kx_xx2(packet1) -> packet2
Bob:
hydro_kx_xx3(packet2) -> packet3
(Optional) Alice:
hydro_kx_xx4(packet3) -> DONE!
![Page 75: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/75.jpg)
Don’t reinvent the wheel
Noise
Noisesocket
Strobe
+ well-studied constructions
![Page 76: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/76.jpg)
Improving securitythrough better abstractions
From:
Many raw crypto primitives and combinators + high level APIs implementing specific protocols
To:
A translation of what primitives can do into what typical applications need. High-level building blocks with a simple,
unified interface modeled after real-world use cases.
Requirements: no limitations, MR, domain separation.
![Page 77: API design for cryptography - Hack.lu 2017 · 2017-10-22 · CAST-128 Camellia GOST DES IDEA RC2 RC4 RC5 RC6 SEED 3DES Twofish. AES Blowfish CAST-128 Camellia GOST DES IDEA RC2](https://reader030.fdocuments.net/reader030/viewer/2022041118/5f2fbf610547fa4a8e5dcd6a/html5/thumbnails/77.jpg)
Thanks!Frank Denis
@jedisct1 [email protected]
https://libsodium.org https://github.com/jedisct1/libhydrogen