APIS should have security options enabled by default– for example, having best practice cipher suites enabled by default (something that changes over time) while disabling out-of-favor cipher suites by default. When interface stability is also a design requirement, an interface can meet both goals by providing off-by-default options that produce stable behavior, such as TLS_ENABLE_Y2015_BEST_PRACTICE_CIPHERS_ONLY.
Noncompliant Code Example
If the caller of this API in this noncompliant example doesn't understand what the options mean, they will pass 0 or TLS_DEFAULT_OPTIONS and get a connection vulnerable to man-in-the-middle attacks and using old versions of TLS.
int tls_connect_by_name(const char *host, int port, int option_bitmask); #define TLS_DEFAULT_OPTIONS 0 #define TLS_VALIDATE_HOST 0x0001 #define TLS_DISABLE_V1_0 0x0002 #define TLS_DISABLE_V1_1 0x0004
Compliant Solution
If the caller of this API doesn't understand the options and passes 0 or TLS_DEFAULT_OPTIONS they will get certificate validation with only the current version of TLS enabled.
int tls_connect_by_name(const char *host, int port, int option_bitmask); #define TLS_DEFAULT_OPTIONS 0 #define TLS_DISABLE_HOST_VALIDATION 0x0001 // use rarely, subject to man-in-the-middle attack #define TLS_ENABLE_V1_0 0x0002 #define TLS_ENABLE_V1_1 0x0004
Related Guidelines
Bibliography
