SSL/TLS API Reference

This section provides information about the Application Programming Interfaces (APIs) for Secure Sockets Layer (SSL) and Transport Layer Security (TLS) on Windows. These APIs enable secure communication over networks by providing encryption and authentication.

Overview

SSL/TLS is a cryptographic protocol designed to provide communications security over a computer network. It is widely used for securing HTTP (HTTPS) traffic, but also for other protocols like FTP, SMTP, and VPNs. Windows implements SSL/TLS primarily through the Security Support Provider Interface (SSPI) and the Cryptography API: Next Generation (CNG).

Key APIs and Concepts

Security Support Provider Interface (SSPI)

SSPI is a Windows API that provides a common interface for various security protocols, including SSL/TLS (via Schannel). It allows applications to authenticate themselves and to establish secure connections without needing to know the specifics of the underlying security package.

InitializeSecurityContext: Initiates a security context for a client application.
AcceptSecurityContext: Accepts a security context for a server application.
EncryptMessage: Encrypts a message.
DecryptMessage: Decrypts a message.
QuerySecurityContextToken: Retrieves the handle to the token associated with a security context.

See also: Schannel Security Package

Cryptography API: Next Generation (CNG)

CNG is a more modern and flexible cryptography framework introduced in Windows Vista. It provides support for algorithms, key storage, and digital signatures, and can be used for implementing SSL/TLS functionalities.

NCryptOpenAlgorithmGroup, NCryptOpenKey: For managing cryptographic algorithms and keys.
NCryptSignHash, NCryptVerifySignature: For signing and verifying data.
BCryptEncrypt, BCryptDecrypt: For symmetric encryption and decryption.

WinINet and WinHTTP

Higher-level APIs like WinINet and WinHTTP abstract away much of the complexity of SSL/TLS for common internet protocols like HTTPS. They automatically handle the SSL/TLS handshake when connecting to secure servers.

When using InternetOpenUrl or HttpOpenRequest with an https:// URL, these APIs will initiate an SSL/TLS session.
Applications can use SSPI or CNG for more granular control or custom SSL/TLS implementations.

Common Tasks

Establishing a Secure Client Connection: Use InitializeSecurityContext after a successful socket connection is established.
Accepting a Secure Server Connection: Use AcceptSecurityContext on the server side after a socket connection is established.
Managing Certificates: Applications often need to load, validate, and present X.509 certificates. This can be done using Cryptography API functions.
Configuring TLS Versions and Ciphers: Through system settings or specific API configurations, developers can influence which TLS versions and cipher suites are preferred or allowed.

Best Practices

Always use the latest supported TLS version (e.g., TLS 1.2 or TLS 1.3) for maximum security.
Validate server certificates thoroughly to prevent Man-in-the-Middle attacks.
Use strong, modern cipher suites.
Keep your SSL/TLS libraries and operating system updated.

Windows API Reference