Monday, February 24, 2014

Use Braces Even For Single Line Statement



On Feb. 21, 2014, Apple released security update for iOS that affected SSL/TLS connections. The impact is described as "An attacker with a privileged network position may capture or modify data in sessions protected by SSL/TLS." And the CVSS v2 Base Score is 6.8(AV:N/AC:M/Au:N/C:P/I:P/A:P). What's the problem with it?

Here is the Apple code:
static OSStatus
SSLVerifySignedServerKeyExchange(SSLContext *ctx, bool isRsa, SSLBuffer signedParams,
                                 uint8_t *signature, UInt16 signatureLen)
{
    ...

    if ((err = ReadyHash(&SSLHashSHA1, &hashCtx)) != 0)
        goto fail;
    if ((err = SSLHashSHA1.update(&hashCtx, &clientRandom)) != 0)
        goto fail;
    if ((err = SSLHashSHA1.update(&hashCtx, &serverRandom)) != 0)
        goto fail;
    if ((err = SSLHashSHA1.update(&hashCtx, &signedParams)) != 0)
        goto fail;
        goto fail;
    if ((err = SSLHashSHA1.final(&hashCtx, &hashOut)) != 0)
        goto fail;

    err = sslRawVerify(ctx,
                       ctx->peerPubKey,
                       dataToSign,    /* plaintext */
                       dataToSignLen,   /* plaintext length */
                       signature,
                       signatureLen);
    if(err) {
        sslErrorLog("SSLDecodeSignedServerKeyExchange: sslRawVerify "
                    "returned %d\n", (int)err);
        goto fail;
    }

fail:
    SSLFreeBuffer(&signedHashes);
    SSLFreeBuffer(&hashCtx);
    return err;

}

Did you note these lines?
    if ((err = SSLHashSHA1.update(&hashCtx, &signedParams)) != 0)
        goto fail;
        goto fail;

There are two "goto fail;" lines. The second one will always be executed and jump to "fail" marked block. Therefore, there is no chance to execute the sslRawVerify() method, which is essential to establish a safe SSL connection.  Here comes the security issue. Read here if you want to learn more detailed analysis of the issue.

The lesson I learned:
1. Be patient during code review. Even a minor typo can result in serious security issues.
2. Follow good code conversions. People make fewer mistakes in consistent environments.

Java suggests to always to use braces for "if" statements. C and C++ also have similar conversions, for example the brace policy in C and C++.
Note: if statements always use braces, {}. Avoid the following error-prone form:

if (condition) //AVOID! THIS OMITS THE BRACES {}!
    statement;
Rewrite the Apple code with the braces policy:
    if ((err = SSLHashSHA1.update(&hashCtx, &signedParams)) != 0) {
        goto fail;
    }
    goto fail;
With this reorg, it is easier to find the problem during code review. Or
    if ((err = SSLHashSHA1.update(&hashCtx, &signedParams)) != 0) {
        goto fail;
        goto fail;
    }
With this reorg, the problem disappears.

Good code conversions make a lot of fun!

Sunday, January 19, 2014

JEP 115: AES-GCM CipherSuites in JDK 8

Chengdu, China

RFC 5288 describes the use of AES in Galois Counter Mode (GCM) (AES-GCM) with various key exchange mechanisms as a cipher suite for TLS. AES-GCM is an authenticated encryption with associated data (AEAD) cipher (as defined in TLS 1.2) providing both confidentiality and data origin authentication.

Java SE had already defined the AES-GCM interfaces in Java SE 7.  In the coming Java SE 8, as an implementation of JEP 115, AES-GCM algorithms is implemented in SunJCE provider, and AES-GCM cipher suites are implemented in SunJSSE provider.

The following SSL/TLS AEAD/GCM cipher suites, in preference order, are enabled by default in SunJSSE provider for TLS version 1.2:
    TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 (RFC 5289)
    TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 (RFC 5289)
 
    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (RFC 5289)
    TLS_RSA_WITH_AES_256_GCM_SHA384 (RFC 5288)
    TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 (RFC 5289)
    TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 (RFC 5289)
    TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 (RFC 5288)
    TLS_DHE_DSS_WITH_AES_256_GCM_SHA384 (RFC 5288)
 
    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (RFC 5289)
    TLS_RSA_WITH_AES_128_GCM_SHA256 (RFC 5288)
    TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 (RFC 5289)
    TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 (RFC 5289)
    TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 (RFC 5288)
    TLS_DHE_DSS_WITH_AES_128_GCM_SHA256 (RFC 5288)

The following SSL/TLS AEAD/GCM cipher suites are supported but not enabled by default in SunJSSE provider for TLS version 1.2:
    TLS_DH_anon_WITH_AES_256_GCM_SHA384 (RFC 5288)
    TLS_DH_anon_WITH_AES_128_GCM_SHA256 (RFC 5288)

The following SSL/TLS AEAD/GCM cipher suites are defined, but not implemented or supported by SunJSSE provider:
    TLS_DH_RSA_WITH_AES_128_GCM_SHA256 (RFC 5288)
    TLS_DH_RSA_WITH_AES_256_GCM_SHA384 (RFC 5288)
 
    TLS_DH_DSS_WITH_AES_128_GCM_SHA256 (RFC 5288)
    TLS_DH_DSS_WITH_AES_256_GCM_SHA384 (RFC 5288)

For better compatibility and interoperability, in JDK 8, it is decided to decrease the preference priority of cipher suites in GCM mode for a while before GCM technologies mature in the industry. New developments in TLS security have occurred recently, the industry is moving towards TLS 1.1/1.2 and the use of GCM-based cipher suites. The preference priority of GCM-based cipher suites by default may be increased in JDK 9, or a JDK 8 update release in the future.

Enojoy this new feature!

Thursday, January 2, 2014

JEP 114: TLS SNI Extension - Virtual Servers Dispatcher


The implementation of JEP 114 (TLS Server Name Indication (SNI) Extension) had integrated into JDK 8 at October, 2012. In the previous blog entries, we talked about the behavior changes in JSSE, and a few typical user cases. Let's look at a special user case, how to design a virtual server dispatcher in Java. Please refer to javax.net.ssl package of JDK 8 APIs for the detailed specification.


Prepare the ClientHello Parser


Applications need to implementation their own APIs to parser the client hello message from a plaintext socket. Suppose that an application design the following API to do the work, SSLCapabilities and SSLExplorer.

SSLCapabilities is defined to show the SSL/TLS security capabilities during handshaking, SSLCapabilities can be retrieved by exploring the network data of an SSL/TLS connection via SSLExplorer.explore(ByteBuffer).

/**
 * Encapsulates the security capabilities
 * of an SSL/TLS connection.
 * 
 * The security capabilities are the list
 * ciphersuites to be accepted in an SSL/TLS
 * handshake, the record version, the hello
 * version, and server name indication, etc.,
 * of an SSL/TLS connection.
 * 
 * {@code SSLCapabilities} can be retrieved by exploring the network
 * data of an SSL/TLS connection via {@link SSLExplorer#explore(ByteBuffer)}
 * or {@link SSLExplorer#explore(byte[], int, int)}.
 *
 * @see SSLExplorer
 */
public abstract class SSLCapabilities {

    /**
     * Returns the record version of an SSL/TLS connection
     *
     * @return a non-null record version
     */
    public abstract String getRecordVersion();

    /**
     * Returns the hello version of an SSL/TLS connection
     *
     * @return a non-null hello version
     */
    public abstract String getHelloVersion();

    /**
     * Returns a {@code List} containing all
     * {@link SNIServerName}s of the server name indication.
     *
     * @return a non-null immutable list of {@link SNIServerName}s
     *         of the server name indication parameter, may be empty
     *         if no server name indication.
     *
     * @see SNIServerName
     */
    public abstract List<SNIServerName> getServerNames();
}
SSLExplorer is defined to explore the initial ClientHello message from TLS Client. But it does not kick off handshaking, or consume network data. The SSLExplorer.explore() method parses the ClientHello message, and retrieve the security parameters from ClientHello message into SSLCapabilities.

This method must be called before handshaking occurs on any TLS connections.
/**
 * Instances of this class acts as an explorer of the network data of an
 * SSL/TLS connection.
 */
public final class SSLExplorer {

    /**
     * The header size of TLS/SSL records.
     * <P>
     * The value of this constant is {@value}.
     */
    public final static int RECORD_HEADER_SIZE = 0x05;

    /**
     * Returns the required size in byte from byte buffer to explore an
     * SSL/TLS connection.
     * <P>
     * This method tries to parse as few bytes as possible from
     * {@code source} byte buffer to get the length of an
     * SSL/TLS record.
     *
     * @param  source
     *         a {@code ByteBuffer} containing
     *         inbound or outbound network data for an SSL/TLS connection.
     *
     * @throws BufferUnderflowException if less than {@code RECORD_HEADER_SIZE}
     *         bytes remaining in {@code source}
     */
    public final static int getRequiredSize(ByteBuffer source);

    /**
     * Returns the required size in byte from byte array to explore an
     * SSL/TLS connection.
     * <P>
     * This method tries to parse as few bytes as possible from
     * {@code source} byte array to get the length of an
     * SSL/TLS record.
     *
     * @param  source
     *         a byte array containing inbound or outbound network data for
     *         an SSL/TLS connection.
     * @param  offset
     *         the start offset in array {@code source} at which the
     *         network data is read from.
     * @param  length
     *         the maximum number of bytes to read.
     *
     * @throws BufferUnderflowException if less than {@code RECORD_HEADER_SIZE}
     *         bytes remaining in {@code source}
     */
    public final static int getRequiredSize(byte[] source,
            int offset, int lenght) throws IOException;

    /**
     * Launch and explore the security capabilities from byte buffer.
     * <P>
     * This method tries to parse as few records as possible from
     * {@code source} byte buffer to get the {@code SSLCapabilities}
     * of an SSL/TLS connection.
     * <P>
     * Please NOTE that this method must be called before any handshaking
     * occurs.  The behavior of this method is not defined in this release
     * if the handshake has begun, or has completed.
     * <P>
     * This method accesses the {@code source} parameter in read-only
     * mode, and does not update the buffer's properties such as capacity,
     * limit, position, and mark values.
     *
     * @param  source
     *         a {@code ByteBuffer} containing
     *         inbound or outbound network data for an SSL/TLS connection.
     *
     * @throws IOException on network data error
     * @throws BufferUnderflowException if no enough source bytes available
     *         to make a complete exploration.
     *
     * @return the explored {@code SSLCapabilities} of the SSL/TLS
     *         connection
     */
    public final static SSLCapabilities explore(ByteBuffer source)
            throws IOException;

    /**
     * Launch and explore the security capabilities from byte array.
     * <P>
     * Please NOTE that this method must be called before any handshaking
     * occurs.  The behavior of this method is not defined in this release
     * if the handshake has begun, or has completed.
     * <P>
     * Please NOTE that this method must be called before any handshaking
     * occurs.  Once handshake has begun, or has completed, the security
     * capabilities can not and should not be launched with this method.
     *
     * @param  source
     *         a byte array containing inbound or outbound network data for
     *         an SSL/TLS connection.
     * @param  offset
     *         the start offset in array {@code source} at which the
     *         network data is read from.
     * @param  length
     *         the maximum number of bytes to read.
     *
     * @throws IOException on network data error
     * @throws BufferUnderflowException if no enough source bytes available
     *         to make a complete exploration.
     * @return the explored {@code SSLCapabilities} of the SSL/TLS
     *         connection
     *
     * @see #explore(ByteBuffer)
     */
    public final static SSLCapabilities explore(byte[] source,
            int offset, int length) throws IOException;
}

Please note that the above two classes is not part of JDK. It is used to illustrate how to use JSSE specification of server name indication.

Socket Based Scenarios of a virtual servers dispatcher

Step 1: register server name handler in the dispatcher server
At the step, the application may create different SSLContext for different server name indication, or link a certain server name indication to a specified virtual machine or distributed system.

For example, for server name of "www.example.com", the registered server name handler may be for a local virtual hosting web service. The local virtual hosting web service will use a specified SSL context. For server name of "www.invalid.com", the registered server name handler may be for a virtual machine hosting on "10.0.0.36". The handler may map proxy this connection to the virtual machine.

Step 2: create a server socket, and accept a new connection
    ServerSocket serverSocket = new ServerSocket(serverPort);
    Socket socket = serverSocket.accept();
Step 3: read and buffer bytes from the socket input stream, and explore the buffered bytes
    InputStream ins = socket.getInputStream();

    byte[] buffer = new byte[0xFF];
    int position = 0;
    SSLCapabilities capabilities = null;

    // Read the header of TLS record
    while (position < SSLExplorer.RECORD_HEADER_SIZE) {
        int count = SSLExplorer.RECORD_HEADER_SIZE - position;
        int n = ins.read(buffer, position, count);
        if (n < 0) {
            throw new Exception("unexpected end of stream!");
        }
        position += n;
    }

    // Get the required size to exlpore the SSL capabilities
    int recordLength = SSLExplorer.getRequiredSize(buffer, 0, position);
    if (buffer.length < recordLength) {
        buffer = Arrays.copyOf(buffer, recordLength);
    }

    while (position < recordLength) {
        int count = recordLength - position;
        int n = ins.read(buffer, position, count);
        if (n < 0) {
            throw new Exception("unexpected end of stream!");
        }
        position += n;
    }

    // Explore
    capabilities = SSLExplorer.explore(buffer, 0, recordLength);;
    if (capabilities != null) {
        System.out.println("Record version: " +
                capabilities.getRecordVersion());
        System.out.println("Hello version: " +
                capabilities.getHelloVersion());
    }
Step 4: get the requested server name from the SSLCapabilities
    List<SNIServerName> serverNames = capabilities.getServerNames();
Step 5: looking for the registered server name handler for this server name indication
Typically, there are two types of handler. The first one is that the service of the hostname is resident in a virtual machine or another distributed separated box. In this case, the application need to forward the connection to the destination. The application requires to read and write the raw internet data, rather than the SSL application from the socket stream.
    Socket destinationSocket = new Socket(serverName, 443);

    // forward buffered bytes and network data from the current socket to
    // destinationSocket, proxy-like coding

The 2nd one is that the service of the server name is resident in the same process. And the service is able to use the socket directly. In this case, the application will simply set the SSLSocket instance to the server.
    SSLContext serviceContext = ...
                    // get service context from registered handler
                    // or create the context on the fly
    SSLSocketFactory serviceSocketFac =
                    serviceContext.getSSLSocketFactory();

    ByteArrayInputStream bais =
        new ByteArrayInputStream(buffer, 0, position);
                           // wrap the buffered bytes
    SSLSocket serviceSocket =
        (SSLSocket)serviceSocketFac.createSocket(socket, bais, true);

    // Now the service can use the serviceSocket as normal.

SSLEngine Based Scenarios of a virtual servers dispatcher


Similar to the socket based scenatios. There is a little different in the 2nd case in step 5.
The 2nd case is that the service of the hostname is resident in the same process. And hostname service is able to use the engine directly. In this case, the application will simply feed the net data to the new engine.
    SSLContext serviceContext =
                    // get service context from registered handler
                    // or create the context on the fly
    SSLEngine serviceEngine = serviceContext.createSSLEngine();

    // Now the service can use the buffered bytes and other byte
    // buffer as normal.
The scenarios for the cases that bridge SSLSocket source to SSLEngine destination, or SSLEngine source to SSLSocket destination are pretty similar to the above two scenarios.

No server name indication extension


It's often that there is no server name indication extension in a ClientHello message. There is no way to select a proper service according to server name indication.

For such cases, the application may want to specify a default service. When there is no server name indication extension, the connection will be delegated to the default service.

Failover


Please NOTE that the explore of the security capabilities should neither consume nor produce network or application data. So what about if the explore fails?

SSLExploree.explore() should not checking the validity of SSL/TLS contents. However, it requires that the record format complies to SSL/TLS specification, and handshaking has not started. SSLExploree.explore() may throw IOException for such bad cases.

SSLExploree.explore() cannot produce network data. And SSL/TLS protocols requires to reply with proper alert messages. It is not recommended to close the raw socket out of band of SSL/TLS protocols. Failover is recommended to handle exception thrown by SSLExplorer.explore().

The application need to define a failover SSLContext, it is not used to negotiate any real SSL/TLS connection. Instead, it is used to close the SSL/TLS connection with proper alert message. So the initialization of the context can be very basic.
    byte[] buffer = ...       // buffered network data
    boolean failed = true;    // SSLExploree.explore() throws an exception

    // off course, the above explore failed. Faile to failure handler
    SSLContext context = SSLContext.getInstance("TLS");
                                        // the failover SSLContext
    context.init(null, null, null);
    SSLSocketFactory sslsf = context.getSocketFactory();
    ByteArrayInputStream bais =
            new ByteArrayInputStream(buffer, 0, position);
    SSLSocket sslSocket = (SSLSocket)sslsf.createSocket(socket, bais, true);

    SNIMatcher matcher = new DenialSNIMatcher(); // see case 2.2.1
    Collection<SNIMatcher> matchers = new ArrayList<>(1);
    matchers.add(matcher);
    SSLParameters params = sslSocket.getSSLParameters();
    params.setSNIMatchers(matchers);    // no recognizable server name
    sslSocket.setSSLParameters(params);

    try {
        InputStream sslIS = sslSocket.getInputStream();
        sslIS.read();
    } catch (Exception e) {
        System.out.println("server exception " + e);
    } finally {
        sslSocket.close();
    }

To put it together, as SSLExplore.explore() may fail with exception, the application MUST handle the exception with a failover solution, such as failover SSLContext. An application may also need to handle ClientHello message without server name indication extension, the application MUST specify a default service for non-server-name-indication handshaking. And an application may be expected to handle server name indication properly, the application MUST specify the target service for a particular server name indication.

Hope it helps!