### Navigation

- index
- next |
- previous |
- Secure Networking Guide »

# 3. Secure Networking Configuration

This section provides an in-depth description of the OpenSplice security configuration by describing the most important configuration parameters for the Secure Networking Service.

Each configuration parameter will be explained by means of an extensive description together with the tabular summary that contains the following information:

Full path -
  Describes the location of the item within a complete configuration. Because the configuration is in XML format, an XPath expression is used to point out the name and location of the configuration item.
Format -
  Describes the format of the value of the configuration item.
Dimension -
  Describes the unit for the configuration item (for instance seconds or bytes).
Default value -
  Describes the default value that is used by the service when the configuration item is not set in the configuration.
Valid values -
  Describes the valid values for the configuration item. This can be a range or a set of values.

If the configuration parameter is an XML attribute, the table also contains the following information:

Required -
  Describes whether the attribute is required or if it is optional.

If the configuration parameter is an XML element, the table also contains the following information:

Occurrences -
  Describes the range of the possible number of occurrences of the element in the configuration by specifying the minimum and maximum number of occurrences.

## 3.1. Activating Secure Networking

The OpenSplice Security Service comes as a separate service, replacing the regular networking service.

The secure networking service executable is named `snetworking` on Linux and Solaris and `snetworking.exe` on Windows.

It needs to be configured in the OpenSplice configuration XML file (see below). In addition, a license is required to enable the OpenSplice Secure Networking feature; if a license is not found then an error message is printed and the service will not start.

### 3.1.1. Configuring the Secure Networking Service

OpenSplice services are configured in an OpenSplice configuration file, which is located in `<OSPL_HOME>/etc/configs/ospl.xml` by default.

Within this configuration file the `<Domain>` element contains a set of Service child elements, which are responsible for starting services like durability or networking. The default configuration file already contains a `<Service>` element starting the networking service. To configure secure networking only the name of the service’s executable in the `<Command>` child element needs to be replaced with the value `snetworking`.

The following snippet shows an example of an OpenSplice configuration starting secure networking service:

    <OpenSplice>
        <Domain>
            <Name>OpenSplice Security</Name>
            <Database>
                <Size>10485670</Size>
            </Database>
            <Lease>
                <ExpiryTime update_factor="0.5">5.0</ExpiryTime>
            </Lease>
            <Service enabled="true" name="networking">
                <Command>snetworking</Command>
            </Service>
        </Domain>
        ...
    </OpenSplice>

To check if the service starts correctly the info logfile `ospl-info.log` can be inspected (see also How to Diagnose Problems - Logging ).

## 3.2. Secure Networking Configuration Elements

The secure networking configuration expects a root element named `OpenSplice/NetworkingService`. Within this root element, the networking daemon will look for several sub-elements.

The configuration elements for secure networking are listed and explained below.

These elements are an extension of the configuration elements for the Networking Service described in the Vortex OpenSplice Deployment Guide and the Vortex OpenSplice Configuration Guide.

### 3.2.1. Element GlobalPartition

This element specifies the global or default networking partition.

#### 3.2.1.1. Attribute SecurityProfile

In the context of secure networking, the `GlobalPartition` element provides support for the attribute `SecurityProfile`. The attribute is referencing a security profile declared in the context of the `Security` element.

If the given reference is invalid, the global partition configuration is invalid. In this case, the partition will be blocked to prevent unwanted information leaks. A configuration error message will be logged to the `ospl-error.log` file. If the security feature has been enabled, but no profile is declared, then the `NULL` profile is used by default: this means that no security is added to the transport (see Attribute Enabled).

Full Path | OpenSplice/NetworkService/Partitioning/GlobalPartition[@SecurityProfile]
Format | string
Dimension | none
Default Value | none
Valid Values | any
Required | no
Remarks | This attribute is referencing a security profile declared in the context of the Security element.

### 3.2.2. Element NetworkPartition

The Networking configuration can contain a set of networking partitions, which are defined in the context of the `NetworkPartitions` element.

#### 3.2.2.1. Attribute SecurityProfile

In the context of secure networking, the `NetworkPartition` element provides support for the attribute `SecurityProfile`. The attribute is referencing a security profile declared in the context of the `Security` element.

If the given reference is invalid, the network partition configuration is invalid. In this case the partition will be blocked to prevent unwanted information leaks. A configuration error message will be logged to the `ospl-error.log` file. If the security feature has been enabled but no profile is declared, the `NULL` profile will be used by default.

The ordering of network partition declarations in the OSPL configuration file must be the same for all nodes within the OpenSplice domain.

If certain nodes shall not use one of the network partitions, the network partition in question must be declared as `connected="false"`. In this case the declared security profile would not be evaluated or initialized, and the associated secret cipher keys need not to be defined for the OpenSplice node in question.

Full Path | OpenSplice/NetworkService/NetworkPartitions/NetworkPartition[@SecurityProfile]
Format | string
Dimension | none
Default Value | none
Valid Values | any
Required | no
Remarks | This attribute is referencing a security profile declared in the context of the Security element.

### 3.2.3. Element Security

The `Security` section defines the parameters relevant for secure networking. Declaring this element in the OSPL configuration file will activate the secure networking feature.

Without any additional security settings, all network partitions of the node would use the `NULL` cipher encoding. If confidentiality and integrity is required for a network partition, the network partition must be associated with a security profile (see Element SecurityProfile).

#### 3.2.3.1. Attribute Enabled

This is an optional attribute.

If not defined it defaults to `true` and all network partitions, if not specified otherwise, will be encoded using the `NULL` cipher. The NULL cipher does not provide for any level of integrity or confidentiality, and message items will be sent unencrypted.

If `enabled="false"` the security feature will not be activated, and the node acts like any other OpenSplice node not being security-aware. Security profiles defined in the configuration file will not take effect, but will cause the system to log warnings.

Full Path | OpenSplice/NetworkService/Security[@Enabled]
Format | Boolean
Dimension | none
Default Value | true
Valid Values | true, false
Required | no
Remarks | This attribute is a flag to enable or disable the secure networking.

### 3.2.4. Element SecurityProfile

This element defines the security profile which can be applied to one or more network partitions. This element is optional.

#### 3.2.4.1. Attribute Name

This is a mandatory attribute. The name must be unique for all Security Profiles being declared. If the name is not specified, the security profile will be ignored as it cannot be referenced anyway.

Full Path | OpenSplice/NetworkService/Security[@Enabled]
Format | string
Dimension | none
Default Value | none
Valid Values | any, but must be unique amongst all other SecurityProfiles
Required | yes
Remarks | This is a required attribute. The given name can be referenced by NetworkPartition and GlobalPartition elements.

#### 3.2.4.2. Attribute Cipher

This is a mandatory attribute. Depending on the declared cipher, the cipher key must have a specific length, 128 bits, 192 bits, 256 bits or none at all. The following case-insensitive values are supported by the current implementation:

- aes128, implements AES cipher with 128 bit cipher-key (16 Bytes, 32 hexadecimal characters). This cipher will occupy 34 bytes of each UDP packet being sent.
- aes192, implements the AES cipher with 192 bit cipher-key (24 Bytes, 48 hexadecimal characters). This cipher will occupy 34 bytes of each UDP packet being sent.
- aes256, implements the AES cipher with 256 bit cipher-key (32 Bytes, 64 hexadecimal characters. This cipher will occupy 34 bytes of each UDP packet being sent.
- blowfish, implements the Blowfish cipher with 128 bit cipher-key (16 Bytes, 32 hexadecimal characters). This cipher will occupy 26 bytes of each UDP packet being sent.
- null, implements the `NULL` cipher. The only cipher that does not require a cipher-key. This cipher will occupy 4 bytes of each UDP packet being sent.

All ciphers except for the `NULL` cipher are combined with SHA1 to achieve data integrity. Also, the rsa- prefix can be added to the ciphers. In this case, digital signatures using RSA will be available.

Full Path | OpenSplice/NetworkingService/Security/SecurityProfile[@Cipher]
Format | enumeration
Dimension | none
Default Value | none
Valid Values | aes128, aes192, aes256, blowfish, rsa-aes128, rsa-eas192, rsa-eas256, rsa-blowfish, rsa-null, NULL
Required | yes
Remarks | All but NULL cipher require attribute CipherKey to be set with matching key length.

#### 3.2.4.3. Attribute CipherKey

The `CipherKey` attribute is used to define the secret key required by the declared cipher. The value can be a URI referencing an external file containing the secret key, or the secret key can be defined in-place directly as a string value. The key must be defined as a hexadecimal string, each character representing 4 bits of the key; for example, `1ABC` represents the 16-bit key `0001 1010 1011 1100`. The key must not follow a well-known pattern and must match exactly the key length required by the chosen cipher. If the cipher-keys are malformed, the security profile in question will be marked as invalid. Moreover, each network partition referring to the invalid Security Profile will not be operational and thus traffic will be blocked to prevent information leaks.

As all OpenSplice applications require read access to the XML configuration file, for security reasons it is recommended to store the secret key in an external file in the file system, referenced by the URI in the configuration file. The file must be protected against read and write access from other users on the host. Verify that access rights are not given to any other user or group on the host.

Alternatively, storing the secret key in-place in the XML configuration file will give read/write access to all DDS applications joining the same OpenSplice node. Because of this, the ‘in-place’ method is strongly discouraged.

Full Path | OpenSplice/NetworkingService/Security/SecurityProfile[@CipherKey]
Format | string
Dimension | none
Default Value | none
Valid Values | Hexadecimal string or file URI matching the pattern: `file://.*`.
Required | yes
Remarks | All but NULL cipher require attribute CipherKey to be set with matching key length.

### 3.2.5. Element AccessControl

The optional `AccessControl` element defines settings for access control enforcement and which access control module shall be used.

#### 3.2.5.1. Attribute enabled

The access control feature will be activated when `enabled="true"`.

Full Path | Security/AccessControl[@enabled]
Format | Boolean
Dimension | none
Default Value | false
Valid Values | false, true

#### 3.2.5.2. Attribute policy

The `policy` attribute references a file containing the access control policy. Configuration elements of this file are explained in detail in Access Control Policy Elements.

Full Path | Security/AccessControl[@policy]
Format | file URI, also see Attribute CipherKey
Dimension | none
Default Value | none
Valid Values | any

### 3.2.6. Element AccessControlModule

The `AccessControlModule` element defines which access control module will be used. More than one module may be defined. All defined and enabled modules will be used to determine if access should be granted.

#### 3.2.6.1. Attribute enabled

The module specified in the `type` attribute is used to evaluate access control rules when `enabled="true"`.

Full Path | Security/AccessControl/AccessControlModule[@enabled]
Format | Boolean
Dimension | none
Default Value | true
Valid Values | true, false

#### 3.2.6.2. Attribute type

The `type` attribute defines the access control model type.

OpenSplice currently only supports mandatory access control, accordingly the only valid value for this attribute is `"MAC"`.

Full Path | Security/AccessControl/AccessControlModule[@enabled]
Format | string
Dimension | none
Default Value | none
Valid Values | “MAC”
Remarks | This value is referencing an access control module.

### 3.2.7. Element Authentication

The optional `Authentication` element defines whether additional sender authorization shall be performed. Enabling Authentication requires that a cipher, including RSA (such as rsa-aes256), is used.

#### 3.2.7.1. Attribute enabled

Authentication is performed when `enabled` is set to `true`.

Full Path | Security/Authentication[@enabled]
Format | Boolean
Dimension | none
Default Value | none
Valid Values | true, false

#### 3.2.7.2. Element X509Authentication

The `X509Authentication` element defines where keys and certificates required for X509 authentication may be found.

##### 3.2.7.2.1. Element Credentials

The `Credentials` element is an optional element. If it is missing, then the node does not sign messages (in other words, does not send credentials).

###### 3.2.7.2.1.1. Element Key

The `Key` element references the file containing the key.

Full Path | Security/Authentication/X509Authentication/Credentials/Key
Format | string
Dimension | none
Default Value | none
Valid Values | any file URI
Occurrences (min-max) | 1 - 1
Remarks | It is recommended that the absolute path is used. A relative path will be interpreted relative to the directory from which the OpenSplice daemon is started.

###### 3.2.7.2.1.2. Element Cert

The `Cert` element references the file containing the certificate.

Full Path | Security/Authentication/X509Authentication/Credentials/Cert
Format | string
Dimension | none
Default Value | none
Valid Values | any file URI
Occurrences (min-max) | 1 - 1
Remarks | It is recommended that the absolute path is used. A relative path will be interpreted relative to the directory from which the OpenSplice daemon is started.

##### 3.2.7.2.2. Element TrustedCertificates

The `TrustedCertificates` element references a file containing the trusted certificates.

Full Path | Security/Authentication/X509Authentication/TrustedCertificates
Format | string
Dimension | none
Default Value | none
Valid Values | any file URI
Occurrences (min-max) | 1 - 1
Remarks | It is recommended that the absolute path is used. A relative path will be interpreted relative to the directory from which the OpenSplice daemon is started.

## 3.3. Secure Networking Example Configuration

The following XML is an example of a secure networking configuration.

    <OpenSplice>
        <Domain>
            <Name>OpenSplice Security</Name>
            <Database>
                <Size>10485670</Size>
            </Database>
            <Lease>
                <ExpiryTime update_factor="0.5">5.0</ExpiryTime>
            </Lease>
            <Service enabled="true" name="networking">
                <Command>snetworking</Command>
            </Service>
        </Domain>

        <NetworkService name="networking">
            <Partitioning>
                <GlobalPartition Address="broadcast"
                   SecurityProfile="GlobalProfile"/>
                <NetworkPartitions>
                    <NetworkPartition Name="ChatRoomPartition"
                       Address="230.230.230.1"
                       SecurityProfile="ChatRoomProfile" />
                </NetworkPartitions>
                <PartitionMappings>
                    <PartitionMapping DCPSPartitionTopic="ChatRoom.*"
                       NetworkPartition="ChatRoomPartition"/>
                </PartitionMappings>
            </Partitioning>

          <Security enabled="true">
             <SecurityProfile Name="GlobalProfile"
                Cipher="aes128"
                CipherKey="000102030405060708090a0b0c0d0e0f" />
             <SecurityProfile Name="ChatRoomProfile"
                Cipher="blowfish"
                CipherKey="000102030405060708090a0b0c0d0e0f" />
             <SecurityProfile Name="OtherProfile"
                Cipher="rsa-aes128"
                CipherKey=
                   "file:///my/shared/secrets/aes128.key" />

             <AccessControl enabled="true" policy="file://.....">
                <AccessControlModule enabled="true" type="MAC"/>
             <AccessControl/>

             <Authentication enabled="true">
                <X509Authentication>
                   <Credentials>
                      <Key>
                        file:///usr/osp/securityConfig/ProxyKey.pem
                      </Key>
                      <Cert>
                         file:///usr/osp/securityConfig/ \
                            ProxyCert.pem
                      </Cert>
                   </Credentials>
                   <TrustedCertificates>
                      file://../../securityConfig/ \
                         trustedCerts.pem
                   </TrustedCertificates>
                </X509Authentication>
             <Authentication>
          </Security>
          <Channels>
                <Channel
                      enabled="true" name="BestEffort"
                      reliable="false" default="true">
                    <PortNr>3340</PortNr>
                </Channel>
                <Channel enabled="true" name="Reliable" reliable="true">
                    <PortNr>3350</PortNr>
                </Channel>
            </Channels>
            <Discovery enabled="true">
                <PortNr>3360</PortNr>
            </Discovery>
        </NetworkService>
    </OpenSplice>

### Navigation

- index
- next |
- previous |
- Secure Networking Guide »