Guidelines are based on scientific sources.
| Name | Usable Crypto APIs |
| Sources | (Green and Smith, 2016) |
| Synonyms | None |
| Context | Design of Crypto APIs for Software Developers While it has become accepted that systems should be user-friendly and robust to the end-user, the prevailing attitude towards software developers amongst cryptographer library designers is that they are experts and thus should know better. As a consequence, many recent security incidents were not caused by end-users, but rather by software developers making mistakes. Therefore ten recommendations for creating usable, secure crypto APIs for developers should be considered: |
| Item1 | Integrate crypto functionality into standard APIs so regular developers do not have to interact with crypto APIs in the first place. Integrate crypto APIs into non-security related APIs, in such a way that the regular developer does not have to interact with the crypto API at all. |
| Item2 | Sufficiently powerful to satisfy both security and non-security requirements. The API should be designed in such a way that it is powerful enough to satisfy all the requirements. |
| Item3 | Easy to learn, even without cryptographic expertise. APIs should strive to be designed in a way that developers do not need to understand the background in order to correctly use the API. |
| Item4 | Don’t break the developer’s paradigm. |
| Item5 | Easy to use, even without documentation. If the API is not self-explanatory or worse gives the false impression that it is, developers will make dangerous mistakes. [Principle] Expected Ability |
| Item6 | Hard to misuse. Incorrect use should lead to visible errors. Security APIs should pay special attention to preventing incorrect use and making error visible. [Principle] Visibility |
| Item7 | Defaults should be safe and never ambiguous A fundamental principle of usable security is to avoid providing users with default behaviors that are either ambiguous or unsafe. [Principle] Path of Least Resistance] [Principle] Provide Standardized Security Policies |
| Item8 | Testing Mode. Security mechanisms often come with a complexity or performance penalty. While this is a necessary trade-off in production use, it is legitimate and understandable if developers wish to be able to test their software with reduced or no security for convenience. |
| Item9 | Easy to read and maintain code that uses “Updatability”. Bloch (Bloch, 2006) recommends that API designers should try and ensure that it is easy to maintain code that uses the API. In the security context this is particularly important since it is essential that security code be kept up to date. |
| Item10 | Assist with/handle end-user interaction. Firstly, most developers using a security API do not have a firm grasp on the cryptographic or security background and thus would be hard pressed to explain to the end-user what went wrong. Secondly, even with a solid understanding of what went wrong, designing good warning messages is an art to itself. |
| Examples | None |
| Related Guidelines | None |
| Tags | Usability, Cryptography, API, Developers |
| Log history | [11/22/2016]: Added to repository [01/30/2019]: Formal guideline revision |
Bloch, J., 2006. How to design a good aPI and why it matters, in: Companion to the 21st ACM SIGPLAN Symposium on Object-Oriented Programming Systems, Languages, and Applications, OOPSLA ’06. ACM, New York, NY, USA, pp. 506–507. doi:10.1145/1176617.1176622
Green, M., Smith, M., 2016. Developers are Not the Enemy!: The Need for Usable Security APIs. IEEE Security Privacy 14, 40–46. doi:10.1109/MSP.2016.111