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.
var session = Diffusion.Sessions.SslContext(ssl_context).Open( "secure_url" );
Java and Android
Session session = Diffusion.sessions().sslContext(ssl_context).open("secure_url");

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
TrustManager tm = new X509TrustManager() {
    public void checkClientTrusted(X509Certificate[] chain, String authType) throws CertificateException {

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

    public X509Certificate[] getAcceptedIssuers()
         return new X509Certificate[0];

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

Session session = Diffusion.sessions().sslContext(context).open("secure_url");
// the environent variable can be set this way in the code
// or it can be set explicitly in the environment

SESSION_T *session = session_create(url, principal, credentials, NULL, NULL, NULL);
//  Copyright (C) 2021 Push Technology Ltd.
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//  http://www.apache.org/licenses/LICENSE-2.0
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.

import Foundation
import Diffusion

class ConnectingSecurely {

    func connect_disable_certificate_validation() {
        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)

            // At this point we now have a connected session.