RTI Web Integration Service

2 Starting Web Integration Service

Web Integration Service runs as a separate application. The script to run the executable is in <NDDSHOME>/bin.

To start Web Integration Service, enter:

$ <NDDSHOME>/bin/rtiwebintegrationservice [options]

For example (note: you would enter this all on one line):

$ <NDDSHOME>/bin/rtiwebintegrationservice \
    -cfgFile example.xml \
    -cfgName example

Table 1 describes in detail the list of command-line options.

4 Web Integration Service Command-Line Options

The following table describes all the command-line options available in Web Integration Service. They are all optional, except for -cfgName.

Option	Description
`-accessLogFile <file>`	Path to the web server's access log. Default: NULL (nothing gets logged).
`-aclFile <file>`	Access Control List file. This parameter loads an Access Control List file, which enables access control in all the HTTP requests. It is recommended to use this parameter with a secured connection, i.e., it is important to enable HTTPS in every single `-listeningPort` and provide an `-sslCertificate`. Default: Do not load an ACL file and therefore do not check for any kind of access key in HTTP requests.
`-cfgFile <file>`	Specifies a configuration file to be loaded. See How to Load the XML Configuration in the Configuration Chapter.
`-cfgName <name>`	Required. Specifies a configuration name. Web Integration Service will look for a matching `<web_integration_service>` tag in the configuration file specified via the `-cfgFile` parameter and in the default configuration files listed in the Configuration Chapter.
`-createAPIKey <description>`	Adds a new API key to an Access Control List file along with a description of the purpose of the API key to be generated. This command must be used in combination with the `-aclFile` argument to specify the file in which to add the API key. If the file does not exist, Web Integration Service will automatically create it for you. Once the key is added to the ACL file, Web Integration Service exits.
`-deleteAPIKey <key>`	Deletes an API key from an Access Control List file. This command must be used in combination with the `-aclFile` argument to specify the file from which the API key will be deleted. Once the key is deleted from the ACL file, Web Integration Service exits.
`-documentRoot <dir>`	Directory that will be served by Web Integration Service's web server on `http[s]://<hostname>:<listening_port>`. Default: Documentation directory.
`-enableKeepAlive <yes or no>`	Allows clients to reuse TCP connections for subsquent HTTP requests, which improves performance. It is important to add the correct Content-Length HTTP header for each request. Otherwise, the client will timeout. Default: no.
`-help`	Displays help information.
`-listAPIKeys`	Lists all the API keys available in an Access Control List file. This command must be used in combination with the `-aclFile` argument to specify the file from which API keys should be listed.
`-listeningPorts <list_of_ports>`	Comma-separated list of ports to listen on. To enable HTTPS on a specific port, append `'s'` to the port number. For example, if you specify `"8080,443s"`, Web Integration Service will listen on port 8080 using HTTP and port 443 using HTTPS. If any of the ports has SSL enabled, `-listeningPorts` must be used in combination with `-sslCertificate` to indicate the path to the certificate file that will be used. Default: 8080 (HTTP)
`-numThreads <n>`	Number of worker threads for the web server. The web server handles each incoming connection in a separate thread. Therefore, the value of this option is effectively the number of connections that can be handled. Default: 50
`-sslCertificate <file>`	Path to the SSL certificate file. This option is only required when one of the `-listeningPorts` has enabled SSL. The file must be in PEM format and must contain both the private key and the certificate. For more information on how to configure HTTPS and authentication, see Section 5. Default: NULL.
`-verbosity <n>`	Controls what type of messages are logged: Silent Exceptions (Connext DDS and Web Integration Service) Warnings (Web Integration Service) Information (Web Integration Service) Warnings (Connext DDS and Web Integration Service) Tracing (Web Integration Service) Tracing (Connext DDS and Web Integration Service) Each verbosity level, `n`, includes all the verbosity level smaller than `n`.
`-version`	Prints the Web Integration Service version number.

Table 1: RTI Web Integration Service Command-line Options

5 Authentication and Access Control Mechanisms

Web Integration Service supports a simple access control mechanism that can be enabled to restrict access to its REST API. It is based on a set of API keys that authorize client applications to perform operations over the HTTPS protocol. When access control is enabled, client applications without an authorized API key are rejected and are not allowed to perform any operation on the running instance.

To enable Access Control, we recommend that you enable HTTPS to secure the transmission of API keys and data. While HTTPS can be enabled for all kinds of applications—even when access control is not a requirement—API keys should never be exchanged over simple HTTP as malicious applications could extract the API key, which should be considered a secret.

Section 5.1 explains how to enable HTTPS in Web Integration Service, Section 5.2 describes the Access Control List file, Section 5.3 illustrates how to manage the Access Control List file, and Section 5.4 explains how to configure client applications to use the generated API keys.

5.1 Enabling HTTPS

To secure the transmission of API keys and the data exchanged between client applications and Web Integration Service, information must be exchanged via HTTPS.

To enable HTTPS, all the ports specified in the -listeningPorts command-line option must add a trailing "s" to the port number and provide an SSL certificate (which must include the private key). For example:

$ <NDDSHOME>/bin/rtiwebintegrationservice -listeningPorts 8080s \
    -sslCertificate ~/.certificates/server.pem

The trailing "s" (that is, using 8080s instead of 8080) indicates that HTTPS must be used on every port it follows. In contrast, ports specified without a trailing "s" will use HTTP.

Unlike other popular web servers, Web Integration Service's web server requires users to combine both the actual certificate and the RSA private key section in the same file.

For example, Apache uses the SSLCertificateFile and SSLCertificateKeyFile parameters to configure certificates and keys. Nginx uses also two different parameters: ssl_certificate and ssl_certificate_key.

Assuming the original certificate is stored in a file called server.crt and the private key is in a file called server.key, these certificates need to be combined in a common PEM file (which in this example we call server.pem) as follows:

$ cat server.crt > server.pem
$ cat server.key >> server.pem

In some cases, certificate authorities provide two different certificates, one for the domain and one for a certificate from the appropriate certificate authority (e.g., DigiCert). In that case, all certificates and keys can be combined as follows:

$ cat star_dot_example_dot_com.crt > server.pem
$ cat DigiCertCA.crt >> server.pem
$ cat star_dot_example_dot_com.key  >> server.pem

5.2 The Access Control List file

To enable access control, users need to provide an Access Control List (ACL) file when starting the service. The -aclFile command-line option specifies the path to the ACL file and configures the service to reject HTTP requests from clients that do not provide a valid API key (i.e., an API key included in the Access Control List file the service was started with).

If the file specified in -aclFile does not exist, Web Integration Service will create an empty file that can be populated later on with the -createAPIKey and -deleteAPIKey command-line options.

The Access Control List is a Sqlite3 database with a single table that contains all the API keys, a message describing each API key, and the date when they were added to the file.

5.3 Creating, Deleting, and Listing API keys

The rtiwebintegrationservice executable can be used to dynamically create, delete, and list API keys. If the file that is being updated is in use by any Web Integration Service instance, the service will be automatically notified of the changes in it. Then it will reload the list of valid API keys accordingly.

5.3.1 Creating API Keys

To add a new API key to an ACL file, use the -createAPIKey and -aclFile command-line options as follows:

$ <NDDSHOME>/bin/rtiwebintegrationservice \
 -createAPIKey "API Key for ShapesDemo client" \
 -aclFile ~/.acl/acl_file.db

If the ACL file does not exist, it will automatically be created. Note that a message identifying the API key must be passed to the -createAPIKey argument.

5.3.2 Deleting API Keys

To delete an API key from an ACL file, use the -deleteAPIKey and -aclFile command-line options as follows:

$ <NDDSHOME>/bin/rtiwebintegrationservice \
 -deleteAPIKey "r5x/ERs9wGkIufffeRfWSFH1li/60BUoJmJ0ETua" \
 -aclFile ~/.acl/acl_file.db

5.3.3 Listing API Keys

To list the API keys in an ACL file, use the -listAPIKeys and -aclFile command-line options as follows:

$ <NDDSHOME>/bin/rtiwebintegrationservice \
 -aclFile ~/.acl/acl_file.db \
 -listAPIKeys

5.4 Using API Keys in Client Applications

Client applications communicating with access-control-limited instances of Web Integration Service must include a valid API key in the OMG-DDS-API-Key header field of every HTTP request. The API key must remain secret. Therefore, clients should only share it through a secure connection and should not expose it to users of the client application.

Section 2 of the REST API documentation provides a complete overview of the HTTP headers involved in operations supported by Web Integration Service's REST API.

Usage

1 Running Web Integration Service