www.crcs.cz/rsa @CRoCS_MUNI
PV286 - Secure coding principles and
practices
Automata-based programming
Designing good and secure API
Łukasz Chmielewski chmiel@fi.muni.cz (based on the lecture by P. Svenda)
(email me with your questions/feedback)
Centre for Research on Cryptography and Security, Masaryk University
Consultation hours: Friday 9.30-11.00 in A406 (but email me before).
www.crcs.cz/rsa @CRoCS_MUNI
Overview
• Today’s Lecture:
– How to write good & secure API
– automata-based programming
– In the corresponding PA193 seminars, the participants will write a small security
API and model the inner state with an automata-based design.
• There is a ROPOT this week
• Resources:
– We are recording so the video should be published next week.
– Recording from the last year (online lecture):
• https://is.muni.cz/auth/el/fi/jaro2023/PV286/um/lectures/lecture9_api/
– Materials: https://is.muni.cz/auth/el/fi/jaro2024/PV286/um/lecture7_secureapi_automataprogramming
2 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
ORGANIZATIONAL
3 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Rules about the project
• The deadline for the nearest deadline of the project is on 17/04.
– Please work on that!
• No plagiarism!
• Commit only to your work and not the work of other people!
– We need to differentiate between your efforts within teams.
• Everyone needs to work on the code!
– For example, concentrating on writing the report is not enough.
4 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
PROBLEM
5 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
What is this device for?
6 PV286 | Secure API, Automata-based programming
IBM 4758 Hardware Security Module (HSM)
www.crcs.cz/rsa @CRoCS_MUNI
Hardware Security Modules (HSM)
• Hardware Security Modules are high-security devices
– small security computer
• RAM, CPU, storage...
• resilience against tampering, side-channels...
– support various cryptographic operations
– keys are generated, stored and used directly on the device
– additional restricted code can be uploaded (firmware)
• HSM exposes its functionality via API
– E.g., encrypt supplied data with key generated inside HSM
• HSM is trusted, accessed by not-so-trusted applications
– HSM’s API serves as wall between different levels of trust
– Intentionally limits visibility and access
7 PV286 | Secure API, Automata-based programming
API
Security API
www.crcs.cz/rsa @CRoCS_MUNI
API
8 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
When we use API?
• All the time ☺
• When using function from standard library
• When using external library
• When calling system (Win32 API, POSIX...)
• When calling methods of our own class
• ...
9 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
When we design API?
• Almost all the time ☺
• Function signature is API for this function usage
• List of public methods in interface is its API
• When we create good API?
– good programming habit is to create reusable modules
– every module has its own API
– once module will get reused, API cannot be changed (easily)
10 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Application programming interface (API)
• Different types of API
1. Non-security API
– any library API (module/library interface)
– e.g., C++ STL, Boost library, Web REST API...
2. Cryptographic API
– set of functions for cryptographic operations
– e.g., Microsoft CryptoAPI, OpenSSL API...
3. Security API
– allows untrusted code to access sensitive resources in secure way
– e.g., PKCS#11 HSM module, suExec, OAuth
11 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
What is API and ABI?
• API = Application Programming Interface
– source code-based specification intended to be used as an interface between software
components to communicate
– classes, interfaces, methods, structure of json for webapi...
• ABI = Application Binary Interface
– specification of interface on binary level
– size, binary representation and layout of data types
– function calling conventions (stdcall, decl...)
– how to make system calls (functions outside program memory)
– binary formats of data produced (little/big endian…)
• API != ABI, but both are necessary
12 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Language (in)dependent API
• Language dependent API
– API available only for one particular language
– ABI is relevant (calling convention, memory layout…)
• Language independent API
– Not restricted to particular languages
– E.g., Web API based on HTTP/REST/JSON
• Language bindings
– Bridge between particular language and library/OS API
– E.g., library implemented in C, but called from Python
– Additional API in target language with small proxy code
13 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Web API
• Web API = API used to invoke method on web server
– Usually via HTTP(S) with REST
– Language independent API
• E.g., Twitter API
– POST https://api.twitter.com/1.1/statuses/update.json?status=At%20PA193
• Application programming interface key (API key)
– Code supplied by program calling an API
– Identifies program, developer, user…
– Can be used to control usage (e.g., limit requests…)
14 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Quiz – where is API stored?
• Language: C
– API: Functions listed in header files (*.h)
• Language: C++
– API: public methods of class
– API: public methods of abstract class
• Language: Java
– API: public methods of class
– API: methods of interface
• Twitter Web API
– API: HTTP/REST requests, response in JSON format
15 PV286 | Secure API, Automata-based programming
© Martin Handford
www.crcs.cz/rsa @CRoCS_MUNI
PRINCIPLES OF GOOD API
16 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Credits: Joshua Bloch
• Joshua Bloch, How to Design a Good API and Why it Matters
(Google)
– https://web.archive.org/web/20140209043631/http://lcsd05.cs.tamu.edu/slides/keynote.pdf
– video: http://www.infoq.com/presentations/effective-api-design
• Reading/watching is highly recommended
• Many ideas have been taken from his presentation
– demonstrated on cryptographic libraries by myself
18 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Principles of good API (Joshua Bloch)
1. Easy to learn
2. Easy to use, even without documentation
3. Hard to misuse
4. Easy to read and maintain code that uses it
5. Sufficiently powerful to satisfy requirements
6. Easy to extend
7. Appropriate to audience
• https://web.archive.org/web/20140209043631/http://lcsd05.cs.tamu.edu/slides/keynote.pdf
19 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Process of API design (Joshua Bloch)
1. Gather requirements
2. Start with short specification (1 page)
3. Write API early and often
4. Test and use your API
– especially when designing SPI (Service Providers Interface)
– write more plugins (one – NOK, two – difficult, three - OK)
5. Prepare for evolution and mistakes
– displease everyone equally
20 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI21 PV286 | Secure API, Automata-based programming
What is Service Provider Interface?
www.crcs.cz/rsa @CRoCS_MUNI
General principles - encapsulation
• API should do one thing and do it well
• As small as possible, but not smaller
– if in doubt, leave function out (you can add, but not remove)
• Implementation details should not leak into API
– try to hide as much as possible from user
• Minimalize accessibility (encapsulation)
– make public what really needs to be
– no public fields (attributes) except constants
• Make understandable names (self-explanatory, consistent, easy to
read when used)
24 PV286 | Secure API, Automata-based programming
if (key.length() < 80)
generateAlert(”NSA can crack!”);
www.crcs.cz/rsa @CRoCS_MUNI
General principles - documentation
• Document rigorously
– JavaDoc, Doxygen…
– specify how function should be used
– class: what instance represents
– Method: a contract between method and client
• preconditions, postconditions, side effects
– Parameters: who owns (ptr), units, format...
• Specific case of documentation are Annotations
– e.g., Microsoft SAL, pre&post conditions, Java annotations…
25 PV286 | Secure API, Automata-based programming
void* memcpy(void* destination, const void* source, size_t num);
void* memcpy(__out_bcount(num) void* destination,
__in_bcount(num) const void* source, size_t num);
/**
* \brief Output = HMAC-SHA-512( hmac key, input buffer )
*
* \param key HMAC secret key
* \param keylen length of the HMAC key
* \param input buffer holding the data
* \param ilen length of the input data
* \param output HMAC-SHA-384/512 result
* \param is384 0 = use SHA512, 1 = use SHA384
*/
www.crcs.cz/rsa @CRoCS_MUNI
Which one you like more? Why?
27 PV286 | Secure API, Automata-based programming
POLARSSL
/**
* \brief Output = HMAC-SHA-512( hmac key, input buffer )
*
* \param key HMAC secret key
* \param keylen length of the HMAC key
* \param input buffer holding the data
* \param ilen length of the input data
* \param output HMAC-SHA-384/512 result
* \param is384 0 = use SHA512, 1 = use SHA384
*/
void sha512_hmac( const unsigned char *key, size_t keylen,
const unsigned char *input, size_t ilen,
unsigned char output[64], int is384 );
OPENSSL
unsigned char *HMAC(const EVP_MD *evp_md, const void *key, int key_len,
const unsigned char *d, size_t n, unsigned char *md,
unsigned int *md_len);
www.crcs.cz/rsa @CRoCS_MUNI
OpenSSL – HMAC  (hard to understand)
28 PV286 | Secure API, Automata-based programming
//hmac.h
unsigned char *HMAC(const EVP_MD *evp_md, const void *key, int key_len,
const unsigned char *d, size_t n, unsigned char *md,
unsigned int *md_len);
//envp.h
struct env_md_st
{
int type;
int pkey_type;
int md_size;
unsigned long flags;
int (*init)(EVP_MD_CTX *ctx);
int (*update)(EVP_MD_CTX *ctx,const void *data,size_t count);
int (*final)(EVP_MD_CTX *ctx,unsigned char *md);
int (*copy)(EVP_MD_CTX *to,const EVP_MD_CTX *from);
int (*cleanup)(EVP_MD_CTX *ctx);
/* FIXME: prototype these some day */
int (*sign)(int type, const unsigned char *m, unsigned int m_length,
unsigned char *sigret, unsigned int *siglen, void *key);
int (*verify)(int type, const unsigned char *m, unsigned int m_length,
const unsigned char *sigbuf, unsigned int siglen,
....
} /* EVP_MD */;
//ossl_typ.h
typedef struct env_md_st EVP_MD;
www.crcs.cz/rsa @CRoCS_MUNI
General principles - performance
• Consider performance impact of API decisions
– but be not influenced by implementation details
– underlying performance issues will be fixed eventually, but API warping (for fixing past
issue) remains
• Examples of bad performance decisions
– need for frequent allocations and copy constructors
• pass arguments by reference or pointer
• use copy free functions
– usage of mutable objects instead of immutable
• use const everywhere possible
– need for frequent re-coding (byte[] -> string -> byte[])
29 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNIPV286 | Secure API, Automata-based programming
Copy-free functions
• API style which minimizes array copy operations
• Frequently used in cryptography
– we take block, process it and put back
– can take place inside original memory array
• int encrypt(byte array[], int startOffset, int length);
– encrypt data from startOffset to startOffset + length;
• Wrong(?) example:
– int encrypt(byte array[], int length, byte outArray[], int* pOutLength);
– note: C/C++ can still use pointers arithmetic
– note: Java can’t (we need to create new array)
30
www.crcs.cz/rsa @CRoCS_MUNI
Sensitive data (keys) in memory
• What is the difference?
• Try to limit copies of sensitive data in memory
– potential unintended disclosure (memory, swap…)
• Pass by value requires more memory erases
– What about Java’s pass by value of reference?
31 PV286 | Secure API, Automata-based programming
int set_key(Key_t key, pin_t seal_pin);
vs.
int set_key(Key_t* key, pin_t* seal_pin);
www.crcs.cz/rsa @CRoCS_MUNI
General principles – static factory
• Use static factory instead of class constructor
– e.g., javacardx.crypto & class::getInstance()
– e.g., javacardx.crypto & class::buildKey()
32 PV286 | Secure API, Automata-based programming
import javacardx.crypto.*;
// CREATE AES KEY OBJECT
m_aesKey = (AESKey) KeyBuilder.buildKey(KeyBuilder.TYPE_AES_TRANSIENT_DESELECT,
KeyBuilder.LENGTH_AES_256, false);
// CREATE OBJECTS FOR CBC CIPHERING
m_encryptCipher = Cipher.getInstance(Cipher.ALG_AES_BLOCK_128_CBC_NOPAD, false);
m_decryptCipher = Cipher.getInstance(Cipher.ALG_AES_BLOCK_128_CBC_NOPAD, false);
// CREATE RANDOM DATA GENERATOR
m_secureRandom = RandomData.getInstance(RandomData.ALG_SECURE_RANDOM);
// CREATE SHA256 ENGINE
m_sha256 = MessageDigest.getInstance(MessageDigest.ALG_SHA_256, false);
www.crcs.cz/rsa @CRoCS_MUNI
General principles – static factory
• Advantages of static factory over constructors
– provides named "constructors“ (getInstance, buildKey)
– can return null, if appropriate
– can return an instance of a derived class, if appropriate
– reduce verbosity when instantiating variables of generic/template types (no
need to write type twice)
– allows immutable classes to use pre-constructed instances or to cache
instances (speed)
– http://www.informit.com/articles/article.aspx?p=1216151
33 PV286 | Secure API, Automata-based programming
Map<String, list<String>>* m = new HashMap<String, List<String>>();
vs.
Map<String, list<String>> m = HashMap.newInstance();
www.crcs.cz/rsa @CRoCS_MUNI
General principles – behave as expected
• Principle of the last astonishment
– user should not be surprised by API behavior
• Be careful with overloading
– Use different names for methods when having the same number of arguments
– same behavior for same (position of) arguments
• Fail fast – report error as soon as possible
– failure in compile time is better
– during runtime, the first method invocation with a bad state should fail
• Provide methods to obtain data elements from results
provided originally in strings
– Do not force the programmer to parse strings
34 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Example: Avoid long parameter lists
36 PV286 | Secure API, Automata-based programming
WIN32 API
HWND WINAPI CreateWindow(
_In_opt_ LPCTSTR lpClassName,
_In_opt_ LPCTSTR lpWindowName,
_In_ DWORD dwStyle,
_In_ int x,
_In_ int y,
_In_ int nWidth,
_In_ int nHeight,
_In_opt_ HWND hWndParent,
_In_opt_ HMENU hMenu,
_In_opt_ HINSTANCE hInstance,
_In_opt_ LPVOID lpParam
);
QT API
QWidget window;
window.setWindowTitle("Window title");
window.resize(320, 240);
...
window.show();
Which one you like more?
Why?
www.crcs.cz/rsa @CRoCS_MUNI
General principles - parameters
• Avoid long parameter lists
– three or fewer parameters ideal (including default values)
• mistake in filling arguments might be missed in compile
• When more parameters are required:
– break the method into more methods
– Or encapsulate multiple arguments into a single class/struct
• Use consistent parameter ordering (src vs. desc)
37 PV286 | Secure API, Automata-based programming
#include <string.h>
char *strcpy (char* dest, char* src);
void bcopy (void* src, void* dst, int n);
Bad example
from C stdlib
www.crcs.cz/rsa @CRoCS_MUNI
Security API
• “A security API allows untrusted code to access sensitive resources in a
secure way.” Graham Steel
• Interface between different levels of trust
• Security API is designed to enforce a policy
– certain predefined security properties should always hold
– e.g., private key cannot be used before user is authenticated
• Security API is not equal to security protocols
– but closely related
– security protocol == short program how principals communicate
– security API == set of short programs called in any order
• http://www.lsv.ens-cachan.fr/~steel/security_APIs_FAQ.html
• http://www.cl.cam.ac.uk/~rja14/Papers/SEv2-c18.pdf
38 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Security API attack
• API attack is sequence of commands (function calls) which breach
security policy of an interface
• “Pure” API attacks – only sequence of commands
– e.g., key value is directly revealed
• “Augmented” API attacks – additional brute-force computations
required
– e.g., 128bits key value is exported under 56bits key
39 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Security API – problems in time
• Interfaces get richer and more complex over time
– pressure from customers to support more options
– economic pressures toward unsafe defaults
– Failures tend to arise from complexity, KISS!!!
– Hard to design secure API, and even harder to keep it secure
• Leaks when trusted component talks to less trusted
– Interface often leaks more information than anticipated by the designer of the
trusted component
40 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Security API - typical problems
• Unexpected command sequences
– methods called in different order than expected
– use method call fuzzer to test
– use automata-based programing to verify proper state
• Unknown commands
– invalid values as method arguments
– always make extensive input verification
– use fuzzer to test
41 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Security API - typical problems
• Commands in a wrong device mode
– sensitive operation (e.g., Sign()) called without previous authentication
– use methods order fuzzing to test
– use automata-based programing to ensure proper state
• Existence of undocumented API
– debugging API not removed (unintentionally)
– security by obscurity (be aware of reverse engineering)
– example: Crysalis Luna module (key extraction)
• http://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-592.pdf
45 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Security API - typical problems
• Multiple different APIs to single component/storage
– contracts within one set of API may be broken by second set
– possible interleaving of function calls from different APIs
– Example: Ultimaco HSM APIs
• Microsoft world: CNG, CSP, EKMI
• JCE, PKCS#11, OpenSSL
• administration API's: IT monitoring SNMP
– Example: IBM 4758 HSM APIs
• IBM CCA, VISA EMV, PKCS#11...
• IBM proprietary
• Attacks already used in the wild for large scale attacks
– http://www.wired.com/threatlevel/2009/04/pins/
46 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Security API: best practices
• Use API keys, not Username/Password
– e.g., OAuth instead of Basic Auth
• Don’t use sessions (if possible)
– build API as RESTful services
– “Each request from any client contains all of the information necessary to
service the request, and any session state is held in the client.” REST Wikipedia
– check client input extensively (including state)
• Supply methods for secure erase of sensitive data
47 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Security API: best practices
• Use TLS when secure channel is required
– or other suitable secure channel, don’t build one yourself
• Look at mature APIs for best practice examples
– Foursquare, Twitter, and Facebook...
• Don’t use weak cryptographic algorithms
– MD5, RC4... Old NSA saying: “Cryptanalysis always gets better. It never gets
worse.”
• Don’t hardcode particular algorithms into API
– and be prepared for change
(e.g., BlockCipher interface instead of AES)
48 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Formal verification of security API
• Harder than security protocol analysis
– security API typically consist of tens of functions called in any order
– security protocol only few messages executed in predefined sequence
• Initially applied only to small APIs, now getting better
– Very helpful as bug hunting tool
• Many interesting practical results
– real attacks against PKCS#11 devices
– PKCS#11 RSA’s token problem found
• Proofs of security within given model may be given
• http://www.lsv.ens-cachan.fr/~steel/security_APIs_FAQ.html
49 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
CODE ANNOTATIONS
54 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Motivation for making annotations
• More semantics of code available for checker
– Capture otherwise missed bugs
• More explicit documentation of code/API
– Ideally automatically testable
– Problems captured in compile time
• Compliancy requirements
– Driver signature by Microsoft, a must for 64b Windows
• …
55 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Microsoft SDL C/C++ static checker
• Problems not found by PREfast checker by default
• Achievable via source-code annotation language (SAL)
– check of return value
– argument must be not NULL
– string must be terminated
– length of data read / written into buffer
• Additional requirements are added to declaration of function, structure... via
(non-standard) keywords
• Validity of such requirements are checked by PREfast
– in pre-state (before fnc call) & in post-state (after fnc call)
56 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
SAL – examples (in and out buffer)
57 PV286 | Secure API, Automata-based programming
// read from buffer with size equal to length
int readData( void *buffer, int length );
int readData(_In_reads_(length) void *buffer, int length );
// writes specified amount (length) of data into buffer
int fillData( void *buffer, int *length );
int fillData(_Out_writes_all_(length) void *buffer, const int length );
www.crcs.cz/rsa @CRoCS_MUNI
SAL – basic terms
• Element is valid if contains explicitly assigned value
– Item of allocated array with unassigned value is invalid
• Valid in pre-condition (before function is called)
– Annotation typically starts with In_xxx
• Valid in post-condition (when function ends)
– Annotation typically starts with Out_xxx
• Number of specified bytes vs. items
– Default is number of items, bytes if _bytes_ added
– Number of elements valid
59 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
SAL functions basics
• Optional version of arguments
– argument might be NULL
– _In_opt, _Out_opt...
– function must perform check before use
• Otherwise PREFast will report error
60 PV286 | Secure API, Automata-based programming
https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-
studio-2015/code-quality/understanding-sal
www.crcs.cz/rsa @CRoCS_MUNI
SAL functions basics II.
• Pointer type annotations
• _Outptr_
– should not be NULL
– should be initialized
• _Outptr_opt_
– can be NULL, must be checked
61 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
• PREfast analysis
62 PV286 | Secure API, Automata-based programming
void salDemo(_In_ int* pInArray, _Outptr_ int** ppArray) {
}
int main(int argc, char* argv[]) {
int* pArray = NULL;
int* pArray2 = NULL;
if (strcmp(argv[1], "alloc") == 0) {pArray = new int[5];}
salDemo(pArray, &pArray2);
return 0;
}
test.cpp(34): warning : C6101: Returning uninitialized memory '*ppArray'. A successful
path through the function does not set the named _Out_ parameter.
test.cpp(49): warning : C6387: 'pArray' could be '0': this does not adhere to the
specification for the function 'salDemo'.
test.cpp(49): warning : C6001: Using uninitialized memory '*pArray'.
www.crcs.cz/rsa @CRoCS_MUNI
SAL annotations – much more
• Annotations of functions
– http://msdn.microsoft.com/en-us/library/hh916382.aspx
• Structs and classes can be also annotated
– http://msdn.microsoft.com/en-us/library/jj159528.aspx
• Locking behavior for concurrency can be annotated
– http://msdn.microsoft.com/en-us/library/hh916381.aspx
• Whole function can be annotated
– http://msdn.microsoft.com/en-us/library/jj159529.aspx
– _Must_inspect_result_
• Best practices
– http://msdn.microsoft.com/en-us/library/jj159525.aspx
• Some extra information: https://www.codeproject.com/Reference/879527/SAL-Function-Parameters-Annotations
63 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
SAL – examples (in and out buffer)
64 PV286 | Secure API, Automata-based programming
// read from buffer with size equal to length
int readData( void *buffer, int length );
int readData(_In_reads_(length) void *buffer, int length );
// writes specified amount (length) of data into buffer
int fillData( void *buffer, int *length );
int fillData(_Out_writes_all_(length) void *buffer, const int length );
// writes into buffer maxLength at max, but possibly less and modifies also length argument
int fillData( void *buffer, const int maxLength, int *length );
// Check if no more then maxLength and *length is written, also check range of length
int fillData( __Out_writes_to_( maxLength, *length ) void *buffer,
const int maxLength, _Out_range_(0, maxLength-1) int *length );
// read AND write from buffer
int readWriteData( void *buffer, int length );
int readWriteData(_Inout_updates_(length) void *buffer, int length );
www.crcs.cz/rsa @CRoCS_MUNI
SAL – examples (pointers, strings)
65 PV286 | Secure API, Automata-based programming
// pass argument by value foo pointer
int getInfo( struct thing *thingPtr );
// value is used as input and output => _Inout_
int getInfo( _Inout_ struct thing *thingPtr );
// pass C null-terminated strings
int writeString( const char *string );
// must be null terminated string > _In_z_
int writeString( _In_z_ const char *string );
www.crcs.cz/rsa @CRoCS_MUNI
Annotations for GCC/LLVM
• Deputy
– Not active anymore , last update 2006?
– http://ivy.cs.berkeley.edu/ivywiki/uploads/deputy-manual.html
• Clang Static Analyzer
– http://clang-analyzer.llvm.org/annotations.html
– Only few annotations
68 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Splint (is simple to use?)
• SAL version
• Splint version
69 PV286 | Secure API, Automata-based programming
void strcpy( _Out_z char *s1, _In_z const char *s2 );
void /*@alt char * @*/ strcpy(
/*@unique@*/ /*@out@*/ /*@returned@*/ char *s1, char *s2 )
/*@modifies *s1@*/ /*@requires maxSet( s1 ) >= maxRead( s2 ) @*/
/*@ensures maxRead( s1 ) == maxRead( s2 ) @*/;
www.crcs.cz/rsa @CRoCS_MUNI
SIDE-CHANNEL PROTECTED CRYPTO
LIBRARY API
EXCEPTIONS?
70 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
What changes for side-channel protected library?
• What is the scope of the side-channel protected crypto library?
– Crypto functions are there…
– What about copying, comparison, handling, wiping the keys,
– What about the initialization of the crypto-library? Memory protections perhaps? Is RNG
secure and only accessible to the library?
• What about a calling convention?
– Examples from the lecture
“Programming in the presence of side-channels / faults”
71 PV286 | Secure API, Automata-based programming
An example: https://github.com/sca-secure-library-sca25519/sca25519
www.crcs.cz/rsa @CRoCS_MUNI
AUTOMATA-BASED PROGRAMMING
72 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Automata-based style program
• Program (or its part) is though of as a model of finite state machine (FSM)
• Basic principles
– Automata state (explicit designation of FSM state)
– Automata step (transition between FSM states)
– Explicit state transition table (not all transitions are allowed)
• Practical implementation
– imperative implementation (switch over states)
– object-oriented implementation (encapsulates complexity)
• https://en.wikipedia.org/wiki/Automata-based_programming
73 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Example: SimpleSign applet
• Simple smart card applet for digital signature
– Operation 1: user must verify UserPIN before private key usage for signature is
allowed
– Operation 2: unblock of user pin allowed only after successful AdminPIN
verification
• Imperative solution:
– sensitive operation (Sign()) is wrapped into condition testing successful PIN
verification
– more conditions may be required (PIN and < 5 signatures)
– same signature operation may be called from different
contexts (SignHash(), ComputeHashAndSign())
76 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
SimpleSign – imperative solution
77 PV286 | Secure API, Automata-based programming
void SignData(APDU apdu) {
// ...
// INIT WITH PRIVATE KEY
if (m_userPIN.isValidated()) {
// INIT WITH PRIVATE KEY
m_sign.init(m_privateKey, Signature.MODE_SIGN);
// SIGN INCOMING BUFFER
signLen = m_sign.sign(apdubuf, ISO7816.OFFSET_CDATA,
(byte) dataLen, m_ramArray, (byte) 0);
// ... SEND OUTGOING BUFFER
}
else ISOException.throwIt(SW_SECURITY_STATUS_NOT_SATISFIED);
// ...
}
Test of required condition
Execution of sensitive operation
www.crcs.cz/rsa @CRoCS_MUNI
Example: states for smart card applet
78 PV286 | Secure API, Automata-based programming
digraph StateModel {
rankdir=LR;
size="6,6";
node [shape =ellipse color=green, style=filled];
{ rank=same; "STATE_UPLOADED";"STATE_INSTALLED";}
"STATE_INSTALLED";
"STATE_UPLOADED";
"STATE_UPLOADED" -> "STATE_INSTALLED" [label="install()"];
{ rank=same; "STATE_SELECTED";}
"STATE_SELECTED";
{ rank=same;"STATE_USER_AUTH";"STATE_ADMIN_AUTH";}
"STATE_USER_AUTH" ;
"STATE_ADMIN_AUTH" ;
"STATE_INSTALLED" -> "STATE_SELECTED" [label="select()" color="black" fontcolor="black"];
"STATE_SELECTED" -> "STATE_USER_AUTH" [label="VerifyUserPIN()" color="black" fontcolor="black"];
"STATE_SELECTED" -> "STATE_ADMIN_AUTH" [label="VerifyAdminPIN()" color="black" fontcolor="black"];
...
www.crcs.cz/rsa @CRoCS_MUNI
SimpleSign – automata-based solution
1. Mental model → .dot format (human readable)
– Graphviz visualization (visual inspection)
– source code generated for state check and transition check
– input for formal verification (state reachability)
2. Easy to extend by new states
– source code is generated again
3. More robust against programming mistakes and omissions
79 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Is transition allowed between given states?
• E.g., is allowed to change state directly from STATE_UPLOADED to
STATE_ADMIN_AUTH?
80 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Is function call allowed in present state?
• E.g., do not allow to use private key before UserPIN was verified
81 PV286 | Secure API, Automata-based programming
private void checkAllowedFunction(short requestedFunction) {
switch (requestedFunction) {
case FUNCTION_VerifyUserPIN:
if (m_currentState == STATE_SELECTED) break;
_OperationException(EXCEPTION_FUNCTIONEXECUTION_DENIED);
case FUNCTION_SignData:
if (m_currentState == STATE_USER_AUTH) break;
_OperationException(EXCEPTION_FUNCTIONEXECUTION_DENIED);
...
Sign data only when in
STATE_USER_AUTH
www.crcs.cz/rsa @CRoCS_MUNI
How to react on incorrect state transition
• Depends on particular application
– create error log entry
– throw exception
– terminate process
– ...
• Error message should not reveal too much
– side-channel attack based on error content
– Enable padding oracle attacks…
82 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
SimpleSign – additional functionality
• Programs almost always change in time
• If new functionality is required:
– E.g., signature allowed also after verification of AdminPIN
• Changes required in imperative solution:
– add additional condition before every Sign()
– when called from multiple places, developer may forgot to include conditions to all places
– not easy to realize, what conditions are required from existing code
• Changes required in automata-based solution:
– add new state transition (STATE_ADMIN_AUTH <-> SignData())
– generate new transition tables etc.
83 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
SUMMARY
84 PV286 | Secure API, Automata-based programming
www.crcs.cz/rsa @CRoCS_MUNI
Summary
• Designing good API is hard
– follow best practices, learn from well-established APIs
• Designing security API is even harder
• Automata-based programming
– make more robust state and transition validation
– good to combine with visualization and automatic code generation
85 PV286 | Secure API, Automata-based programming
Questions