5. Authentication

Required

The prefix name of the security plugin suite that will be loaded by Connext DDS. For example: com.rti.serv.secure. You will use this string as the prefix to some of the property names. Setting this value to non-NULL will also configure the DomainParticipant to attempt authentication with newly discovered remote participants. Note: you can load only one security plugin suite.

Default: NULL unless using the Generic.Security builtin profile

Only required if linking dynamically

Must be set to the dynamic library that implements the security plugin suite. If using Connext DDS’s provided security plugin suite, you must set this value to nddssecurity.

This library and the dependent OpenSSL libraries must be in your library search path (pointed to by the environment variable LD_LIBRARY_PATH on UNIX/Solaris systems, Path on Windows systems, LIBPATH on AIX systems, DYLD_LIBRARY_PATH on macOS systems).

Default: NULL unless using Generic.Security builtin profile

Only required if linking dynamically

Must be set to the security plugin suite creation function that is implemented by the library. If using Connext DDS’s provided security plugin suite, you must set this value to RTI_Security_PluginSuite_create.

Default: NULL unless using Generic.Security builtin profile

Required

This Identity Certificate Authority is used for signing authentication certificate files.

OpenSSL should generate this file using commands such as the following. For an example openssl.cnf file, refer to the example cert folder: rti_workspace/version/examples/dds_security/cert. Note: You will need to modify this file to match your certificate folder structure and Identity Certificate Authority desired configuration.

RSA:

% openssl genrsa -out cakey.pem 2048

% openssl req -new -key cakey.pem -out ca.csr -config  openssl.cnf

% openssl x509 -req -days 3650 -in ca.csr -signkey cakey.pem -out cacert.pem

DSA:

% openssl dsaparam 2048 > dsaparam

% openssl gendsa -out cakeydsa.pem dsaparam

% openssl req -new -key cakeydsa.pem -out dsaca.csr -config openssldsa.cnf

% openssl x509 -req -days 3650 -in dsaca.csr -signkey cakeydsa.pem -out cacertdsa.pem

ECDSA:

% openssl ecparam -name prime256v1 > ecdsaparam

% openssl req -nodes -x509 -days 3650 -newkey ec:ecdsaparam 
-keyout cakeyECdsa.pem -out cacertECdsa.pem -config opensslECdsa.cnf

If specifying the file name as the property value, this property value should be set to "file:" (no space after the colon), followed by the file name that appears after the "-out" parameter of the final openssl command (e.g., cacert.pem, cacertdsa.pem, or cacertECdsa.pem).

Note: When running the above commands, you may run into these OpenSSL warnings:

WARNING: can't open config file: [default openssl built-inpath]/openssl.cnf 

Or:

unable to write 'random state' 

To resolve the first issue, set the environmental variable OPENSSL_CONF with the path to the openssl.cnf file you are using. (See Installing OpenSSL, in the Security Plugins Installation Guide.) To resolve the second issue, set the environmental variable RANDFILE with the path to a writable file.

Two participants that want to securely communicate with each other must use the same Identity Certificate Authority.

The document should be in PEM format. You may specify either the file name or the document contents. If specifying the file name, the property value must have the prefix "file:" (no space after the colon), followed by the fully-qualified path and name of the file. If specifying the contents of the document, the property value must have the prefix "data:," (no space after the comma), followed by the contents inside the document. For example:

"data:,-----BEGIN CERTIFICATE-----\nabcdef\n-----END CERTIFICATE-----"

Note that the two “\n” characters are required.

Default: NULL

Required

The private key associated with the first certificate that appears in identity_certificate. After generating the identity_ca, OpenSSL should generate this file using commands such as the following:

RSA:

% openssl genrsa -out peer1key.pem 2048

DSA:

% openssl dsaparam 2048 > dsaparam

% openssl gendsa -out peer1keydsa.pem dsaparam

ECDSA:

% openssl ecparam -name prime256v1 > ecdsaparam1

% openssl req -nodes -new -newkey ec:ecdsaparam1 -config example1ECdsa.cnf \
   -keyout peer1keyECdsa.pem -out peer1reqECdsa.pem

peer1reqECdsa.pem will be used to generate the certificate file. This property value should be set to peer1keyECdsa.pem.

The document should be in PEM format. You may specify either the file name or the document contents. If specifying the file name, the property value must have the prefix "file:" (no space after the colon), followed by the fully-qualified path and name of the file. If specifying the contents of the document, the property value must have the prefix "data:," (no space after the comma), followed by the contents inside the document. For example:

"data:,-----BEGIN PRIVATE KEY-----\nabcdef\n-----END PRIVATE KEY-----" 

Note that the two “\n” characters are required.

Default: NULL

Required

An Identity Certificate is required for secure communication.

To generate this file, first generate the identity_ca and private_key. Then create a serial file whose contents are 01 and a blank index.txt file. The names of these files will depend on the contents of the openssl*.cnf file. Then use OpenSSL to generate the certificate file using commands such as the following. For example .cnf files, refer to the example cert folder: rti_workspace/version/examples/dds_security/cert. Note: You will need to modify this file to match your certificate folder structure and Identity Certificate desired configuration:

RSA:

% openssl req -config example1.cnf -new -key peer1key.pem -out user.csr

% openssl ca -config openssl.cnf -days 365 -in user.csr -out peer1.pem

DSA:

% openssl req -config example1dsa.cnf -new -key peer1keydsa.pem -out dsauser.csr 

% openssl ca -config openssldsa.cnf -days 365 \
  -in dsauser.csr -out peer1dsa.pem

ECDSA:

Generate peer1reqECdsa.pem using the instructions for private_key.

% openssl ca -batch -create_serial -config opensslECdsa.cnf \
  -days 365 -in peer1reqECdsa.pem -out peer1ECdsa.pem

If specifying the file name as the property value, this property value should be set to "file:" (no space after the colon), followed by the file name that appears after the "-out" parameter.

Notes:

• The above commands will generate an optional human-readable section above the mandatory section delimited by

-----BEGIN CERTIFICATE-----

-----END CERTIFICATE-----

The human-readable section's "Subject" field may be copied to a <subject_name> element in the Permissions Document. But this section adds no functionality and is not protected in any way. It may be modified without changing the validity of the certificate. To generate a certificate without this section, add the command line parameter -notext to the "openssl ca" command.

• openssl((EC)dsa).cnf must have the same countryName, stateOrProvinceName, and localityName as the example .cnf files.
• For better security, it is recommended, but not required, that .cnf files of different participants have different commonNames
• The document should be in PEM format. You may specify either the file name or the document contents. If specifying the file name, the property value must have the prefix "file:" (no space after the colon), followed by the fully qualified path and name of the file. If specifying the contents of the document, the property value must have the prefix "data:," (no space after the comma), followed by the contents inside the document. For example:

"data:,-----BEGIN CERTIFICATE-----\nabcdef\n-----END CERTIFICATE-----"

Note that the two “\n” characters are required.

• You may put a chain of certificates in the Identity Certificate by concatenating individual certificates and specifying the concatenated result as a single file or string. See 5.1 Identity Certificate Chaining.

Default: NULL

Optional

The algorithm used to establish a shared secret during authentication. The options are dh and ecdh for (Elliptic Curve) Diffie-Hellman.

If two participants discover each other and they specify different values for this algorithm, the algorithm that is used is the one that belongs to the participant with the lower-valued participant_key.

Note: ecdh does not work with static OpenSSL libraries when using Certicom Security Builder Engine.

Default: ecdh

Optional

A comma-separated list of alternative Identity CA certificates. If the verification of a file fails with the main certificate (identity_ca/ca_file), verification will be retried with all of the corresponding alternative certificates. If none of the alternative certificates can be used to verify the file, the verification process will fail. If any of the alternative certificate files fail to be loaded, the DomainParticipant creation will fail.

Default: NULL

Optional

This Certificate Revocation List keeps track of untrusted X.509 certificates.

OpenSSL should generate this file using commands such as the following. For an example opensslECdsa.cnf file, refer to the example cert folder: rti_workspace/version/examples/dds_security/cert. Note: You will need to modify this file to match your certificate folder structure and Certificate Revocation List desired configuration:

% touch indexECdsa.txt

% echo 01 > crlnumberECdsa

% openssl ca -config opensslECdsa.cnf -batch -revoke peerRevokedECdsa.pem

% openssl ca -config opensslECdsa.cnf -batch -gencrl -out democaECdsa.crl

In this example:

crlnumberECdsa is the database of revoked certificates. This file should match the crlnumber value in opensslECdsa.cnf.

peerRevokedECdsa.pem is the certificate_file of a revoked DomainParticipant.

democaECdsa.crl should be the value of the crl_file property.

If crl_file is set to NULL, no CRL is checked, and all valid certificates will be considered trusted.

If crl_file is set to an invalid CRL file, the DomainParticipant creation will fail.

If crl_file is set to a valid CRL file, the CRL will be checked upon DomainParticipant creation and upon discovering other DomainParticipants. Creating a DomainParticipant with a revoked certificate will fail. If ParticipantA uses a certificate that does not appear in ParticipantA’s CRL but does appear in ParticipantB’s CRL, then ParticipantB will reject and ignore ParticipantA. Changes in the CRL will not be enforced until the DomainParticipant using the CRL is deleted and recreated.

This property value may optionally contain "file:" (no space after the colon) as a prefix to the fully-qualified path and name of the file.

Default: NULL