Just a second...

Connecting securely

A Diffusion™ client can make secure connections to the Diffusion server over Transport Layer Security (TLS) . All supported transports can connect securely.

To connect securely do one of the following:
  • In JavaScript® , set the secure parameter to true
  • In Android™ and Java™ , when specifying parameters individually, pass true to the secureTransport() method.
  • If using a URL to connect, insert an "s" after the transport value in the url parameter. For example, wss://diffusion.example.com:443.

Configure the SSL context or behavior

A secure connection to the Diffusion server uses Secure Sockets Layer (SSL) to secure the communication.

When connecting over SSL, you might need to configure SSL.
  • In JavaScript , the SSL context is provided by the browser.
  • In Android , Java , and .NET, you can provide an SSL context when creating the session.
  • In Apple® , you can use the sslOptions property to provide a dictionary of values that specify the SSL behavior. For more information, see the CFStreamConstants documentation.
.NET
var session = Diffusion.Sessions
                   .Principal("principal")
                   .CertificateValidation((cert, chain, errors) => CertificateValidationResult.ACCEPT)
                   .Open("url");
Java and Android
final SSLContext context = SSLContext.getInstance("TLS");

final Session session = Diffusion
    .sessions()
    .sslContext(context)
    .open("wss://localhost:443");

If no SSL context or behavior is specified, the client uses the default context or configuration.

Validating server-side certificates

Diffusion clients that connect over a secure transport use certificates to validate the security of their connection to the Diffusion server . These certificates are validated against any certificates in the set trusted by the framework, runtime, or platform that the client library runs on.

If the client does not trust the certificate provided by a CA, you can configure the client to add certificates to its trust store:

You can also write a trust manager that explicitly allows the CA's certificates.

Disabling certificate validation on the client

You can disable client validation of the server-side certificates.

Note: We do not recommend disabling this validation on your production clients. However, it can be useful for testing.

Certificates can only be strictly validated if they have been issue by an appropriate Certificate Authority (CA) and if the CA's certificates are also known to your client.

Since certificates are specific to the domain name that the server is deployed on, Diffusion ships with demo certificates and these cannot be strictly validated. To test against a server with demo certificates, disable client-side SSL certificate validation as shown in the following examples:

Java and Android
final TrustManager tm = new X509TrustManager() {
    @Override
    public void checkClientTrusted(X509Certificate[] chain,
        String authType) throws CertificateException { }

    @Override
    public void checkServerTrusted(X509Certificate[] chain,
        String authType) throws CertificateException { }

    @Override
    public X509Certificate[] getAcceptedIssuers() {
        return new X509Certificate[0];
    }
};

final SSLContext context = SSLContext.getInstance("TLS");
context.init(null, new TrustManager[] { tm }, null);

final Session session = Diffusion
    .sessions()
    .sslContext(context)
    .open("wss://localhost:443");
C
// the environent variable can be set this way in the code
// or it can be set explicitly in the environment
putenv("DIFFUSION_TRUST_SELF_SIGNED_CERTS=1");

SESSION_T *session = session_create(url, principal, credentials, NULL, NULL, NULL);
Apple
let configuration = PTDiffusionMutableSessionConfiguration()
configuration.sslOptions = [kCFStreamSSLValidatesCertificateChain: kCFBooleanFalse]

// Use the configuration to open a new session...
PTDiffusionSession.open(with: URL(string: "wss://TestServer")!,
                        configuration: configuration) { (session, error) in

    // Check error is `nil`, then use session as required.
    // Ensure to maintain a strong reference to the session beyond the lifetime
    // of this callback, for example by assigning it to an instance variable.

    if (session == nil) {
        print("Failed to open session: %@", error!.localizedDescription)
        return
    }

    // At this point we now have a connected session.
    print("Connected.")
}