Page History

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

...