Service Reference

This document describes all of the elements and properties you can use to configure Kaazing WebSocket Gateway services.

Overview

You can use the optional service element to configure one or more services running on Kaazing WebSocket Gateway.

Structure

The Gateway configuration file (gateway-config.xml or gateway-config.xml) defines the service configuration element and its subordinate elements and properties that are contained in the top-level gateway-config element:

service

Configure all Gateways with one or more services for which you want to provide reverse connectivity. Each service element contains an accept URI on which the service listens on for client connections and a connect. Configuration is the same for all services.

Each service can contain any of the subordinate elements listed in the following table.

Note: Subordinate elements must be specified in the order shown in the following table.
Subordinate Element Description
accept

The URLs on which the service accepts connections.

connect

The URL of a back-end service to which the proxy service (for example, jms.proxy) or broadcast service connects.

balance The URI that is balanced by a balancer service. See balancer service for details.
notify

The notification-specific URI of the Apple Push Notification Service (APNs) that is going to make APNs notifications available for this service. See the notify element for details.

type

The type of service. One of the following:

properties The service type-specific properties.
accept-options Options for the accept element (see accept-options).
connect-options

Options for the connect element (see connect-options).

notify-options Options for the notify element (see notify-options).
realm-name The name of the security realm used for authorization. If you do not include a realm name, then authentication and authorization are not enforced for the service.
authorization-constraint

The user roles that are authorized to access the service (see authorization-constraint).

mime-mapping Mappings of file extensions to MIME types. Each mime-mapping entry defines the HTTP Content-Type header value to be returned when a client or browser requests a file that ends with the specified extension (see mime-mapping).
cross-site-constraint The cross-origin sites (and their methods and custom headers) allowed to access the service. (see cross-site-constraint).

Supported URL Schemes:

When specifying URLs for the accept or connect elements, you can use tcp://{hostname}:{port} to make a basic TCP connection, or specify any of the supported protocol schemes:

  • ws
  • wss
  • http
  • https
  • ssl
  • tcp
  • udp (not available for the proxy service)

accept

Required? Yes; Occurs: At least once.

The URLs on which the service accepts connections (see "Supported URL schemes").

Example

<service>
  <accept>ws://balancer.example.com:8081/echo</accept>
.
.
.
</service>

Notes

  • There is no default value for the accept element. You must configure it and specify the URI on which the service accepts connections.
  • The Gateway is configured by default to provide services only to users on the same machine (localhost) as that on which it is running. To customize the Gateway for your environment, choose the appropriate type of service (for example, balancer, broadcast, directory, and so on) to signal the Gateway to accept incoming connections from clients using any supported URL scheme.
  • Supported URL Schemes: When specifying URLs for the accept or connect elements, you can use tcp://{hostname}:{port} to make a basic TCP connection, or specify any of the supported protocol schemes:

    • ws
    • wss
    • http
    • https
    • ssl
    • tcp
    • udp (not available for the proxy service)
  • Normally an accept element in a service definition instructs the Gateway to listen on the port for incoming connections. However, in an Enterprise Shield™ topology, instead of listening, the internal (trusted) Gateway initiates a reverse connection to the DMZ Gateway. The reverse connection is achieved by configuring the internal Gateway service to act as a SOCKS client, sending remote bind requests to the DMZ Gateway. This tells the remote side to listen for connections on a particular host and port. That way, when clients' connection requests come in to the DMZ Gateway, the Gateway matches them up with SOCKS bind requests.

connect

Required? Yes; Occurs: At least once.

The URL of a back-end service to which the proxy service (for example, jms.proxy) or broadcast service connects (see "Supported URL schemes").

Example

<connect>tcp://192.0.2.11:5943</connect>

Notes

  • There is no default value for the connect element. You must configure it and specify the URI on which the service makes a connection to the JMS-compliant message broker.
  • The Gateway is configured by default to provide services only to users on the same machine (localhost) as that on which it is running. To customize the Gateway for your environment, choose the appropriate type of service (for example, balancer, broadcast, echo, and so on) to signal the Gateway to accept incoming connections from clients using any supported URL scheme.
  • Supported URL Schemes: When specifying URLs for the accept or connect elements, you can use tcp://{hostname}:{port} to make a basic TCP connection, or specify any of the supported protocol schemes:

    • ws
    • wss
    • http
    • https
    • ssl
    • tcp
    • udp (not available for the proxy service)
  • Normally a connect element in a service definition instructs the DMZ Gateway to establish an outgoing physical network connection to the specified URI on a remote host machine for each client as it connects to the service. However, with a reverse connection, instead of connecting, the DMZ Gateway listens for an incoming bind request from the Enterprise Gateway. If a bind request matching the specified connect URI is received, then a reverse connection is formed. The reverse connection is achieved by configuring the DMZ Gateway service to act as a SOCKS server, receiving remote bind requests from the Enterprise Gateway. For example: tcp://127.0.0.1:3102. In a cluster, you configure a UDP connect URI that cluster members use to join the cluster. For example: udp://224.2.2.44:44444
  • .

balance

Required? Optional; Occurs: one or more.

A URI that matches the accept URI in a balancer service. The balance element is added to a service in order for that service to be load balanced between cluster members.

Example

The following example shows a Gateway with a balancer service and an Echo service that contains a balance element. Note that the accept URI in the balancer service matches the balance URI in the Echo service.

Balancer Service

<service>
  <accept>ws://balancer.example.com:8081/echo</accept>

  <type>balancer</type>

  <accept-options>
      <ws.bind>192.168.2.10:8081</ws.bind>
  </accept-options>

</service>

Gateway Service Participating in Load Balancing

<service>
  <accept>ws://node1.example.com:8081/echo</accept>
  <balance>ws://balancer.example.com:8081/echo</balance>

  <type>echo</type>

  <cross-site-constraint>
    <allow-origin>http://directory.example.com:8080</allow-origin>
  </cross-site-constraint>
</service>

Notes

  • There is no default value for the balance element. If you configure it, then you must specify a URI for its value.
  • The balance and accept element URIs in a service must use the same port number and path. The hostnames in the URIs may be different.
  • See the balancer service to configure the balancer.
  • See Set Up Kaazing WebSocket Gateway as a Load Balancer for a complete load balancing description and example.

notify

Required? Optional; Occurs: one or more.

Use the notify element to make Apple Push Notification Service (APNs) notifications available for the service. This element specifies the notification-specific URI that contains the bundle ID and an optional development (or sandbox) indicator. The Gateway supports APNs push notifications for APNs-enabled clients that are connected to a jms service (possibly through a jms.proxy service).

Note: You must specify the bundle ID for your app in lowercase letters. For more information, see Setting the Bundle ID.

For example, you might configure the URI <notify>apns://com.example.myapp</notify> to indicate that the iOS application can use the APNs notifying feature (while other iOS applications, with different bundle IDs, cannot). Because the bundle ID is the same for both the sandbox and production environments, you might have two different APNs certificates for the same bundle ID: one sandbox certificate and one production certificate. To tell them apart in the Gateway configuration, the URIs would be slightly different. For example:

  • For the sandbox environment: <notify>apns://com.example.myapp/DEVELOPMENT</notify>
  • For the production environment: <notify>apns://com.example.myapp/PRODUCTION</notify>
Note: To configure the Gateway and iOS applications built using the Kaazing WebSocket Gateway Objective-C client library to use APNs for offline notifications, see the step-by-step instructions in Checklist: Deploy APNs with Kaazing WebSocket Gateway.

Example Configuration for the notify Element

The following examples show complete notify elements including a service for the production and Apple sandbox environments. The examples also demonstrate the use of multiple notify-options and show a security element that specifies the keystore.db keystore. Including this in the configuration is essential for communication with the Apple servers because the keystore has the APNs certificate imported into it (this is imported using the keytool command
-importcert, as described in Checklist: Deploy APNs with Kaazing WebSocket Gateway).

Example Configuration for an Apple Production Environment

<service>
  <accept>ws://${gateway.hostname}:8000/proxy</accept>

  <!-- Use the APNs scheme (notification provider), 
    and allow the application com.example.myapp to 
    to subscribe and receive notifications via APNs --> 
  <notify>apns://com.example.myapp/PRODUCTION</notify>

  <type>jms</type>

  <properties>
    <connection.factory.name>
      Connection Factory
    </connection.factory.name>
    <context.lookup.topic.format>
      dynamicTopics/%s
    </context.lookup.topic.format>
    <context.lookup.queue.format>
      dynamicQueues/%s
    </context.lookup.queue.format>
    <env.java.naming.factory.initial>
      org.apache.activemq.jndi.ActiveMQInitialContextFactory
    </env.java.naming.factory.initial>
    <env.java.naming.provider.url>
      tcp://localhost:61616
    </env.java.naming.provider.url>
  </properties>
  
    <!-- These DNS names/ports point to the production Apple servers. This means
    JMS clients that connect to this service should have production device tokens.-->
    <!-- Use ssl:// - Apple requires TLS/SSL to communicate with their services -->
  <notify-options>
    <apns.notify.transport>ssl://gateway.push.apple.com:2195</apns.notify.transport>
    <apns.feedback.transport>ssl://feedback.push.apple.com:2196</apns.feedback.transport>
  </notify-options>

  <realm-name>demo</realm-name>

  <cross-site-constraint>
    <allow-origin>http://example.com:8080</allow-origin>
  </cross-site-constraint>
</service>
    .
    .
    .
<security>
  <keystore>
    <type>JCEKS</type>
    <file>keystore.db</file>
    <password-file>keystore.pw</password-file>
  </keystore>
  <truststore>
    <type>JCEKS</type>
    <file>truststore-JCEKS.db</file>
  </truststore>
</security>
  .
  .
  .

Example Configuration for an Apple Sandbox Development Environment

  .
  .
  .
<service>
  <accept>ws://example.com:8080/jms</accept>
  
    <!-- Use the APNs scheme (notification provider) and allow  
    the application com.example.myapp/DEVELOPMENT to  
    subscribe and receive notifications via APNs -->
  <notify>apns://com.example.myapp/DEVELOPMENT</notify>

  <type>jms</type>

  <properties>
    <connection.factory.name>
      Connection Factory
    </connection.factory.name>
    <context.lookup.topic.format>
      dynamicTopics/%s
    </context.lookup.topic.format>
    <context.lookup.queue.format>
      dynamicQueues/%s
    </context.lookup.queue.format>
    <env.java.naming.factory.initial>
      org.apache.activemq.jndi.ActiveMQInitialContextFactory
    </env.java.naming.factory.initial>
    <env.java.naming.provider.url>
      tcp://localhost:61616
    </env.java.naming.provider.url>
  </properties>
  
    <!-- These DNS names/ports point to the sandbox Apple servers. Thus, the JMS
    clients that connect to this service should have development device tokens.-->
    <!-- Must use ssl:// - Apple requires TLS/SSL to communicate with their services -->
  <notify-options>
    <apns.notify.transport>
      ssl://gateway.sandbox.push.apple.com:2195
    </apns.notify.transport>
    <apns.feedback.transport>
      ssl://feedback.sandbox.push.apple.com:2196
    </apns.feedback.transport>
  </notify-options>

  <realm-name>demo</realm-name>

  <cross-site-constraint> 
    <allow-origin>http://example.com:8080</allow-origin> 
  </cross-site-constraint>
</service>
.
.
.
<security>
  <keystore>
    <type>JCEKS</type>
    <file>keystore.db</file>
    <password-file>keystore.pw</password-file>
  </keystore>
  <truststore>
    <type>JCEKS</type>
    <file>truststore-JCEKS.db</file>
  </truststore>
</security>
  .
  .
  .

Notes

  • There is no default value for the notify element. If you configure the notify element, then you must specify the URI of the Apple Push Notification Service (APNs) as its value.
  • Configure the notify element after any accept, connect, and balance elements, and before the type element.
  • Configure the notify-options after any properties, accept-options, and connect-options elements, and before any realm-name element.
  • Configure the security element for all APNs configurations, including both the production and development environments.
  • In an Enterprise Shield™ topology, configure notify and notify-options on the jms service on an internal Gateway that is connected directly to the JMS-compliant message broker.
  • Do not configure a single Gateway instance to have a service connecting to the sandbox (development) Apple servers and a service connecting to the production Apple servers if those services will use the same bundle ID in their notify elements. Instead, you must configure and launch a separate Gateway instance for each service that uses the same bundle ID.

    For example, because the production and sandbox configurations shown in Example Configuration for the notify Element use the bundle ID com.example.myapp, each service must be configured and started as a separate Gateway instance. Otherwise, an APNs notification intended for the development environment might be sent on the connection to the production environment, or vice versa. This means, in turn, that APNs client applications may not receive the APNs notifications as intended. Note that this could occur even though the sandbox Apple server connection includes /DEVELOPMENT (com.example.myapp/DEVELOPMENT) on its URI.

  • For APNs notifications, if the sandbox and the production environments both use the same bundle ID (such as com.example.myapp), then you must configure two Gateway instances: one for the sandbox environment and one for the production environment. When establishing connections to Apple's development (and production) environment, both the bundle ID and the environment are used.

  • If the client already has an active or open connection to the Gateway, then APNs will not be used.
  • Considerations regarding certificates:
    • Connecting to the APNs requires a certificate; each certificate is tied to a specific application (by iOS application ID). Thus, you must configure multiple APNs certificates for a given service.
    • The sandbox and the production environments each has its own set of certificates. Configuration of APNs certificates, for a given service, is therefore comprised of separate sets of certificates per environment, and per application within each environment.
    • The APNs URI (which uses the bundle ID, such as com.example.myapp) in the notify element ties together the provisioning profile and digital certificate. The provisioning profile and digital certificate are only valid for a single AppID. This relationship ensures that the Gateway can send push notifications to instances of a specific iOS app, and to no other application.
    • If you use separate digital certificates for the Gateway and the iOS app, then both certificates must have the same bundle ID.

type

The type of service. One of the following:

balancer

Use the balancer service to balance load for requests for any other Gateway service type.

Example

The following example shows a Gateway with a balancer service and an Echo service that contains a balance element. Note that the accept URI in the balancer service matches the balance URI in the Echo service.

Balancer Service

<service>
  <accept>ws://balancer.example.com:8081/echo</accept>

  <type>balancer</type>
  
  <accept-options>
    <ws.bind>192.168.2.10:8081</ws.bind>
  </accept-options>

  <cross-site-constraint>
    <allow-origin>http://directory.example.com:8080</allow-origin>
  </cross-site-constraint>
</service>

Gateway Service Participating in Load Balancing

<service>
  <accept>ws://node1.example.com:8081/echo</accept>
  <balance>ws://balancer.example.com:8081/echo</balance>

  <type>echo</type>

  <cross-site-constraint>
    <allow-origin>http://directory.example.com:8080</allow-origin>
  </cross-site-constraint>
</service>

Notes

  • When you configure the Gateway as a load balancer you specify accept elements that identify the URLs on which the balancer service listens for client requests. The balancer service is used to balance load for a cluster of Gateways.
  • As with all services, the balancer service needs to have appropriate cross-site constraints defined.
  • For more information about load balancing and using the balancer service, see the Checklist: Configure Kaazing WebSocket Gateway for High Availability topic.

broadcast

Use the broadcast service to relay information from a back-end service. The broadcast service has the following property:

broadcast Property Description
accept The URL of the broadcast service to which a back-end service connects.

Examples

  • The following example configures the broadcast service with the accept element coded inside the properties element. This configures the Gateway to accept connections initiated by the back-end service and broadcast messages that are sent along that connection to clients.
    <service>
      <accept>sse://localhost:8000/sse</accept>
      <accept>sse+ssl://localhost:9000/sse</accept>
    
      <type>broadcast</type>
    
      <properties>
        <accept>udp://localhost:50505</accept>
      </properties>
    
      <cross-site-constraint>
        <allow-origin>http://localhost:8000</allow-origin>
      </cross-site-constraint>
    
      <cross-site-constraint>
        <allow-origin>https://localhost:9000</allow-origin>
      </cross-site-constraint>
    </service>
    
  • The following example configures the broadcast service with a connect element that contains the URL of the back-end service (news.example.com:50505) that the Gateway connects to. If you configure the Gateway in this way, then the Gateway initiates the connection to the back-end service. When the service receives information, it broadcasts it to all the SSE channels accepted from clients on www.example.com.

    <service>
      <accept>sse://www.example.com:8000/sse</accept>
      <accept>sse+ssl://www.example.com:9000/sse</accept>
      <connect>tcp://news.example.com:50505/</connect>
      <type>broadcast</type>
    
      <cross-site-constraint>
        <allow-origin>http://www.example.com:8000</allow-origin>
      </cross-site-constraint>
      <cross-site-constraint>
        <allow-origin>https://www.example.com:9000</allow-origin>
      </cross-site-constraint>
    </service>
    

directory

Use the directory service to expose directories or files hosted on the Gateway. The directory service has the following properties:

Note: The properties must be specified in the order shown in the following table.

Property Required or Optional? Description
directory Required The path to the directory to be exposed on the Gateway.
options Optional Enables directory browsing of the files and folders in the location specified by the directory property. The value indexes must be entered. For example, using the value <options>indexes</options> enables directory browsing. Omitting the options property disables directory browsing. Browsing a directory with welcome-file will serve the welcome file.
welcome-file Optional If the request URL does not contain a file name, then the file name specified here is displayed to the client browser.
error-pages-directory Optional The path to the directory containing the 404.html file. By default, the Gateway includes a 404.html file in GATEWAY_HOME/error-pages. See the Notes for more information.
location Optional You add this element to configure Cache-Control for a resource(s) hosted by the directory service. location provides a resource(s)-specific scope to the cache-control setting, enabling you to specify the Cache-Control for multiple locations served by the directory service. The patterns and cache-control elements are child elements of location. See HTTP Caching with the Directory Service and Cache-Control Examples.
patterns Optional You add this element to instruct the Gateway on which file types and names to apply Cache-Control directives. For example, **/* specifies all files and **/*.html specifies HTML files. The `patterns` element uses the Apache DirectoryScanner syntax. Note: as patterns applies to a URL path, the separator is / not \. The patterns element contains one or more patterns that are whitespace separated, for example. See HTTP Caching with the Directory Service and Cache-Control Examples.
cache-control Optional You add this element to configure the caching behavior for the resource(s) matching by the patterns value. The syntax is <cache-control>value</cache-control> where value is a string containing valid Cache-Control directives, as specified by RFC 7234, section 5.2.2 Response Cache-Control Directives. The directive names used in cache-control must be those specified in RFC 7234, such as max-age, public, no-cache, etc. The format must be as specified in RFC 7234, namely comma-separated. Example: <cache-control>max-age=60, public, no-store</cache-control>. See HTTP Caching with the Directory Service and Cache-Control Examples.

HTTP Caching with the Directory Service

HTTP/1.0 provided the Expires header as a simple way for an origin server to mark a response with a time before which a client cache could return the response validly. The server might then either respond with a 304 (Not Modified) status code, implying that the cache entry is valid, or it might send a normal 200 (OK) response to replace the cache entry. The problem with this mechanism is that neither origin servers or clients can give full and explicit instructions to caches, leading incorrect caching of some responses that should not have been cached, and failure to cache some responses that could have been cached.

In RFC 7234, HTTP/1.1 adds the new `Cache-Control` header to make caching requirements more explicit than in HTTP/1.0. The Cache-Control header allows an extensible set of directives to be transmitted in both requests and responses. See Cache-Control Examples.

Here are a few examples of Cache-Control directives that are used in the cache-control property:

max-age

You use this Cache-Control directive to state that the resource included in the response is to be considered stale after its age is greater than the specified number of seconds. For example, <cache-control>max-age=0</cache-control> means the resource expires immediately.

You can specify your preferred time interval syntax in milliseconds, seconds, minutes, or hours (spelled out or abbreviated). For example, all of the following are valid: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit then seconds are assumed.

You can also use the formula [m+]N [time unit]. m represents the last modified date. N can be 0 or a positive integer. 0 signifies the resource expires immediately. [time unit] is optional, and defaults to seconds if omitted. For example: max-age=m+2 hours instructs the client to expire the file two hours after the file was last modified.

There is an important difference between expiry of a file based on when the client downloaded the resource and expiry based on the last modified date of the resource. Here is the distinction:

  • By default, expiry is relative to when the client downloaded the resource. For example, if max-age is 1 hour, the resource expires 1 hour from when the client downloaded it. If a second client downloaded the same resource 15 minutes after the first client did, then their resource will expire 15 minutes later than the one downloaded by the first client.
  • If you specify the expiry of the resource relative to the last modified date of the resource, then the resource will expire at the same time for every client, regardless of when the clients downloaded it. This feature gives you the ability to expire a resource at the same time for all users, irrespective of when they first downloaded it, such as when you know you are going to release a new version of a resource at predictable times.

See Cache-Control Examples.

public

A Cache-Control directive stating that any cache may store the response, even if the response would normally be non-cacheable or cacheable only within a private cache. See See Cache-Control Examples.

Note that this does not guaranteed privacy. Only cryptographic mechanisms can provide true privacy. See Secure Network Traffic with the Gateway.

no-store

A Cache-Control directive stating that a cache must not store any part of either the immediate request or response. This directive applies to both private and shared caches. See Cache-Control Examples.

Cache-Control Examples

Directory Service Example

The following is an example of a service element of type directory that accepts connections on example.com by default:

<service>
  <accept>http://www.example.com:80/</accept>
  <accept>https://www.example.com:443/</accept>
    <type>directory</type>
  <properties>
    <directory>/</directory>
    <welcome-file>index.html</welcome-file>
    <error-pages-directory>/error-pages</error-pages-directory>
    <location>
      <patterns>**/*</patterns>
      <cache-control>max-age=1 year</cache-control>
    </location>
</service>

Cache-Control Examples

You can use any valid Cache-Control directives, as specified by RFC 7234, section 5.2.2 Response Cache-Control Directives. In the following examples, only a few of the available directives are used.

Examples for max-age:

The resources expire immediately and the client MUST validate the resource with the Gateway before using it:

<location>
  <patterns>**/*</patterns>
  <cache-control>max-age=0</cache-control>
</location>

Do not cache the resource at all, but validate the response with the Gateway before processing it (see RFC 7234, section 5.2.2.2 no-cache):

<cache-control>no-cache</cache-control>

The resources expire after one minute:

<cache-control>max-age=60</cache-control>

or

<cache-control>max-age=60 seconds</cache-control>

or

<cache-control>max-age=1 minute</cache-control>

The resources expire after one hour:

<cache-control>max-age=1 hour</cache-control>

or

<cache-control>max-age=60 minutes</cache-control>

The following resources expire in one year:

<cache-control>max-age=1 year</cache-control>

Expire two hours after the file was last modified (note that whitespace is allowed between m+ and N, and also between the m and the + of m+. The m can be upper or lowercase):

<cache-control>max-age=m+2 hours</cache-control>

or

<cache-control>max-age=m+ 2 hours</cache-control>

or

<cache-control>max-age=m + 2 hours</cache-control>

Examples of pattern matching for Cache-Control

You can configure a file type pattern for the Gateway to use with cache control. Here are some examples.

Files in specific folders should be cached for a year:

<properties>
  <location>
    <patterns>
      **/images/*
      **/css/*
      **/js/*
    </patterns>
    <cache-control>max-age=1 year</cache-control>
  </location>
</properties>

Images should be cached for a year and HTML files expire immediately:

<properties>
  <!-- Default all files to a far future expires -->
  <location>
    <patterns>**/*.gif</patterns>
    <cache-control>max-age=1 year</cache-control>
  </location>

  <!-- Always reload HTML files -->
  <location>
    <patterns>**/*.html</patterns>
    <cache-control>max-age=0</cache-control>
  </location>
</properties>

Here is an example of conflicting pattern matching, where the pattern for the first location appears to conflict with the pattern matching of the second location:

<properties>
  <!-- Default all files to a far future expires -->
  <location>
    <patterns>**/*</patterns>
    <cache-control>max-age=1 year</cache-control>
  </location>

  <!-- Always reload HTML files -->
  <location>
    <patterns>**/*.html</patterns>
    <cache-control>no-cache</cache-control>
  </location>
</properties>

There is no validation of conflicting directives on the Gateway. Recipients of the HTTP response can handle the headers as required by RFC 7234, or as they choose.

Notes

  • The path you specify for the directory service must be relative to the directory GATEWAY_HOME\web (where GATEWAY_HOME is the directory in which KAAZING Gateway is installed). For example, C:\gateway\GATEWAY_HOME\web. An absolute path cannot be specified.
  • KAAZING Gateway services are configured to accept connections on localhost by default. The cross-origin sites allowed to access those services are also configured for localhost-only by default. If you want to connect to host names other than localhost you must update your server configuration, and use the fully qualified host name of the host machine.
  • If you use the optional error-pages-directory property, you can test it by adding the property, saving the gateway-config.xml file, then starting the Gateway. Once the Gateway is running, point your browser to a page that does not exist, such as http://localhost:8000/nonexistentpage.html.
  • There is the possibility of conflicts with cache-control. For example, all resources could be configured with expiry dates far in the future, but HTML files could be configured to expire immediately. In the case of conflicts, the setting with the shortest expiration will take precedent.
  • Support for Cache-Control might not be consistent across all network proxies or Web browsers. In some cases, it might be necessary to overlap directives. For example, see this discussion on stackoverflow.

echo

This type of service receives a string of characters through a WebSocket connection and returns, or echoes the same characters to the sender.

Example

<service>
  <accept>ws://localhost:8001/echo</accept>
  <accept>wss://localhost:9001/echo</accept>

  <type>echo</type>
  
  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>

  <cross-site-constraint>
    <allow-origin>https://localhost:9000</allow-origin>
  </cross-site-constraint>
</service>

Notes

  • The primary use for the echo service is to validate the basic gateway configuration.
  • The default echo service is configured to run on a separate port to verify cross-origin access.

kerberos5.proxy

Use the kerberos5.proxy service to connect the Gateway to the Kerberos Key Distribution Center.

Example

<service>
  <accept>ws://localhost:8000/kerberos5</accept>
  <connect>tcp://kdc.example.com:88</connect>

  <type>kerberos5.proxy</type>

  <cross-site-constraint>
    <allow-origin>*</allow-origin>
  </cross-site-constraint>
</service>

Notes

  • The kerberos5.proxy service is required when you configure the Application Negotiate authentication scheme.

management.jmx

Use the management.jmx service type to track and monitor user sessions and configuration data using JMX Managed Beans.

Example

The following example is a snippet from the default Gateway configuration file showing the JMX Management section:

     <service>
       <name>JMX Management</name>
           <description>JMX Management Service</description>

           <type>management.jmx</type>
          
           <properties>
             <connector.server.address>jmx://${gateway.hostname}:2020/</connector.server.address>
           </properties>

       <!-- secure monitoring using a security realm -->
       <realm-name>demo</realm-name>

       <!-- configure the authorized user roles -->
           <authorization-constraint>
         <require-role>ADMINISTRATOR</require-role>
       </authorization-constraint>
     </service>

Notes

  • See Checklist: Monitor Kaazing WebSocket Gateway for an introduction to monitoring the Gateway.
  • See Monitor with JMX for more information and examples of monitoring with JMX.
  • The management.jmx service is enabled by default in the Gateway configuration file.
  • Kaazing WebSocket Gateway supports Java Management Extension (JMX) access through any JMX-compliant console that supports communication using the JMX protocol.

management.snmp

Use the management.snmp service type to monitor a Gateway or a Gateway cluster through Command Center, which is a browser-based application. Using Command Center is the recommended method for monitoring the Gateway.

Example

The following example is a snippet from the default Gateway configuration file showing the SNMP Management section:

      <service>
        <name>SNMP Management</name>
            <description>SNMP Management Service</description>
        <accept>ws://${gateway.hostname}:${gateway.base.port}/snmp</accept>
          
            <type>management.snmp</type>

        <!-- secure monitoring using a security realm -->
        <realm-name>commandcenter</realm-name>

        <!-- configure the authorized user roles -->
            <authorization-constraint>
          <require-role>ADMINISTRATOR</require-role>
        </authorization-constraint>
          
        <cross-site-constraint>
          <allow-origin>*</allow-origin>
        </cross-site-constraint>
      </service>

Notes

session

Use the session service to prevent sessions from timing out.

Example

<service>
  <accept>https://localhost:9000/session</accept>

  <type>session</type>

  <authorization-constraint>
    <require-role>AUTHORIZED</require-role>
  </authorization-constraint>
</service>

Notes

  • Always use HTTPS when configuring communication with the session service.

Pipe scheme

The pipe:// scheme is a URI scheme internal to the Gateway and used to connect one service to another service running in the same Gateway instance. Essentially, the pipe scheme is a named, logical channel between two services on the local Gateway.

The format of the pipe:// scheme is pipe://string, such as pipe://jms-common. The URI must conform to the standard URI syntax. Any values entered after the pipe:// scheme and string, such as a path, are invalid. The URI <accept>pipe://customera/app1</accept> is invalid. If a path is used, the Gateway will respond with an error message.

The pipe:// scheme is available to the accept and connect elements. It is often used with Enterprise Shield and protocol.transport (as pipe.transport).

Let’s look at an example using tiered connection speeds.

You could offer different connection speeds by defining a separate jms.proxy service for each tier and then pipe the client connections into a single jms service. Here’s an example of the configuration for the jms.proxy service for the bottom tier:

<service>
  <name>JMS Minimum Level</name> <!-- the name of the service -->
  <accept>ws://example.com:8001/jms-slow</accept> <!-- clients in the bottom tier connect using this URI -->
  <connect>pipe://jms-common</connect> <!-- connections are piped to the JMS service with the accept pipe://jms-common -->
           
  <type>jms.proxy</type> <!-- this jms.proxy service is used for the bottom tier only -->
       
  <accept-options>
    <tcp.maximum.outbound.rate>1kB/s</tcp.maximum.outbound.rate> <!-- this element sets the outbound speed for the bottom tier -->
  </accept-options>

  <cross-site-constraint>
    <allow-origin>*</allow-origin>
  </cross-site-constraint>
</service>

Here’s an example of the configuration for the jms.proxy service for the middle tier:

<service>
  <name>JMS Medium Level</name> <!-- the name of the service -->
  <accept>ws://example.com:8001/jms-medium</accept> <!-- clients in the middle tier connect using this URI -->
  <connect>pipe://jms-common</connect> <!-- connections are piped to the JMS service with the accept pipe://jms-common -->
           
  <type>jms.proxy</type> <!-- this jms.proxy service is used for the middle tier only -->
       
  <accept-options>
    <tcp.maximum.outbound.rate>20MB/s</tcp.maximum.outbound.rate> <!-- this element sets the outbound speed for the middle tier -->
  </accept-options>

  <cross-site-constraint>
    <allow-origin>*</allow-origin>
  </cross-site-constraint>
</service>

To accept the pipes from the JMS Minimum and Medium Level jms.proxy services, the JMS service has a <accept>pipe://jms-common</accept> in its configuration:

<service>
  <name>JMS Common</name> <!-- the name of the service -->
  <accept>pipe://jms-common</accept> <!-- matches the pipe URI in the connect element of the jms.proxy services -->
  <accept>ws://example.com:8001/jms</accept> <!-- normal, non-tiered connections will connect here -->
  
  <type>jms</type>
  
  <properties>
    <connection.factory.name>ConnectionFactory</connection.factory.name>
    <context.lookup.topic.formatdynamic>Topics/%s</context.lookup.topic.format>
    <context.lookup.queue.format>dynamicQueues/%s</context.lookup.queue.format>
  
    <env.java.naming.factory.initial>
      org.apache.activemq.jndi.ActiveMQInitialContextFactory
    </env.java.naming.factory.initial>
    <env.java.naming.provider.url>
      tcp://localhost:61616
    </env.java.naming.provider.url>
  </properties>
  
  <cross-site-constraint>
    <allow-origin>*</allow-origin>
  </cross-site-constraint>
</service>

properties

The service's type-specific properties.

Example

<service>
  <accept>http://${gateway.hostname}:${gateway.extras.port}/</accept>

  <type>directory</type>

  <properties>
    <directory>/</directory>
    <welcome-file>index.html</welcome-file>
  </properties>
        .
    .
    .
</service>

Notes

  • The properties subelement to used to configure properties that are specific to each service.
  • See also the property subelement that you specify in the Property Defaults section of the Gateway configuration file to define property values once and that are then propagated throughout the configuration when the Gateway starts. See the Configure Kaazing WebSocket Gateway topic for more information about configuring the property defaults section of the Gateway configuration file.

accept-options

Required? Optional; Occurs: zero or one

Use the accept-options element to add options to all accepts for the service (see also the accept element).

Notes:
  • You can configure accept-options on the service or the service-defaults elements:
    • Setting accept-options on the service element only affects the specified service and overrides any defaults.
    • Setting accept-options on service-defaults affects all services that can use that option and is overridden by any accept-options applied at the service level.

    See service-defaults for more information.

accept-options Description
ssl.ciphers Lists the cipher strings and cipher suite names used by the secure connection. See ssl.ciphers.
ssl.protocols Lists the TLS/SSL protocol names on which the Gateway can accept connections. See ssl.protocols and socks.ssl.protocols.

ssl.encryption Signals Kaazing WebSocket Gateway to enable or disable encryption on incoming traffic. See ssl.encryption.
ssl.verify-client Signals Kaazing WebSocket Gateway to require a client to provide a digital certificate that the Gateway can use to verify the client’s identity. See ssl.verify-client.
protocol.bind

Binds the URL(s) on which the service accepts connections (defined by the accept element). Set protocol to one of the following:

  • ws
  • wss
  • http
  • https
  • ssl
  • tcp
  • udp

See protocol.bind

ws.maximum.message.size Specifies the maximum incoming WebSocket message size allowed by the Gateway (see ws.maximum.message.size).
ws.inactivity.timeout Specifies the maximum number of seconds that the network connection can be inactive (seconds is the default time interval syntax). The Gateway will drop the connection if it cannot communicate with the client in the number of seconds specified (see ws.inactivity.timeout). You can specify your preferred time interval syntax in milliseconds, seconds, minutes, or hours (spelled out or abbreviated). For example, all of the following are valid: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit then seconds are assumed. The values for http.keepalive.timeout and ws.inactivity.timeout should be the same.
http.server.header Controls the inclusion of HTTP Server header. By default, the Gateway writes a HTTP Server header (see http.server.header).
http.keepalive.timeout Specifies how much time the Gateway waits after responding to an HTTP or HTTPS request and receiving a subsequent request. The values for http.keepalive.timeout and ws.inactivity.timeout should be the same (see http.keepalive.timeout).
protocol.transport

Specifies the URI for use as a transport layer (defined by the accept element). Set protocol.transport to any of the following:

  • http.transport
  • ssl.transport
  • tcp.transport
  • pipe.transport

See protocol.transport.

socks.mode

The mode that you can optionally set to forward or reverse to tell the Gateway how to interpret SOCKS URIs to initiate the connection (see socks.mode).

socks.ssl.ciphers Lists the cipher strings and cipher suite names used by the secure SOCKS connection. See socks.ssl.ciphers.
socks.ssl.protocols Lists the TLS/SSL protocol names on which the Gateway can accept connections for Enterprise Shield™ configurations that are running the SOCKS protocol over SSL. See ssl.protocols and socks.ssl.protocols.
socks.retry.maximum.interval The maximum interval the Gateway waits before retrying if an attempt to connect to the SOCKS proxy fails. The Gateway initially retries after waiting for 500ms; the subsequent wait intervals are as follows: 1s, 2s, 4s, and so on up to the value of socks.retry.maximum.interval. After the maximum interval is reached, the Gateway continues to reconnect to the SOCKS proxy at the maximum interval. See sock.retry.maximum.interval.
tcp.maximum.outbound.rate Specifies the maximum bandwidth rate at which bytes can be written from the Gateway (outbound) to each client session. This option controls the rate of outbound traffic being sent per client connection for clients connecting to a service (see tcp.maximum.outbound.rate).

ssl.ciphers

Required? Optional; Occurs: zero or one; Values: cipher strings and cipher suite names for OPENSSL and Java 7.

Use ssl.ciphers to list the encryption algorithms used by TLS/SSL on the secure connection (WSS, HTTPS or SSL). By default (or if you do not specify this element on a secure connection), the Gateway uses HIGH,MEDIUM,!ADH,!KRB5.

Examples
  • The following example shows a jms.proxy service accepting a secure connection over WSS and connecting to the back-end server over TCP with the ciphers used by the encryption algorithm specified in ssl.ciphers.

    <service>
      <accept>wss://www.example.com:443/remoteService</accept>
      <connect>tcp://localhost:61613</connect>
    
      <type>jms.proxy</type>
    
      <accept-options>
        <ssl.ciphers>DEFAULT</ssl.ciphers>
      </accept-options>
    
      <connect-options>
        <ssl.ciphers>LOW</ssl.ciphers>
      </connect-options>
    </service>
    

    By default (or if you do not specify ssl.ciphers on a secure connection), the Gateway uses the equivalent of the following ciphers:

    <ssl.ciphers>HIGH,MEDIUM,!ADH,!KRB5</ssl.ciphers>
    
    • HIGH and MEDIUM aliases are included because they do not contain any weak (LOW or EXPORT) cipher suites.
    • ADH (Anonymous Diffie-Hellman) cipher suites are excluded because they are not secure against man-in-the-middle attacks.

      To support DSA certificates, you must add ADH to the ssl.ciphers element as follows: <ssl.ciphers>HIGH,MEDIUM,ADH</ssl.ciphers>. Do not use ADH with DEFAULT. DSA certificates are not recommended. See Diffie-Hellman key exchange for more information. If you omit the -keyalg switch when you create a certificate using keytool, keytool generates a DSA certificate. You should always include -keyalg RSA when creating a certificate using keytool.

    • KRB5 (Kerberos) cipher suites are excluded because most sites do not have the related Kerberose libraries installed for supporting those cipher suites.
  • NULL cipher suite

    Use the NULL cipher suite when you want the Gateway to accept connections from known authenticated TLS clients but you do not want those connections to be encrypted:

    <ssl.ciphers>NULL</ssl.ciphers>
    

    This is analogous to configuring an HTTP service for authentication using authorization-constraint, only now you are doing it for a TLS/SSL service.

  • ALL cipher suite

    Use the ALL cipher suite to enable all of the cipher suites (such as for testing purposes):

    <ssl.ciphers>ALL</ssl.ciphers>
    

    Note that because NULL encryption cipher suites are so insecure they are not enabled even by using the ALL cipher suite. You must explicitly include NULL ciphers by configuring them, as follows:

    <ssl.ciphers>HIGH,MEDIUM,LOW,EXPORT,NULL</ssl.ciphers>
    
Notes
  • The OpenSSL Project documentation lists all permitted OpenSSL cipher strings. The Gateway supports ciphers that are implemented by Java, as described in the Java Secure Socket Extension (JSSE) documentation.
  • For configurations running Kaazing WebSocket Gateway 4.0.5 or earlier releases, you can disable the SSLv3 protocol by configuring SSLv3 ciphers using <ssl.ciphers>!SSLv3<ssl.ciphers>.
  • Values for cipher strings are case-sensitive.
  • Typos or incorrect strings (or unsupported ciphers) in ssl.ciphers are noticed by the Gateway when a connection is made, not when the Gateway is started. These errors are only discoverable by looking at the Gateway log.
  • The ssl.ciphers property does not configure the ciphers used on a secure connection. It merely specified the ciphers used in the TLS/SSL certificate used to establish the secure connection.
  • For secure SOCKS connections, use socks.ssl.ciphers.
  • TLS/SSL is used to verify the Gateway to the client. To use TLS/SSL to verify the client using the connection, use ssl.verify-client.
  • Two or more services can have TLS/SSL accept elements with the same address and port (for example, one service might accept on wss://example.com:9000/echo and another service might accept on https://example.com:9000/directory). If accept elements listening on the same address and port number are also configured with the ssl.ciphers accept option, the values for ssl.ciphers must be identical.

ssl.protocols and socks.ssl.protocols

Required? Optional; Occurs: zero or one; Values: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2

Specify a comma-separated list of the TLS/SSL protocol names on which the Gateway can accept or make connections. The list of protocols you specify are negotiated during the TLS/SSL handshake when the connection is created. See How TLS/SSL Works with the Gateway to learn more about secure communication between clients and the Gateway. See the Java Documentation for a list of valid protocol names.

The ssl.protocols and socks.ssl.protocols elements are optional, and in general, there is no need to configure either element except to prevent usage of specific TLS/SSL protocols for which a vulnerability has been discovered. A good example is the POODLE attack that exploited a vulnerability in SSLv3.

If you configure these elements, then you must explicitly name the TLS/SSL protocols you want to enable. If you do not configure the ssl.protocols or socks.ssl.protocols element, or you configure either element but do not specify any protocols, then the default value is taken from the underlying JVM. The protocol values are case-sensitive.

Typically, you configure the ssl.protocols or socks.ssl.protocols in the accept-options for inbound requests from clients. You might also specify these elements in the connect-options for an Enterprise Shield™ configuration, although this is less common because Gateway-to-Gateway communication usually occurs in a controlled environment and the TLS/SSL protocol you use is controlled. The ssl.protocols and socks.ssl.protocols elements are more useful in the accept-options when accepting requests from clients that are not in your direct control.

Note: These elements were introduced in Kaazing WebSocket Gateway release 4.0.6 and can be used for configurations running Kaazing WebSocket Gateway 4.0.6 or later releases. For configurations running Kaazing WebSocket Gateway 4.0.5 or earlier releases, you can disable the SSLv3 protocol by disabling SSLv3 ciphers with <ssl.ciphers>!SSLv3</ssl.ciphers>. See ssl.ciphers for more information.

If you configure the ssl.protocols or the socks.ssl.protocols element to enable SSLv3, but disable SSLv3 cipher suites with the ssl.ciphers or socks.ssl.ciphers elements, then the connection does not occur and the Gateway will not accept SSLv3 connections. Similarly, if you enable TLSv1 with the ssl.protocols or the socks.ssl.protocols element, but disable the TLSv1 ciphers, then the handshake will not succeed and the connection cannot go through.

Example: Simple Configuration Using ssl.protocols to Accept TLSv1, TLSv1.2, and TLSv1.1 Connections

The following example shows a jms.proxy service. Because the accept URL the wss:// scheme, we know that this is a secure connection. The ssl.protocols element in line 12 indicates that we want the Gateway to accept only TLSv1, TLSv1.2, and TLSv1.1 protocols, say, from clients over this secure connection.

<service>
  <name>DMZ Gateway</name>
  <accept>wss://example.com:443/myapp</accept>
    ... 
  <type>jms.proxy</type>

  <properties>
    ... 
  </properties>

  <accept-options>
    <ssl.protocols>TLSv1,TLSv1.2,TLSv1.1</ssl.protocols>
    ... 
  </accept-options>
  
</service>
Example: Enterprise Shield™ Configuration Using socks.ssl.protocols to Accept Reverse Connections on TLSv1.2

This example shows a jms.proxy service in the DMZ configured for Enterprise Shield™, for which the behavior is reversed. Instead of connecting to another host, the Gateway accepts connections instead. Thus, the setting is configured as connect-options in this example. For more information about Enterprise Shield™ and forward and reverse connectivity, see Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

Because this configuration connects a Gateway to another Gateway in a controlled data center, the example only configures the TLSv1.2 protocol for secure connections. For this type of topology we don't expect to make any other kinds of connections.

The prefix for this example is socks.ssl, rather than just ssl to explicitly reference the SSL layer that is transporting the SOCKS protocol.

<service>
  <name>DMZ Gateway</name>
  <accept>wss://example.com:443/myapp</accept>
  <connect>wss://example.com:443/myapp</connect>
    ... 
  <type>jms.proxy</type>

  <properties>
    ... 
  </properties>
  
  <connect-options>
    <http.transport>socks://internal.example.com:1080</http.transport>
	<socks.mode>reverse</socks.mode>
	<socks.transport>ssl://internal.example.com:1080</socks.transport>
	<socks.ssl.protocols>TLSv1.2</socks.ssl.protocols>
  </connect-options>
     ... 	 
</service>
Example: Enterprise Shield™ Configuration Using Both the ssl.protocols and socks.ssl.protocols Elements

This example combines the previous two examples to show an Enterprise Shield™ configuration in which ssl.protocols is specified in the accept-options, and socks.ssl.protocols is specified in the connect-options.

On the frontplane, the Gateway accepts connections from clients only using the TLSv1, TLSv1.2, and TLSv1.1 protocols. On the backplane, the Gateway only accepts (reverse) connections using the protocol TLSv1.2 (from another Gateway).

<service>
  <name>DMZ Gateway</name>
  <accept>wss://example.com:443/myapp</accept>
  <connect>wss://example.com:443/myapp</connect>
    ... 
  <type>jms.proxy</type>

  <properties>
    ... 
  </properties>

  <accept-options>
    <ssl.protocols>TLSv1,TLSv1.2,TLSv1.1</ssl.protocols>
    ... 
  </accept-options>
  
  <connect-options>
    <http.transport>socks://internal.example.com:1080</http.transport>
	<socks.mode>reverse</socks.mode>
	<socks.transport>ssl://internal.example.com:1080</socks.transport>
	<socks.ssl.protocols>TLSv1.2</socks.ssl.protocols>
  </connect-options>
     ... 
	 
</service>

ssl.encryption

Required? Optional; Occurs: zero or one; Values: enabled, disabled

This element allows you to enable or disable TLS/SSL encryption on incoming traffic to the Gateway, turning off TLS/SSL certificate verification for an HTTPS or WSS accept. By default (or if you do not specify this element), encryption is enabled for HTTPS and WSS.

For example, if the Gateway is deployed behind a TLS/SSL offloader (a network device designed specifically for handling a company's TLS/SSL certificate traffic), where the incoming traffic to the TLS/SSL offloader is secured over HTTPS and the outgoing traffic from the TLS/SSL offloader to the Gateway is not secure, you can disable encryption so that the Gateway accepts the unsecured traffic on a connection that uses HTTPS/WSS. Basically, the Gateway trusts traffic from the TLS/SSL offloader and therefore the Gateway does not need to verify the connection itself.

You can include the accept-options element on a service that accepts over HTTPS or WSS, then disable encryption by setting the ssl.encryption element to disabled. Even when encryption is disabled, the Gateway returns the response as HTTPS/WSS. If you do not include these elements or set the ssl.encryption element to enabled, the Gateway treats incoming traffic on HTTPS or WSS as secure and handles the TLS/SSL certificate verification itself.

See Checklist: Secure Network Traffic with the Gateway for more information about HTTPS/WSS.

The following example shows a service element containing the accept-options and ssl.encryption elements, which signal the Gateway to listen on address www.example.com, with encryption disabled.

<service>
  <accept>wss://www.example.com/remoteService</accept>
  <connect>tcp://localhost:61613</connect>

  <type>jms.proxy</type>
   .
   .
   .
  <accept-options>
    <ssl.encryption>disabled</ssl.encryption>
  </accept-options>
</service>
 

Alternatively, the IP address can be used in the configuration parameters. You can also specify an IP address and port for the external address. Typically when you disable encryption on the incoming traffic, as the Gateway is behind a TLS/SSL offloader, you will also have a network mapping section mapping www.example.com to internal address gateway.dmz.net:9000.

Notes
  • If you have set up Kaazing WebSocket Gateway behind a TLS/SSL offloader, where the front-end traffic is secure over HTTPS and the back-end traffic behind the TLS/SSL offloader to the Gateway is not secure, then you can disable encryption so that the connection can occur. You can include the accept-options element, then disable encryption by setting the ssl.encryption element to disabled. When encryption is disabled, the Gateway returns the response as HTTPS. If you do not include these elements or set the ssl.encryption element to enabled, the Gateway treats incoming traffic on www.example.com:443 as secure and handles the TLS/SSL itself.
  • See Checklist: Secure Network Traffic with the Gateway for more information about HTTPS.

ssl.verify-client

Required? Optional; Occurs: zero or one; Values: required, optional, none

By default, when the Gateway accepts a secure URI (for example, WSS, HTTPS, SSL), the Gateway provides its digital certificate to connecting clients but does not require that the clients provide a certificate of their own — the Gateway trusts all clients. For added security, implement a mutual verification pattern where, in addition to the Gateway presenting a certificate to the client, the client also presents a certificate to the Gateway so that the Gateway can verify the client's authenticity.

To configure that, you can use the ssl.verify-client on an accept to specify that the Gateway requires a client to provide a digital certificate that the Gateway can use to verify the client’s identity. This configuration ensures that both the clients and the Gateway are verified via TLS/SSL before transmitting data, establishing a mutually-verified connection.

If you configure the ssl.verify-client option with the value ... Then ...
required A client certificate is required. The Gateway requires that the client connecting to the Gateway over the secure URI in the accept must provide a digital certificate to verify the client’s identity. After the Gateway has verified the client certificate, then the client can connect to the Gateway service.
optional The client certificate is not required, but if a client provides a certificate, the Gateway attempts to verify it. If the client provides a certificate and verification fails, then the client is not allowed to connect.
none The client recognizes that a certificate is not required and it does not send a certificate. All clients can connect to the secure service on the Gateway.
Example

In the following example, the Gateway accepts on a secure URI (wss://) and requires that all clients connecting to the Gateway on that URI provide a digital certificate verifying their identity.

<service>
  <accept>wss://example.com:443</accept>
  <connect>tcp://server1.corp.example.com:5050</connect>

  <type>jms.proxy</type>

  <accept-options>
    <ssl.verify-client>required</ssl.verify-client>
  </accept-options>
</service>
Notes
  • In an ${enterprise.shield] topology over wsn+ssl:// or socks+ssl://, the DMZ Gateway provides the internal Gateway with a digital certificate that the internal Gateway uses to verify the DMZ Gateway’s identity before establishing the secure connection.

    For added security, you can use the socks.ssl.verify-client connect option to require the internal Gateway to provide a client digital certificate to establish a secure connection. This configuration establishes mutual authentication by ensuring that both the DMZ Gateway and internal Gateway are verified via TLS/SSL before transmitting data.

  • To use ssl.verify-client as an accept-option on a service, the service must be accepting on a secure URI (wss://, https://, ssl://). You cannot use ssl.verify-client on an unsecured URI (ws://, http://, tcp://, udp://).
  • If you have set up Kaazing WebSocket Gateway behind a TLS/SSL offloader, where the front-end traffic is secure over HTTPS and the back-end traffic behind the TLS/SSL offloader to the Gateway is not secure, then you can disable encryption so that the connection can occur. You can include the accept-options element, then disable encryption by setting the ssl.encryption element to disabled. When encryption is disabled, the Gateway returns the response as HTTPS. If you do not include these elements or set the ssl.encryption element to enabled, the Gateway treats incoming traffic on www.example.com:443 as secure and handles the TLS/SSL itself.

    See Checklist: Secure Network Traffic with the Gateway for more information about HTTPS.

  • Configuring ssl.verify-client ensures that both the clients and the Gateway are verified via TLS/SSL before transmitting data, establishing mutual verification. A best practice is to use mutual verification between gateways that are located at different sites. Each gateway can require that the other gateway provide a certificate, thereby ensuring that the connection is secure.
  • Two or more services can have TLS/SSL accept elements with the same address and port (for example, one service might accept on wss://example.com:9000/echo and another service might accept on https://example.com:9000/directory). If accept elements listening on the same address and port number are also configured with the ssl.verify-client accept option, the values for ssl.verify-client must be identical.
  • You must set ssl.verify-client to required if using OCSP. See Implement Certificate Revocation Using OCSP for more details about setting up OCSP with the Gateway.

protocol.bind

Required? Optional; Occurs: zero or more; Where protocol can be ws, wss, http, https, ssl, or tcp

Use protocol.bind to bind an URL or URLs on which the service accepts connections.

Example

The following example shows external addresses (that users will see) for the WebSocket (ws) and WebSocket Secure (wss) protocols on localhost:8000 and localhost:9000. Internally, however, these addresses are bound to ports 8001 and 9001 respectively.

<service>
  <accept>ws://localhost:8000/echo</accept>
  <accept>wss://localhost:9000/echo</accept>

  <accept-options>
    <ws.bind>8001</ws.bind>
    <wss.bind>9001</wss.bind>
  </accept-options>
</service>
Notes

See the Integrate Kaazing WebSocket Gateway into an Internal Network document for more information about configuring the protocol.bind element.

ws.maximum.message.size

Required? Optional; Occurs: zero or one

Configures the maximum message size the service can accept from a WebSocket client connection.

Although the ws.maximum.message.size is optional, you should configure this element to keep clients from accidentally or deliberately causing the Gateway to spend resources processing large messages. Setting this element is useful in preventing denial of service attacks because you can limit the size of the message (such as a particularly large message) incoming to the Gateway from a client.

The actual maximum message size that the Gateway can handle is influenced by the JVM settings (such as maximum heap size), available memory on the system, network resources, available disk space and other operating system resources. The maximum message size is also influenced by the configuration and capabilities of back-end services to which the Gateway might be forwarding these messages. The best way to determine the true maximum message size for your environment and use case is to perform some testing.

If you do not specify ws.maximum.message.size in the gateway-config.xml file, then the default maximum incoming message is limited to 128k.

If you specify ws.maximum.message.size in the gateway-config.xml file, then specify a positive integer. You can append a k, K, m, or M to indicate kilobytes or megabytes (the unit is case insensitive). If a unit is not included, then ws.maximum.message.size defaults to bytes. For example:

  • A value of 2048 sets the buffer to 2048 bytes
  • A value of 128K sets the buffer to 128 kilobytes
  • A value of 128M sets the buffer to 128 megabytes

If an incoming message from a client exceeds the value of ws.maximum.message.size, then the Gateway terminates the connection with the client and disconnects the client, and records a message in the Gateway log.

Example

The following example shows a service element containing a maximum incoming message limit of 64k, as shown in line 8:

<service>
  <accept>ws://localhost:8000/echo</accept>
  <accept>wss://localhost:9000/echo</accept>
  <accept-options>
    <ssl.encryption>disabled</ssl.encryption>
    <ws.bind>8001</ws.bind>
    <wss.bind>9001</wss.bind>
    <ws.maximum.message.size>64k</ws.maximum.message.size>
  </accept-options>
</service>

ws.inactivity.timeout

Required? Optional; Occurs: zero or one

Specifies the maximum number of seconds that the network connection can be inactive (seconds is the default time interval syntax). The Gateway will drop the connection if it cannot communicate with the client in the number of seconds specified (see ws.inactivity.timeout). You can specify your preferred time interval syntax in milliseconds, seconds, minutes, or hours (spelled out or abbreviated). For example, all of the following are valid: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit then seconds are assumed. An inactive connection can result from a network failure (such as a lost cellular or Wi-Fi connection) that prevents network communication from being received on any established connection. Thus, when ws.inactivity.timeout is set to a nonzero time interval, the Gateway will drop the connection if it cannot communicate with the client in the number of seconds specified.

Important: The values for http.keepalive.timeout and ws.inactivity.timeout should be the same.

Some use cases for the ws.inactivity.timeout property include:

  • Detect a lost cellular (or Mobile) connection or a lost Wi-Fi connection.
  • Detect a half-closed connection over WebSocket, such as a silent network failure over WebSocket between Gateways.
  • Detect a network failure between the DMZ and Internal Gateway over WebSocket, such as for an Enterprise Shield™ topology using forward and reverse connectivity.
Example

In the following example, the ws.inactivity.timeout property specifies that if the Gateway cannot communicate with a client over the past five-seconds, then the connection to that client will be dropped.

<service>
  <accept>ws://gateway.example.com/echo</accept>
  <connect>ws://internal.example.com/echo</connect>

  <type>echo</type>

 <accept-options>
   <ws.inactivity.timeout>5s</ws.inactivity.timeout>
 </accept-options>
   .
   .
   .
</service>
Notes
  • Set the time interval to a value that is at least double the expected maximum network round-trip time between the Gateway and any client. Otherwise, clients may be disconnected unexpectedly.
  • A reasonable starting point is to set ws.inactivity.timeout to 60 seconds, and then adjust the value higher or lower based on your environment. For example, if you know a firewall in your environment will terminate idle connections after 30 minutes, then you could increase the value of this setting to 25 minutes.
  • You can specify your preferred time interval syntax in milliseconds, seconds, minutes, or hours (spelled out or abbreviated). For example, all of the following are valid: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit then seconds are assumed.

http.server.header

Required? Optional; Occurs: zero or one; Values: enabled or disabled

Enables or disables the inclusion of the HTTP server header. By default, the Gateway writes a HTTP server header. In general, there is no need to configure this accept option unless you want to obscure server header information.

This setting is ignored for services that do not accept HTTP or WebSocket connections.

Hint: Instead of specifying this setting on every service, consider adding it using the service-defaults element to globally apply the setting across all services running on the Gateway.

Example
<service>
  ...
  <accept-options>
    <http.server.header>disabled</http.server.header>
  </accept-options>
  ...
</service>

http.keepalive.timeout

Required? Optional; Occurs: zero or one

Use the http.keepalive.timeout accept-option to set the number of seconds the Gateway waits after responding to a request and receiving a subsequent request on an HTTP or HTTPS connection before closing the connection. The default value is 30 seconds.

Important: The values for http.keepalive.timeout and ws.inactivity.timeout should be the same..
Example

The following example shows a service element containing an HTTP or HTTPS connection time limit of 120 seconds, as shown in line 8:

<service>
  <accept>ws://localhost:8000/echo</accept>
  <accept>wss://localhost:9000/echo</accept>
  <accept-options>
    <ssl.encryption>disabled</ssl.encryption>
    <ws.bind>8001</ws.bind>
    <wss.bind>9001</wss.bind>
    <http.keepalive.timeout>120</http.keepalive.timeout>
  </accept-options>
</service>
Notes
  • the http.keepalive.timeout accept-option is useful for conserving resources because it avoids idle connections remaining open.
  • You can specify your preferred time interval syntax in milliseconds, seconds, minutes, or hours (spelled out or abbreviated). For example, all of the following are valid: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit then seconds are assumed.

protocol.transport

Required? Optional; Occurs: zero or more; Where protocol can be pipe, tcp, ssl, or http.

Use the protocol.transport accept-option to replace the default transport with a new transport. This allows you to change the behavior of the connection without affecting the protocol stack above the transport. For example, a TCP transport normally connects to a remote IP address and port number. However, you could replace that, for instance, with an in-memory (pipe) transport that communicates with another service in the same Gateway.

Specify any of the following transports:

  • http.transport: Specifies a URI for use as a transport layer under the HTTP transport or WebSocket transport (since WebSocket is always over HTTP). This is the most frequently used transport option.
  • ssl.transport: Specifies a URI for use as a transport layer under the TLS/SSL transport.
  • tcp.transport: Specifies a URI for use as a transport layer under the TCP/IP (tcp) transport.
  • pipe.transport: Specifies a URI for use as a transport layer under the pipe transport.
Example

In the following example, the HTTP transport has been replaced with a new (socks+ssl) transport that is capable of doing a reverse connection using the SOCKS protocol over TLS/SSL.

  <service>
    <accept>wss://gateway.example.com:443/path</accept>
    <connect>tcp://internal.example.com:1080</connect>
    .
    .
    .
    <accept-options>
      <http.transport>socks+ssl://gateway.dmz.net:1080</http.transport>
      <socks.mode>reverse</socks.mode>
      <socks.retry.maximum.interval>1 second</socks.retry.maximum.interval>         
    </accept-options>
  </service>

For more examples, see Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

socks.mode

Required? Optional; Occurs: zero or one

Use the socks.mode accept-option to initiate the the Gateway connection using the SOCKet Secure (SOCKS) protocol in one of the following modes:

  • forward: initiates forward connectivity from the DMZ Gateway to the internal Gateway on the trusted network. Once connected, a regular full-duplex connection is established. You typically use the forward mode to ensure the SOCKS settings are correctly configured before you attempt to reverse the connection.
  • reverse: configures the connection mode in reverse so that the connection is initiated from the internal Gateway on the trusted network to the DMZ Gateway to allow a connection between the client and server that is otherwise blocked by the firewall. With the reverse mode, the Gateway interprets accept URIs as connect URIs.

For more information about Enterprise Shield™ and forward and reverse connectivity, see Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

Example

The following example shows a service element with the socks.mode set to reverse, and thus tells the Gateway to interpret the SOCKS URI as a connect URI, as shown in line 8:

<service>
  <accept>pipe://pipe-1</accept>
  <connect>tcp://broker.example.com:8010/</connect>

  <type>jms.proxy</type>

  <accept-options>
    <pipe.transport>socks+ssl://dmz.example.com:1443</pipe.transport>
    <socks.mode>reverse</socks.mode>
    <socks.retry.maximum.interval>45 seconds</socks.retry.maximum.interval>
  </accept-options>
</service>

socks.retry.maximum.interval

Required? Optional; Occurs: zero or one

Use the socks.retry.maximum.interval accept-option in an Enterprise Shield™ topology to set the maximum interval of time that the internal Gateway waits to retry a reverse connection to the DMZ Gateway after a failed attempt.

Setting socks.retry.maximum.interval handles cases where the DMZ Gateway has not started but the internal Gateway keeps trying to connect to the DMZ Gateway. The setting is the maximum backoff interval. The internal Gateway initially retries after waiting for 500ms, and the subsequent wait intervals start at 100ms, then continue at 200ms, then 400ms, and continue doubling until reaching the specified maximum interval. Once the maximum interval is reached, the Gateway continues to reconnect to the SOCKS proxy at the maximum interval. If no maximum is specified, then the default maximum retry interval is 30 seconds. For more information about configuring the SOCKS proxy, see Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

For most cases, setting socks.retry.maximum.interval to 60 seconds is recommended because it:

  • Reduces the amount of time between retry attempts to connect to the DMZ Gateway.
  • Makes it less likely that services in the DMZ Gateway go into a quiesced mode at startup. (At startup: the value set for the socks.timeout element in the DMZ Gateway determines how long the reverse-port is bound before going into the heartbeat/quiesced mode.)
  • Avoids the situation where it appears that the system is not working when things are simply paused or delayed.
Example

The following example shows a service element containing a SOCKS proxy connection retry interval time limit of 60 seconds, as shown in line 10:

<service>
  <accept>pipe://pipe-1</accept>
  <connect>tcp://broker.example.com:8010/</connect>

  <type>jms.proxy</type>

  <accept-options>
    <pipe.transport>socks+ssl://dmz.example.com:1443</pipe.transport>
    <socks.mode>reverse</socks.mode>
    <socks.retry.maximum.interval>60 seconds</socks.retry.maximum.interval>
  </accept-options>
</service>

socks.ssl.ciphers

Required? Optional; Occurs: zero or one; Values: cipher strings and cipher suite names for OPENSSL and Java 7.

Use socks.ssl.ciphers to list the encryption algorithms used by TLS/SSL on the secure connection (WSS, HTTPS or SSL). By default (or if you do not specify this element on a secure connection), the Gateway uses HIGH,MEDIUM,!ADH,!KRB5.

Example

The following example shows a jms.proxy service accepting a secure connection over WSS and connecting to the back-end server over TCP with the ciphers used by the encryption algorithm specified in ssl.ciphers.

<service>
  <accept>wss://www.example.com:443/remoteService</accept>
  <connect>tcp://localhost:61613</connect>

  <type>jms.proxy</type>

  <accept-options>
    <ssl.ciphers>DEFAULT</ssl.ciphers>
    <ssl.verify-client>none</ssl.verify-client>
  </accept-options>

  <connect-options>
    <ssl.ciphers>LOW</ssl.ciphers>
  </connect-options>
</service>
Example for SOCKS Ciphers

The following example shows a jms.proxy service for the DMZ Gateway in an Enterprise Shield™ topology. The Gateway receives secure client connections (wss://) and specifies the ciphers used on the accept URI (DEFAULT), but does not require mutual verification from the clients (ssl.verify-client). In addition, the internal Gateway connects over SOCKS and TLS/SSL (socks+ssl://) to the DMZ Gateway, specifies the ciphers used (NULL), and requires mutual verification (socks.ssl.verify-client). For more information about forward and reverse connectivity, see Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

<service>
  <accept>wss://dmz.example.com:443/remoteService</accept>
  <connect>tcp://internal.example.com:8000</connect>

  <type>jms.proxy</type>

  <properties>
    <prepared.connection.count>1</prepared.connection.count>
  </properties>

  <accept-options>
    <ssl.ciphers>DEFAULT</ssl.ciphers>
    <ssl.verify-client>none</ssl.verify-client>     
  </accept-options>

  <connect-options>
    <tcp.transport>socks+ssl://dmz.example.com:1443</tcp.transport>
    <socks.mode>reverse</socks.mode>
    <socks.ssl.ciphers>NULL</socks.ssl.ciphers>
    <socks.ssl.verify-client>required</socks.ssl.verify-client>     
  </connect-options>
</service>
Notes
  • Values are case-sensitive.
  • The socks.ssl.ciphers property does not configure the ciphers used on a secure connection. It merely specified the ciphers used in the TLS/SSL certificate used to establish the secure connection.
  • OpenSSL aliases and names listed as Not implemented in the OPENSSL documentation are not supported by the Gateway.
  • Typos or incorrect strings (or unsupported ciphers) in socks.ssl.ciphers are noticed by the Gateway when a connection is made, not on startup. These errors are only discoverable by looking at the Gateway log.
  • TLS/SSL is used to verify the Gateway to the client. To use TLS/SSL to verify the client using the connection, use ssl.verify-client.
  • For configurations running Kaazing WebSocket Gateway 4.0.5 or earlier releases, you can disable the SSLv3 protocol by configuring SSLv3 ciphers using <ssl.ciphers>!SSLv3<ssl.ciphers>.

tcp.maximum.outbound.rate

Required? Optional; Occurs: zero or one

Use the tcp.maximum.outbound.rate accept option to specify the maximum bandwidth rate at which bytes can be written from the Gateway to a client session. This option delays outbound messages as a way to control the maximum rate, per client session, at which the Gateway can send data to clients connecting to a service.

You must specify the value of tcp.maximum.outbound.rate as a positive integer with either no specified unit or appended with B/s (byte), kB/s (kilobyte), KiB/s (kibibyte), MB/s (megabyte), or MiB/s (Mebibytes) per second. (See the NIST Reference for more information about these units.) Do not use spaces between the numeric portion and the units (for example, 40MB/s is supported but 40 MB/s is not supported).

You must specify the value of tcp.maximum.outbound.rate as a positive integer with either no specified unit or appended with a unit of measurement from the following table. (See the NIST Reference for more information about these units.) Do not use spaces between the numeric portion and the units (for example, 40MB/s is supported but 40 MB/s is not supported).

Unit Abbreviation Bytes per Second per Unit Notes
Byte per second B/s 1 Example: 512B/s
kilobyte per second kB/s 1000 (103) Decimal kilobytes per second. Example: 1000kB/s
kibibyte per second KiB/s 1024 (210) Kibibytes per second (kilobytes binary). Example: 1KiB/s
megabyte per second MB/s 1,000,000 (106) Decimal megabytes per second. Example: 1MB/s
mebibyte per second MiB/s 1,048,576 (220) Mebibytes per second (megabytes binary) Example: 512MiB/s
Example

The following example shows a portion of a Gateway configuration file containing three services, each with a different bandwidth constraint: VIP, premium, and freemium. The VIP service has the best bandwidth at 1 megabyte per second (line 5). The premium service is slower at 1 kibibyte per second (line 13), and the free service is the slowest at only 512 bytes per second (line 21). The example shows these variations configured for the jms.proxy service:

<service>
  <accept>ws://service.example.com/vip</accept>
  <type>jms.proxy</type>
  <accept-options>
    <tcp.maximum.outbound.rate>1MB/s</tcp.maximum.outbound.rate>
  </accept-options>
</service>

<service>
  <accept>ws://service.example.com/premium</accept>
  <type>jms.proxy</type>
  <accept-options>
    <tcp.maximum.outbound.rate>1KiB/s</tcp.maximum.outbound.rate>
  </accept-options>
</service>

<service>
  <accept>ws://service.example.com/freemium</accept>
  <type>jms.proxy</type>
  <accept-options>
    <tcp.maximum.outbound.rate>512B/s</tcp.maximum.outbound.rate>
  </accept-options>
</service>
Notes
  • If no unit is specified, the default unit is in bytes per second (B/s).
  • If you do not specify tcp.maximum.outbound.rate, the bandwidth rate is unrestricted.
  • The Gateway follows the conventions for units defined in the Conversion formula table on the Wikipedia Data rate units page.

connect-options

Required? Optional; Occurs: zero or one

Set the connect-options element to add options to all connections for the service (see also the connect element). connect-options contains the subordinate elements shown in the following table.

Notes:
  • Set connect options only for the service element; You cannot configure connect options at the service-defaults level.
  • The connect options settings affect only the specified service and override any defaults.
Subordinate Element Description
ssl.ciphers Lists the cipher strings and cipher suite names used by the secure connection. See ssl.ciphers.
ssl.protocols Lists the TLS/SSL protocol names on which the Gateway can make connections. See ssl.protocols.
ssl.encryption Signals Kaazing WebSocket Gateway to enable or disable encryption on incoming traffic. See ssl.encryption.
ws.version (deprecated) The ws.version element has been deprecated. See ws.version
protocol.transport

Specifies the URI for use as a transport layer (defined by the connect element). Set protocol.transport to any of the following:

  • http.transport
  • ssl.transport
  • tcp.transport
  • pipe.transport

See protocol.transport.

socks.mode The mode that you can optionally set to forward or reverse to tell the Gateway how to interpret SOCKS URIs to initiate the connection (see socks.mode).
socks.timeout Specifies the length of time (in seconds) to wait for SOCKS connections to form. If the connection does not succeed within the specified time, then the connection fails and is closed and the client must reconnect. For more information, see socks.timeout.
socks.ssl.ciphers Lists the cipher strings and cipher suite names used by the secure SOCKS connection. For more information, see socks.ssl.ciphers.
sock.ssl.protocols Lists the TLS/SSL protocol names on which the Gateway can make connections for Enterprise Shield™ configurations that are running the SOCKS protocol over SSL. For more information, see socks.ssl.protocols
socks.ssl.verify-client A connect mode you can set to required, optional, or none to verify how to secure the SOCKS proxy against unauthorized use by forcing the use of TLS/SSL connections with a particular certificate. When required,the DMZ Gateway expects the internal Gateway to prove its trustworthiness by presenting certificates during the TLS/SSL handshake.
ws.inactivity.timeout Specifies the maximum number of seconds that the network connection can be inactive (seconds is the default time interval syntax). The Gateway will drop the connection if it cannot communicate with the client in the number of seconds specified (see ws.inactivity.timeout). You can specify your preferred time interval syntax in milliseconds, seconds, minutes, or hours (spelled out or abbreviated). For example, all of the following are valid: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit then seconds are assumed. The values for http.keepalive.timeout and ws.inactivity.timeout should be the same.

ssl.ciphers

Required? Optional; Occurs: zero or one; Values: cipher strings and cipher suite names for OPENSSL and Java 7.

Use ssl.ciphers to list the encryption algorithms used by TLS/SSL on the secure connection (WSS, HTTPS or SSL). By default (or if you do not specify this element on a secure connection), the Gateway uses HIGH,MEDIUM,!ADH,!KRB5.

Examples
  • DEFAULT cipher suite

    The following example shows a jms.proxy service accepting a secure connection over WSS and connecting to the back-end server over TCP with the ciphers used by the encryption algorithm specified in ssl.ciphers.

     <service>
       <accept>wss://www.example.com:443/remoteService</accept>
       <connect>tcp://localhost:61613</connect>
    
       <type>jms.proxy</type>
    
       <accept-options>
         <ssl.ciphers>DEFAULT</ssl.ciphers>
       </accept-options>
    
       <connect-options>
         <ssl.ciphers>LOW</ssl.ciphers>
       </connect-options>
     </service>
     

    By default (or if you do not specify ssl.ciphers on a secure connection), the Gateway uses the equivalent of the following ciphers:

     <ssl.ciphers>HIGH,MEDIUM,!ADH,!KRB5</ssl.ciphers>
     
    • HIGH and MEDIUM aliases are included because they do not contain any weak (LOW or EXPORT) cipher suites.
    • ADH (Anonymous Diffie-Hellman) cipher suites are excluded because they are not secure against man-in-the-middle attacks.

      To support DSA certificates, you must add ADH to the ssl.ciphers element as follows: <ssl.ciphers>HIGH,MEDIUM,ADH</ssl.ciphers>. Do not use ADH with DEFAULT. DSA certificates are not recommended. See Diffie-Hellman key exchange for more information. If you omit the -keyalg switch when you create a certificate using keytool, keytool generates a DSA certificate. You should always include -keyalg RSA when creating a certificate using keytool.

    • KRB5 (Kerberos) cipher suites are excluded because most sites do not have the related Kerberose libraries installed for supporting those cipher suites.
  • NULL cipher suite

    Use the NULL cipher suite when you want the Gateway to accept connections from known authenticated TLS clients but you do not want those connections to be encrypted:

     <ssl.ciphers>NULL</ssl.ciphers>
     

    This is analogous to configuring an HTTP service for authentication using authorization-constraint, only now you are doing it for a TLS/SSL service.

  • ALL cipher suite

    Use the ALL cipher suite to enable all of the cipher suites (such as for testing purposes):

     <ssl.ciphers>ALL</ssl.ciphers>
     

    Note that because NULL encryption cipher suites are so insecure they are not enabled even by using the ALL cipher suite. You must explicitly include NULL ciphers by configuring them, as follows:

     <ssl.ciphers>HIGH,MEDIUM,LOW,EXPORT,NULL</ssl.ciphers>
     
Notes
  • The OpenSSL Project documentation lists all permitted OpenSSL cipher suites. The Gateway supports ciphers that are implemented by Java, as described in the Java Secure Socket Extension (JSSE) documentation.
  • For configurations running Kaazing WebSocket Gateway 4.0.5 or earlier releases, you can disable the SSLv3 protocol by configuring SSLv3 ciphers using <ssl.ciphers>!SSLv3<ssl.ciphers>.
  • The values for ciphers are case-sensitive.
  • Typos or incorrect strings (or unsupported ciphers) in ssl.ciphers are noticed by the Gateway when a connection is made, not when the Gateway is started. These errors are only discoverable by looking at the Gateway log.
  • The ssl.ciphers property does not configure the ciphers used on a secure connection. It merely specified the ciphers used in the TLS/SSL certificate used to establish the secure connection.
  • For secure SOCKS connections, use socks.ssl.ciphers.
  • TLS/SSL is used to verify the Gateway to the client. To use TLS/SSL to verify the client using the connection, use ssl.verify-client.
  • Two or more services can have TLS/SSL accept elements with the same address and port (for example, one service might accept on wss://example.com:9000/echo and another service might accept on https://example.com:9000/directory). If accept elements listening on the same address and port number are also configured with the ssl.ciphers accept option, the values for ssl.ciphers must be identical.

ssl.protocols and socks.ssl.protocols

Required? Optional; Occurs: zero or one; Values: SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2

Specify a comma-separated list of the TLS/SSL protocol names on which the Gateway can accept or make connections. The list of protocols you specify are negotiated during the TLS/SSL handshake when the connection is created. See How TLS/SSL Works with the Gateway to learn more about secure communication between clients and the Gateway. See the Java Documentation for a list of valid protocol names.

The ssl.protocols and socks.ssl.protocols elements are optional, and in general, there is no need to configure either element except to prevent usage of specific TLS/SSL protocols for which a vulnerability has been discovered. A good example is the POODLE attack that exploited a vulnerability in SSLv3.

If you configure these elements, then you must explicitly name the TLS/SSL protocols you want to enable. If you do not configure the ssl.protocols or socks.ssl.protocols element, or you configure either element but do not specify any protocols, then the default value is taken from the underlying JVM. The protocol values are case-sensitive.

Typically, you configure the ssl.protocols or socks.ssl.protocols in the accept-options for inbound requests from clients. You might also specify these elements in the connect-options for an Enterprise Shield™ configuration, although this is less common because Gateway-to-Gateway communication usually occurs in a controlled environment and the TLS/SSL protocol you use is controlled. The ssl.protocols and socks.ssl.protocols elements are more useful in the accept-options when accepting requests from clients that are not in your direct control.

Note: These elements were introduced in Kaazing WebSocket Gateway release 4.0.6 and can be used for configurations running Kaazing WebSocket Gateway 4.0.6 or later releases. For configurations running Kaazing WebSocket Gateway 4.0.5 or earlier releases, you can disable the SSLv3 protocol by disabling SSLv3 ciphers with ><ssl.ciphers>!SSLv3</ssl.ciphers>. See ssl.ciphers for more information.

If you configure the ssl.protocols or the socks.ssl.protocols element to enable SSLv3, but disable SSLv3 cipher suites with the ssl.ciphers or socks.ssl.ciphers elements, then the connection does not occur and the Gateway will not accept SSLv3 connections. Similarly, if you enable TLSv1 with the ssl.protocols or the socks.ssl.protocols element, but disable the TLSv1 ciphers, then the handshake will not succeed and the connection cannot go through.

Example: Simple Configuration Using ssl.protocols to Accept TLSv1, TLSv1.2, and TLSv1.1 Connections

The following example shows a jms.proxy service. Because the accept URL the wss:// scheme, we know that this is a secure connection. The ssl.protocols element in line 12 indicates that we want the Gateway to accept only TLSv1, TLSv1.2, and TLSv1.1 protocols, say, from clients over this secure connection.

<service>
  <name>DMZ Gateway</name>
  <accept>wss://example.com:443/myapp</accept>
    ... 
  <type>jms.proxy</type>

  <properties>
    ... 
  </properties>

  <accept-options>
    <ssl.protocols>TLSv1,TLSv1.2,TLSv1.1</ssl.protocols>
    ... 
  </accept-options>
  
</service>
Example: Enterprise Shield™ Configuration Using socks.ssl.protocols to Accept Reverse Connections on TLSv1.2

This example shows a jms.proxy service in the DMZ configured for Enterprise Shield™, for which the behavior is reversed. Instead of connecting to another host, the Gateway accepts connections instead. Thus, the setting is configured as connect-options in this example. For more information about Enterprise Shield™ and forward and reverse connectivity, see Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

Because this configuration connects a Gateway to another Gateway in a controlled data center, the example only configures the TLSv1.2 protocol for secure connections. For this type of topology we don't expect to make any other kinds of connections.

The prefix for this example is socks.ssl, rather than just ssl to explicitly reference the SSL layer that is transporting the SOCKS protocol.

<service>
  <name>DMZ Gateway</name>
  <accept>wss://example.com:443/myapp</accept>
  <connect>wss://example.com:443/myapp</connect>
    ... 
  <type>jms.proxy</type>

  <properties>
    ... 
  </properties>
  
  <connect-options>
    <http.transport>socks://internal.example.com:1080</http.transport>
	<socks.mode>reverse</socks.mode>
	<socks.transport>ssl://internal.example.com:1080</socks.transport>
	<socks.ssl.protocols>TLSv1.2</socks.ssl.protocols>
  </connect-options>
     ... 	 
</service>
Example: Enterprise Shield™ Configuration Using Both the ssl.protocols and socks.ssl.protocols Elements

This example combines the previous two examples to show an Enterprise Shield™ configuration in which ssl.protocols is specified in the accept-options, and socks.ssl.protocols is specified in the connect-options.

On the frontplane, the Gateway accepts connections from clients only using the TLSv1, TLSv1.2, and TLSv1.1 protocols. On the backplane, the Gateway only accepts (reverse) connections using the protocol TLSv1.2 (from another Gateway).

<service>
  <name>DMZ Gateway</name>
  <accept>wss://example.com:443/myapp</accept>
  <connect>wss://example.com:443/myapp</connect>
    ... 
  <type>jms.proxy</type>

  <properties>
    ... 
  </properties>

  <accept-options>
    <ssl.protocols>TLSv1,TLSv1.2,TLSv1.1</ssl.protocols>
    ... 
  </accept-options>
  
  <connect-options>
    <http.transport>socks://internal.example.com:1080</http.transport>
	<socks.mode>reverse</socks.mode>
	<socks.transport>ssl://internal.example.com:1080</socks.transport>
	<socks.ssl.protocols>TLSv1.2</socks.ssl.protocols>
  </connect-options>
     ... 
	 
</service>

ssl.encryption

Required? Optional; Occurs: zero or one; Values: enabled, disabled

This element allows you to enable or disable TLS/SSL encryption on traffic with the Gateway, turning off TLS/SSL certificate verification for an HTTPS or WSS accept. By default (or if you do not specify ssl.encryption), encryption is enabled for HTTPS and WSS.

For example, if the Gateway is deployed behind a TLS/SSL offloader (a network device designed specifically for handling a company's TLS/SSL certificate traffic), where the incoming traffic to the TLS/SSL offloader is secured over HTTPS and the outgoing traffic from the TLS/SSL offloader to the Gateway is not secure, you can disable encryption so that the Gateway accepts the unsecured traffic on a connection that uses HTTPS/WSS. Basically, the Gateway trusts traffic from the TLS/SSL offloader and therefore the Gateway does not need to verify the connection itself.

You can include the connect-options element on a service that connects over HTTPS or WSS, then disable encryption by setting the ssl.encryption element to disabled. Even when encryption is disabled, the Gateway returns the response as HTTPS/WSS. If you do not include these elements or set the ssl.encryption element to enabled, the Gateway treats incoming traffic on HTTPS or WSS as secure and handles the TLS/SSL certificate verification itself.

See Checklist: Secure Network Traffic with the Gateway for more information about HTTPS/WSS.

The following example for an Enterprise Shield™ topology shows a service element containing several connect-options including an ssl.encryption option that disables encryption.

<service>
  <accept>wss://dmz.example.com:443/remoteService</accept>
  <connect>tcp://internal.example.com:8010</connect>

  <type>jms.proxy</type>
        
  <properties>
    <prepared.connection.count>1</prepared.connection.count>
  </properties>

  <accept-options>
    <ssl.ciphers>DEFAULT</ssl.ciphers>
    <ssl.verify-client>none</ssl.verify-client>
  </accept-options>

  <connect-options>
    <tcp.transport>socks+ssl://dmz.example.com:1443</tcp.transport>
    <socks.mode>reverse</socks.mode>
    <socks.ssl.ciphers>NULL</socks.ssl.ciphers>
    <ssl.encryption>disabled</ssl.encryption>
    <socks.ssl.verify-client>required</socks.ssl.verify-client>     
  </connect-options>
</service>
Notes
  • If you have set up Kaazing WebSocket Gateway behind a TLS/SSL offloader, where the front-end traffic is secure over HTTPS and the back-end traffic behind the TLS/SSL offloader to the Gateway is not secure, then you can disable encryption so that the connection can occur. You can include the connect-options element, then disable encryption by setting the ssl.encryption element to disabled. When encryption is disabled, the Gateway returns the response as HTTPS. If you do not include these elements or set the ssl.encryption element to enabled, the Gateway treats incoming traffic on tcp://internal.example.com as secure and handles the TLS/SSL itself.
  • See Checklist: Secure Network Traffic with the Gateway for more information about HTTPS.

ws.version (deprecated)

Required? Optional; Occurs: zero or more; Where version can be rfc6455 or draft-75

The ws.version element has been deprecated. If you are using an existing configuration that includes the ws.version element, you can continue to use it. However, if the scheme of the URI inside the connect element is ws:// or wss://, then the WebSocket version defaults to rfc6455 and there is no need to explicitly set ws.version.

The ws.version element was used to tell the Gateway which version of the WebSocket protocol to use for the service connections. You would specify this element only if the scheme of the URI inside the connect element is ws: or wss: (to indicate that the WebSocket protocol was being used). If you did not specify the ws.version connect-option, then the WebSocket version would default to rfc6455.

Example

The following example shows addresses for the WebSocket (ws) and WebSocket Secure (wss) protocols and uses WebSocket version draft-75 to connect to a service running on release 3.2 of the Gateway.

  <service>
    <accept>ws://${gateway.hostname}:8000/jms.proxy</accept>
    <connect>wss://${gateway.hostname}:5566/data</connect>
    <connect-options>
      <ws.version>draft-75</ws.version>
    </connect-options>
  </service>
  

protocol.transport

Required? Optional; Occurs: zero or more; Where protocol can be pipe, tcp, ssl, or http.

Use the protocol.transport connect-option to replace the default transport with a new transport. This allows you to change the behavior of the connection without affecting the protocol stack above the transport. For example, a TCP transport normally connects to a remote IP address and port number. However, you could replace that, for instance, with an in-memory (pipe) transport that communicates with another service in the same Gateway.

Specify any of the following transports:

  • http.transport: Specifies a URI for use as a transport layer under the HTTP transport or WebSocket transport (since WebSocket is always over HTTP). This is the most frequently used transport option.
  • ssl.transport: Specifies a URI for use as a transport layer under the TLS/SSL transport.
  • tcp.transport: Specifies a URI for use as a transport layer under the TCP/IP (tcp) transport.
  • pipe.transport: Specifies a URI for use as a transport layer under the pipe transport.
Example

In the following example, the HTTP transport has been replaced with a new (socks+ssl) transport that is capable of doing a reverse connection using the SOCKS protocol over TLS/SSL.

   <service>
     <accept>wss://gateway.example.com:443/path</accept>
     <connect>wss://gateway.example.com:443/path</connect>
     .
     .
     .
     <connect-options>
       <http.transport>socks+ssl://gateway.dmz.net:1080</http.transport>
       <socks.mode>reverse</socks.mode>
       <socks.timeout>2 seconds</socks.timeout>
       <ssl.verify-client>required</ssl.verify-client>      
     </connect-options>
   </service>

For more examples, see Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

socks.mode

Required? Optional; Occurs: zero or one

Use the socks.mode connect-option to initiate the the Gateway connection using the SOCKet Secure (SOCKS) protocol in one of the following modes:

  • forward: initiates forward connectivity from the DMZ Gateway to the internal Gateway on the trusted network. Once connected, a regular full-duplex connection is established. You typically use the forward mode to ensure the SOCKS settings are correctly configured before you attempt to reverse the connection.
  • reverse: configures the connection mode in reverse so that the connection is initiated from the internal Gateway on the trusted network to the DMZ Gateway to allow a connection between the client and server that is otherwise blocked by the firewall. With the reverse mode, the Gateway interprets accept URIs as connect URIs.

For more information about both forward and reverse connectivity, see Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

Example

The following example shows a service element with the socks.mode set to reverse, and thus tells the Gateway to interpret the SOCKS URI as a connect URI, as shown in lines 8 and 9:

<service>
  <accept>tcp://dmz.example.com:8000/</accept>
  <connect>pipe://pipe-1</connect>

  <type>jms.proxy</type>

  <connect-options>
    <pipe.transport>socks+ssl://dmz.example.com:1443</pipe.transport>
    <socks.mode>reverse</socks.mode>
  </connect-options>
</service>

socks.timeout

Required? Optional; Occurs: zero or one

Use the socks.timeout connect-option to specify the length of time (in seconds) to wait for a SOCKS connection to form before closing the connection. If you do not specify socks.timeout for your Gateway configuration, then a timeout is not enforced.

You must set socks.timeout to be longer than socks.retry.maximum.interval to ensure a connection does not fail because it does not wait long enough for the retry interval from the trusted, internal gateway to the DMZ gateway.

Note the following behavior for reverse and forward SOCKS connections:

  • For reverse connections (socks.mode is set to reverse), the time you specify for socks.timeout determines how long pending connection requests on the DMZ Gateway wait for the internal Gateway to initiate a reverse connection.

    Connect requests are queued until the internal Gateway pulls the requests from the queue and consumes them. If the connect requests are not consumed within the specified time, then the connection to the client times out and is closed.

  • For forward connections (socks.mode is set to forward), the time you specify for socks.timeout determines how long to wait for confirmation that the connection succeeded.

    If the network connection or the SOCKS handshake does not succeed within the time specified by socks.timeout, then the connection to the client fails and the connection is closed.

A best practice recommendation is to use the wsn:// scheme or wsn+ssl:// scheme (WebSocket Native and SSL) for secure connections. The wsn:// scheme instructs the Gateway to only initiate or accept native WebSocket connections. Normally, when communication with clients, a ws:// or wss:// scheme is used. That will attempt native WebSocket connectivity, but will fallback to emulation if required to ensure successful connectivity.

However, between the internal and DMZ Gateways it is a controlled network so you should use native WebSocket. If a connection fails, using wsn:// forces a retry of a native WebSocket connection rather than attempting to fallback to emulation.

Example

The following example shows a socks.timeout that is set to 10 seconds in line 15. If the forward connection is not formed within 10 seconds, then the connection is closed and the client must initiate another connection.

<service>
  <accept>wss://www.example.com:443/remoteService</accept>
  <connect>tcp://localhost:61613</connect>

  <type>jms.proxy</type>

  <accept-options>
    <ssl.ciphers>DEFAULT</ssl.ciphers>
    <ssl.verify-client>none</ssl.verify-client>
  </accept-options>

  <connect-options>
    <pipe.transport>socks+ssl://dmz.example.com:1443</pipe.transport>
    <socks.mode>reverse</socks.mode>
    <socks.timeout>10 sec</socks.timeout>
  </connect-options>
</service>

socks.ssl.ciphers

Required? Optional; Occurs: zero or one; Values: cipher strings and cipher suite names for OPENSSL and Java 7.

Use socks.ssl.ciphers to list the encryption algorithms used by TLS/SSL on the secure connection (WSS, HTTPS or SSL). By default (or if you do not specify this element on a secure connection), the Gateway uses HIGH,MEDIUM,!ADH,!KRB5.

Example

The following example shows a jms.proxy service accepting a secure connection over WSS and connecting to the back-end server over TCP with the ciphers used by the encryption algorithm specified in ssl.ciphers.

<service>
  <accept>wss://www.example.com:443/remoteService</accept>
  <connect>tcp://localhost:61613</connect>

  <type>jms.proxy</type>

  <accept-options>
    <ssl.ciphers>DEFAULT</ssl.ciphers>
    <ssl.verify-client>none</ssl.verify-client>
  </accept-options>

  <connect-options>
    <ssl.ciphers>LOW</ssl.ciphers>
  </connect-options>
</service>
Example for SOCKS Ciphers

The following example shows a jms.proxy service for the DMZ Gateway in an Enterprise Shield™ topology. The Gateway receives secure client connections (wss://) and specifies the ciphers used on the accept URI (DEFAULT), but does not require mutual verification from the clients (ssl.verify-client). In addition, the internal Gateway connects over SOCKS and TLS/SSL (socks+ssl://) to the DMZ Gateway, specifies the ciphers used (NULL), and requires mutual verification (socks.ssl.verify-client). For more information about the internal Gateway and reverse connectivity, see Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

<service>
  <accept>wss://dmz.example.com:443/remoteService</accept>
  <connect>tcp://internal.example.com:8010</connect>

  <type>jms.proxy</type>
        
  <properties>
    <prepared.connection.count>1</prepared.connection.count>
  </properties>

  <accept-options>
    <ssl.ciphers>DEFAULT</ssl.ciphers>
    <ssl.verify-client>none</ssl.verify-client>
  </accept-options>

  <connect-options>
    <tcp.transport>socks+ssl://dmz.example.com:1443</tcp.transport>
    <socks.mode>reverse</socks.mode>
    <socks.ssl.ciphers>NULL</socks.ssl.ciphers>
    <socks.ssl.verify-client>required</socks.ssl.verify-client>     
  </connect-options>
</service>

Note: For configurations running Kaazing WebSocket Gateway 4.0.5 or earlier releases, you can disable the SSLv3 protocol by configuring SSLv3 ciphers using <socks.ssl.ciphers>!SSLv3<socks.ssl.ciphers>.

socks.ssl.verify-client

Required? Optional; Occurs: zero or one; Values: required, optional, none

In an Enterprise Shield™ topology over socks+ssl://, the DMZ Gateway provides the internal Gateway with a digital certificate that the internal Gateway uses to verify the DMZ Gateway’s identity before establishing the secure connection. For added security, you can use the socks.ssl.verify-client option on the DMZ Gateway to require that the internal Gateway provide a digital certificate to establish a secure connection. This configuration ensures that both the DMZ Gateway and internal Gateway are verified via TLS/SSL before transmitting data, establishing mutual verification.

If you configure the socks.ssl.verify-client option with the value ... Then ...
required

A certificate is required. The DMZ Gateway requires that the client connecting from the internal Gateway over the SOCKS transport must provide a digital certificate to verify the client’s identity. After the DMZ Gateway has verified the client certificate, then the reverse connection can be formed.

optional

A certificate is not required, but if a client provides a certificate then the DMZ Gateway attempts to verify it. If the verification fails, then the client is not allowed to connect.

none The client recognizes that a certificate is not required and it does not send a certificate. All clients can connect to the secure service on the DMZ Gateway.

For more information, see Checklist: Configure Enterprise Shield™ for Kaazing WebSocket Gateway.

Example

In the following example, the DMZ Gateway accepts on a WebSocket URI and connects over a named pipe. The DMZ Gateway also listens for connections on port 1443 as pipe.transport URI over SOCKS and TLS/SSL (socks+ssl://). To increase security, the socks.ssl.verify-client is set to required, which specifies that the internal Gateway URI must provide a digital certificate to the DMZ Gateway.

<service>
  <accept>wss://dmz.example.com:443/remoteService</accept>
  <connect>pipe://pipe-1</connect>

  <type>jms.proxy</type>
        
  <properties>
    <prepared.connection.count>1</prepared.connection.count>
  </properties>

  <accept-options>
    <ssl.ciphers>DEFAULT</ssl.ciphers>
    <ssl.verify-client>none</ssl.verify-client>
  </accept-options>

  <connect-options>
    <pipe.transport>socks+ssl://dmz.example.com:1443</pipe.transport>
    <socks.mode>reverse</socks.mode>
    <socks.ssl.ciphers>NULL</socks.ssl.ciphers>
    <socks.ssl.verify-client>required</socks.ssl.verify-client>     
  </connect-options>
</service>
Notes
  • If you have set up Kaazing WebSocket Gateway behind a TLS/SSL offloader, where the front-end traffic is secure over HTTPS and the back-end traffic behind the TLS/SSL offloader to the Gateway is not secure, then you can disable encryption so that the connection can occur. You can include the accept-options element, then disable encryption by setting the ssl.encryption element to disabled. When encryption is disabled, the Gateway returns the response as HTTPS. If you do not include these elements or set the ssl.encryption element to enabled, the Gateway treats incoming traffic on www.example.com:443 as secure and handles the TLS/SSL itself.
  • See Checklist: Secure Network Traffic with the Gateway for more information about HTTPS.
  • See Configure Enterprise Shield™ to learn how to require the internal Gateway to provide TLS/SSL certificates.
  • You must set socks.ssl.verify-client to required if using OCSP. See Implement Certificate Revocation Using OCSP for more details about setting up OCSP with the Gateway.

ws.inactivity.timeout

Required? Optional; Occurs: zero or one

Specifies the maximum number of seconds that the network connection can be inactive (seconds is the default time interval syntax). The Gateway will drop the connection if it cannot communicate with the client in the number of seconds specified (see ws.inactivity.timeout). You can specify your preferred time interval syntax in milliseconds, seconds, minutes, or hours (spelled out or abbreviated). For example, all of the following are valid: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit then seconds are assumed. An inactive connection can result from a network failure (such as a lost cellular or Wi-Fi connection) that prevents network communication from being received on any established connection. Thus, when ws.inactivity.timeout is set to a nonzero time interval, the Gateway will drop an inactive connection if the specified number of seconds pass with no communication from the client.

Important: The values for http.keepalive.timeout and ws.inactivity.timeout should be the same.

Some use cases for the ws.inactivity.timeout property include:

  • Detect a lost cellular (or Mobile) connection or a lost Wi-Fi connection.
  • Detect a half-closed connection over WebSocket, such as a silent network failure over WebSocket between Gateways.
  • Detect a network failure between the DMZ and Internal Gateway over WebSocket, such as for an Enterprise Shield™ topology using forward and reverse connectivity.
Example

In the following example, the ws.inactivity.timeout property specifies that if the Gateway cannot communicate with a client over the past five-seconds, then the connection to that client will be dropped.

<service>
  <accept>ws://gateway.example.com/echo</accept>
  <connect>ws://internal.example.com/echo</connect>

  <type>echo</type>

 <connect-options>
   <ws.inactivity.timeout>5s</ws.inactivity.timeout>
 </connect-options>
   .
   .
   .
</service>
Notes
  • Set the time interval to a value that is at least double the expected maximum network round-trip time between the Gateway and any client. Otherwise, clients may be disconnected unexpectedly.
  • You can specify your preferred time interval syntax in milliseconds, seconds, minutes, or hours (spelled out or abbreviated). For example, all of the following are valid: 1800s, 1800sec, 1800 secs, 1800 seconds, 1800seconds, 3m, 3min, or 3 minutes. If you do not specify a time unit then seconds are assumed.

notify-options

Required? Required for Apple Push Notification Service (APNs); Occurs: zero or one

Specify notify-options for the notify element when using Apple Push Notification Service (APNs) to push notifications to iOS devices on which the Gateway iOS application (Objective C clients) is installed. See also the notify element.

Note:

The notify-options must be specified in the order shown in the following table.

notify-options Required? Description
apns.notify.transport Required*

*This property is required for APNs.

The apns.notify.transport option is a URI containing the Apple scheme and connection data for pushing notifications to remote iOS devices. Push notifications, also known as remote notifications, are sent by the Gateway to Apple Push Notification Service, which pushes the notification to iOS devices on which the Gateway iOS app is installed.

The apns.notify.transport option is required for APNs.

apns.feedback.transport Required*

*This property is required for APNs.

The apns.notify.transport option is a URI containing the scheme and connection data for the Apple Feedback Service, a companion service to APNs, to know when to stop sending notifications to particular devices.

The apns.feedback.transport option is required for APNs.

ssl.ciphers Optional

Lists the cipher strings and cipher suite names used by the secure connection. The ssl.ciphers option is not required for APNs and is used to specify the TLS/SSL cipher suites to use when talking to Apple.

tcp.transport Optional The tcp.transport option is not required for APNs. It is used only to handle cases where the connection out to Apple needs to happen via a forward SOCKS connection (specified using the socks.mode accept-option).

Notes

  • For APNs functionality, the apns.notify.transport and apns.feedback.transport elements are required. The Gateway will not accept the device token from an iOS application if these elements are not present in the Gateway configuration.
  • For a complete example of the notify element with the notify-options, see Example Configuration for the notify Element earlier in this topic.
  • To configure the Gateway and its iOS (Objective-C) client applications to use the Apple Push Notification Service (APNs), see the step-by-step checklist Checklist: Deploy APNs with Kaazing WebSocket Gateway. The Gateway supports APNs push notifications for APNs-enabled clients that are connected to a jms service (possibly through a jms.proxy service).

realm-name

The name of the security realm used for authorization.

Example

<service>
  <accept>wss://localhost:9000/kerberos5</accept>
  <connect>tcp://kerberos.example.com:88</connect>
  <type>kerberos5.proxy</type>
  <realm-name>demo</realm-name>
    .
    .
    .
</service>

Notes

  • If you do not configure realm-name, then authentication and authorization are not enforced for the service.

auth-constraint

This element has been deprecated. Use the authorization-constraint element instead. 

authorization-constraint

Required? Optional; Occurs: zero or more

Use the authorization-constraint element to configure the user roles that are authorized to access the service. authorization-constraint contains the following subordinate element:

Subordinate Element Description
require-role The name of the user role to be included in the authorization-constraint or * to indicate any valid user

Example

The following example of a jms.proxy service element is configured with an authorization-constraint, as shown in lines 7 to 9:

<service>
  <accept>ws://localhost:8000/remoteService</accept>
  <connect>tcp://localhost:61613</connect>

  <type>jms.proxy</type>

  <authorization-constraint>
    <require-role>AUTHORIZED</require-role>
  </authorization-constraint>
</service>

mime-mapping

Required? Optional; Occurs: zero or more

The mime-mapping element defines the way the Gateway maps a file extension to a MIME type. See the the main description for mime-mapping (service-defaults). You can override the default configuration or add a new MIME type mapping for a particular service by adding a mime-mapping element to the service entry. You can only add mime-mapping elements immediately before any cross-site constraints for a service.

Example

The following example shows a directory service that includes two mime-mapping elements for files with the PNG and and HTML extensions. The Gateway sets the content or MIME type for files with the PNG extension as a PNG image and files with the HTML extension as an HTML text file:

<service>
  <accept>ws://localhost:8000</accept>
  <accept>wss://localhost:9000</accept>

   <type>directory</type>

  <accept-options>
    <ws.bind>8001</ws.bind>
    <wss.bind>9001</wss.bind>
  </accept-options>

  <mime-mapping>
    <extension>png</extension>
    <mime-type>image/png</mime-type>
  </mime-mapping>
  <mime-mapping>
    <extension>html</extension>
    <mime-type>text/html</mime-type>
  </mime-mapping>

  <cross-site-constraint>
  <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
  <cross-site-constraint>
    <allow-origin>https://localhost:9000</allow-origin>
  </cross-site-constraint>
  </service>

Notes

  • If your client does not properly render a file type as expected, ensure that the MIME type is properly mapped and that you do not have multiple entries for the same extension type within the same section.
  • If two or more mime-mapping entries for the same extension are given in a single service or in service-defaults, then the Gateway applies the last mime-mapping entry. That is, within a given service or service-defaults section, the Gateway applies the mime-mapping entry closest to the end of the service (or service-defaults) section.

cross-site-constraint

Required? Optional; Occurs: zero or more

Use cross-site-constraint to configure how a cross-origin site is allowed to access a service. cross-site-constraint contains the following subordinate elements:

Subordinate Element Description
allow-origin

Specifies the cross-origin site or sites that are allowed to access this service:

  • To allow access to a specific cross-site origin site, specify the protocol scheme, fully qualified host name, and port number of the cross-origin site in the format: <scheme>://<hostname>:<port>

    For example: <allow-origin>http://localhost:8000</allow-origin>.

  • To allow access to all cross-site origin sites, including connections to gateway services from pages loaded from the file system rather than a web site, specify the value *.

    For example: <allow-origin>*</allow-origin>.

    Specifying * may be appropriate for services that restrict HTTP methods or custom headers, but not the origin of the request.

allow-methods A comma-separated list of methods that can be invoked by the cross-origin site. For example: <allow-methods>POST,DELETE</allow-methods>.
allow-headers A comma-separated list of custom header names that can be sent by the cross-origin site when it accesses the service. For example, <allow-headers>X-Custom</allow-headers>.

Example

The following example of a jms.proxy service element includes a cross-site-constraint (as shown in lines 11-13), allowing access to the back-end service by the site http://localhost:8000 (note the different port number).

<service>
  <accept>ws://localhost:8001/remoteService</accept>
  <connect>tcp://localhost:61613</connect>

  <type>jms.proxy</type>

  <authorization-constraint>
    <require-role>AUTHORIZED</require-role>
  </authorization-constraint>

  <cross-site-constraint>
    <allow-origin>http://localhost:8000</allow-origin>
  </cross-site-constraint>
</service>

Notes

  • Cross-site access to back-end services is denied by default. However, by defining a cross-site constraint, you can override the default behavior and effectively "white-list" cross-origin sites.

Summary

In this document, you learned about the Gateway service element and how to specify it in your Gateway configuration file. For more information about the location of the configuration files and starting the Gateway, see Setting Up Kaazing WebSocket Gateway. For more information about Kaazing WebSocket Gateway administration, see the documentation.

TOP