How to use DDS Secure logging
When using RTI Security Plugins, secure logging stores information about security events. This information can be provided via the standard output or log file, or distributed over DDS. The information is different between the two methods.
Standard output or output file
When Secure logging is configured to be written to the standard output or an output file, you will see the following information:
- Timestamps
- GUIDs
- Log messages
Here is an example of how these messages look:
[1541757196.822050]RTI_Security_Authentication_validate_local_identity:successfully validated local identity [1541757196.822290]RTI_Security_AccessControl_get_permissions_credential_token:successfully got permissions token [1541757196.825604]RTI_Security_AccessControl_validate_local_permissions:successfully validated local permissions [1541757196.828948]RTI_Security_AccessControl_get_participant_sec_attributes:successfully got participant security attributes
To write the log to the standard output, none of the following three functionalities should be enabled; otherwise, the log won’t be shown in the standard output:
- The output file option (com.rti.serv.secure.logging.log_file)
- The distributed log option (com.rti.serv.secure.logging.distribute.enable)
- The regular (non-secure) log (see the Logging QoS Policy in the RTI Connext DDS Core Libraries User's Manual, here for the current release or here for release 5.3.1)
To write the log to an output file, we need to set the following property within the participant_qos:
<participant_qos>
<property>
<value>
<element>
<name>com.rti.serv.secure.logging.log_file</name>
<value>log.txt</value>
</element>
</value>
</property>
</participant_qos>Distributed over DDS
When the messages are distributed over DDS, the information will follow the OMG specification, which states:
The Logger shall populate the facility, severity, and timestamp, fields. The Logger may populate the hostname, hostip, appname, procid fields as appropriate. The Logger shall add an entry to the structured_data field with the key “DDS”. This NameValuePair sequence shall include the following name-value pairs:
- Guid: RTPS GUID of the DDS entity that triggered the log message.
- Domain_id: Domain Id of the DomainParticipant that triggered the log message.
- Plugin_class: Identifier of the type of security plugin: Authentication, AccessControl, Cryptographic, etc.
- Plugin_method: Security plugin method name that triggered the log message.
Here is an example of how these messages look in RTI DDS Spy using the -printSample option:
1543498637.929123 d +M DCB9C740 DDS:Security:LogTopic DDSSecurity::BuiltinLoggingType
facility: 10
severity: DEBUG_LEVEL
timestamp:
sec: 1543498637
nanosec: 928903998
hostname: "localhost"
hostip: "0.0.0.0"
appname: "RTI Secure DDS Application"
procid: "9654"
msgid: "security"
message: "received submessage from an endpoint that discovered me but that I haven't discovered yet; dropping submessage hoping it will be repaired. It will not be repaired if the endpoint did not properly share its MasterKeyId in its CryptoToken."
structured_data:
[0]:
key: "DDS"
pairs:
[0]:
name: "guid"
value: "dcb9c740.7ecf85eb.42aa8349.1c1"
[1]:
name: "domain_id"
value: "25"
[2]:
name: "plugin_method"
value: "RTI_Security_Cryptography_preprocess_secure_submsg"
[3]:
name: "plugin_class"
value: "Cryptography"To distribute the log messages over DDS, set the following property within the participant_qos:
<participant_qos> <property> <value> <element> <name>com.rti.serv.secure.logging.distribute.enable</name> <value>true</value> </element> </value> </property> </participant_qos>
The granularity of the log messages depends on the verbosity level set for the Secure log. You can set the verbosity level as follows, 7 being the highest verbosity level:
<participant_qos> <property> <value> <element> <name>com.rti.serv.secure.logging.log_level</name> <value>7</value> </element> </value> </property> </participant_qos>
Using a custom subscriber
To get the secure logging information that is being distributed over DDS, you will need to create an application that subscribes to the secure log topic:
- Topic name: DDS:Security:LogTopic
- Type name: DDSSecurity::BuiltinLoggingType.
To create a custom subscriber, you can start from the IDL containing the definition of the DDSSecurity::BuiltinLoggingType that can be found under: “$NDDSHOME/resource/idl/builtin_logging_type.idl”.
With the IDL you can run rtiddsgen to generate type support code and example code. For example to generate type support code with a pub/sub application:
<span>rtiddsgen -language C -example x64Linux3gcc4.8.2 -unboundedSupport builtin_logging_type.idl</span>
You need to use the command-line option -unboundedSupport because the DDSSecurity::BuiltinLoggingType contains strings without a specified limit. By default, rtiddsgen will limit unbounded strings to 255 characters, unless you specify the -unboundedSupport option. Without this option, the type support code will not be compatible with the type used by RTI Security Plugins and you won't be able to receive any message.
For more information about the use of unbounded support with built-in types, see the Core Libraries User's Manual, here for the current release or here for release 5.3.1.
You can ignore/delete the builtin_logging_type_publisher.c application.
Now, edit the builtin_logging_type_subscriber.c and change the topic from "Example DDSSecurity_BuiltinLoggingType" to "DDS:Security:LogTopic" and build.
The Log data reader MUST be able to handle large unbound strings. By default, if you try to run the builtin_logging_type_subscribber application, you are going to get an error when the application tries to build the log data reader. To avoid this problem, you need to enter the following QoS in the profile used by the log subscriber:
<datareader_qos> <subscription_name> <name>builtin_logging_typeDataReader</name> </subscription_name> <property> <value> <element> <name>dds.data_reader.history.memory_manager.fast_pool.pool_buffer_max_size</name> <value>4096</value> </element> </value> </property> </datareader_qos>
ADDITIONAL NOTES:
- Your global Governance and Permissions file must allow the built-in logger to subscribe to the log topic.
- Your log subscriber MUST have an identity (private key & certificate) in order to be allowed to receive the log messages
- DDS Secure publish log messages using the QoS profile specified by the property 'com.rti.serv.secure.logging.distribute.profile'. If unset, it will use the same QoS profile as the DDS Domain Participant that is loading the DDS Secure plug-in.
- If you use a custom profile to distribute the log, only data reader and data writer QoS will be used from the specified profile. In particular, the participant that distributes the log always shares the same identity and the same Participant QoS of the participant that instantiate the DDS secure plug-in. You can use this profile for the logger for example if you want to change the logger's reliability, but you cannot use it to change the logger's identity.
In this post you can find the full example of a subscribing application that can be used to receive to the log messages produced by the DDS Secure example that can be found under:
rti_workspace/6.0.0/examples/connext_dds/c/hello_security
To test it, unzip it in the same directory as the hello_security example. For example:
$ cd ~/rti_workspace/6.0.0/examples/connext-dds/c $ unzip ~/Downloads/hello_security_logger.zip $ ls -l total 60 [...] drwxrwsrwx 6 fabrizio users 4096 Mar 22 18:11 builtin_logging_type.idl drwxrwxrwx 2 fabrizio users 4096 Mar 22 19:23 builtin_logging_type_subscriber.c [...] $ make -f makefile_builtin_logging_type_x64Linux3gcc4.8.2 SHAREDLIB=1 [...] $ ./objs/x64Linux3gcc4.8.2/builtin_logging_type_subscriber
The example shares governance file and certificate authorities with the hello_security example.
For more information on DDS Secure logging, see the RTI Security Plugins Getting Started Guide, here for the current release or here for release 5.3.1.
