7. Security Events and Logging¶
The Security Plugins uses its own Logging Plugin to notify you of security events. This Logging Plugin supports the following logging methods (non-exclusive):
Using Connext DDS’s own builtin logging system to send security messages
Distributing security log messages over DDS
By default, log messages are processed by the Connext DDS Builtin Logging System. You can configure which logging methods to use by setting the logging.mode_mask
property. You can also adjust the verbosity level of the log messages with logging.verbosity
. See Table 7.2.
If you distribute log messages over DDS using the Builtin Secure Logging Topic, the messages’ log levels are used as the severity values of the BuiltinLoggingType. If you are using the Connext DDS Builtin Logging System, the messages’ log levels are mapped to the values shown in Table 7.1. See Controlling Messages from Connext DDS in the RTI Connext DDS Core Libraries User’s Manual for more information on the Connext DDS Builtin Logging System.
See the following sections for more information about the different logging methods 1.
- 1
Before release 6.1.0 of Connext DDS, you could choose to redirect the security messages to a file by setting the
logging.log_file
property. In Connext DDS 6.1.0, this property has been removed, and using it will result in a DomainParticipant creation failure. You can still redirect the security log to a file by enabling theBUILTIN
flag in thelogging.mode_mask property
(enabled by default) and configuring the Connext DDS Builtin Logging System to use a log file or an output device (see Controlling Messages from Connext DDS in the RTI Connext DDS Core Libraries User’s Manual).
7.1. Connext DDS Builtin Logging System¶
When security logging is configured to be written to Connext DDS’s own builtin logging system (also known as NDDS_Config_Logger), you will see messages that use a JSON format and look something like the following:
[2020-09-11 16:17:06.477203] [CREATE DP] RTI_Security_CertHelper_loadPrivateKey:{"DDS:Security:LogTopic":{"f":"10","s":"3","t":{"s":"1599841026","n":"477193999"},"h":"rti-10636","i":"0.0.0.0","a":"RTI Secure DDS Application","p":"2788","k":"security","x":[{"DDS":[{"domain_id":"<unknown>"},{"guid":"<unknown>"},{"plugin_class":"Common"},{"plugin_method":"RTI_Security_CertHelper_loadPrivateKey"}]}],"m":"private_key is not encrypted, yet password is supplied. Aborting participant creation due to inconsistent configuration."}}
[2020-09-11 16:17:06.477233] [CREATE DP] RTI_Security_AuthenticationData_create:{"DDS:Security:LogTopic":{"f":"10","s":"0","t":{"s":"1599841026","n":"477228999"},"h":"rti-10636","i":"0.0.0.0","a":"RTI Secure DDS Application","p":"2788","k":"security","x":[{"DDS":[{"domain_id":"<unknown>"},{"guid":"<unknown>"},{"plugin_class":"Authentication"},{"plugin_method":"RTI_Security_AuthenticationData_create"}]}],"m":"failed to read authentication.private_key_file"}}
The mapping from the above format to the fields in the DDS:Security:LogTopic
type (see Builtin Secure Logging Topic) is as follows:
"f"
:facility
"s"
:severity
"t"
:timestamp
(within this field"s"
refers to seconds, and"n"
to nanoseconds)"h"
:hostname
"i"
:hostip
"a"
:appname
"p"
:procid
"k"
:msgid
"m"
:message
"x"
:structured_data
The messages may be preceded by additional information, such as timestamps or GUIDs, depending on the Connext DDS Builtin Logging System format configuration and the message NDDS_Config_LogLevel. (See Format of Logged Messages, in the RTI Connext DDS Core Libraries User’s Manual.)
By default, the Connext DDS Builtin Logging System writes to the standard output, but you can configure it to use a log file or an output device such as a custom logging device or the Distributed Logger. (See Controlling Messages from Connext DDS in the RTI Connext DDS Core Libraries User’s Manual and RTI Distributed Logger in the Core Libraries User’s Manual.)
For messages logged through the Connext DDS Builtin Logging System, the verbosity is per application. This affects both messages directly logged through the Connext DDS Builtin Logging System, as well as the security events from the builtin Logging Plugin if it is configured to go through the Connext DDS Builtin Logging System. If not set, the verbosity will be left unchanged. Therefore, if no DomainParticipant has configured the verbosity, it will be left to the default (ERROR
). However, if a DomainParticipant has configured the verbosity, it will update it for all the DomainParticipants within the application.
7.1.1. Logging Security Events through the Connext DDS Builtin Logging System¶
To make the security log go through the Connext DDS Builtin Logging System, enable the BUILTIN
flag with the logging.mode_mask
property within the domain_participant_qos
(this is the default configuration, see Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual):
<domain_participant_qos>
<property>
<value>
<element>
<name>com.rti.serv.secure.logging.mode_mask</name>
<value>BUILTIN</value>
</element>
</value>
</property>
</domain_participant_qos>
The granularity of the log messages depends on the verbosity level set for the security log. You can set the verbosity level as follows, DEBUG
being the highest verbosity level (see Properties for Configuring Security Events and Logging):
<domain_participant_qos>
<property>
<value>
<element>
<name>com.rti.serv.secure.logging.verbosity</name>
<value>DEBUG</value>
</element>
</value>
</property>
</domain_participant_qos>
7.2. Distributed Over DDS¶
When the messages are distributed over DDS, the information will be logged using the BuiltinLoggingType, following the DDS Security specification. For example, here is how the messages look in RTI DDS Spy (using the -printSample option) when you use logging distribution over DDS:
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"
7.2.1. Configuring the Logging Distribution¶
To distribute the log messages over DDS, enable the SECURITY_TOPIC
flag with the logging.mode_mask
2 property within the domain_participant_qos
(see Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual):
<domain_participant_qos>
<property>
<value>
<element>
<name>com.rti.serv.secure.logging.mode_mask</name>
<value>SECURITY_TOPIC</value>
</element>
</value>
</property>
</domain_participant_qos>
The granularity of the log messages depends on the verbosity level set for the security log. You can set the verbosity level as follows, DEBUG
being the highest verbosity level (see Properties for Configuring Security Events and Logging):
<domain_participant_qos>
<property>
<value>
<element>
<name>com.rti.serv.secure.logging.verbosity</name>
<value>DEBUG</value>
</element>
</value>
</property>
</domain_participant_qos>
For more details on configuring the Logging Distribution over DDS, see Table 7.2.
7.2.2. Builtin Secure Logging Topic¶
When you distribute the security logging information over DDS, your DomainParticipant will publish this information to the Builtin Secure Logging Topic (DDS:Security:LogTopic
), as defined in the DDS Security specification. DDS samples in this topic will have the type BuiltinLoggingType (DDSSecurity::BuiltinLoggingType
).
This type includes information about the logging level, the DomainParticipant producing the message, a timestamp, etc. You can find the IDL description of the BuiltinLoggingType in <NDDSHOME>/resource/idl/builtin_logging_type.idl
. (See Paths Mentioned in Documentation.)
7.2.3. Implementation Notes¶
7.2.3.1. Publication of the Builtin Secure Logging Topic¶
The DDS:Security:LogTopic
(described in Subscribing to the Builtin Logging Topic) is published by the same DomainParticipant that uses the Security Plugins to communicate securely. Therefore, this topic is published in a Secure Domain, and the Governance and Permissions Files that apply to that DomainParticipant also apply to this log topic. For this reason, the Permissions File must allow the DDS:Security:LogTopic
to be published.
By default, the DDS:Security:LogTopic
is protected using Submessage Protection set to SIGN
3 (see Builtin Secure Logging Topic).
Attention
There is no option to use a separate “Builtin Logging” DomainParticipant and to share it among multiple DomainParticipants.
7.2.3.2. Custom QoS Profile for the Builtin Secure Logging Topic¶
The Security Plugins publish log messages using the QoS Profile specified by the property logging.security_topic.profile
. If this property is not set, the Security Plugins will use the BuiltinQosLib::Generic.KeepLastReliable.TransientLocal
profile by default, and the Security Plugins will set history.depth to 64 and publish_mode.kind to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS.
If you specify a custom profile in the property logging.security_topic.profile
, only Publisher, Topic, and DataWriter QoS will be used from the specified profile. This is because the DataWriter that distributes the log belongs to the same DomainParticipant as the one instantiating the Security Plugins. As a result, you can use the custom profile for the logger if, for example, you want to change the logger’s reliability, but you cannot use it to change the logger’s identity (Private Key and Identity Certificate).
- 2
Before release 6.1.0 of Connext DDS, enabling the logging distribution was done by setting the
logging.distribute.enable
property toTRUE
. In Connext DDS 6.1.0, this property has been removed, and setting it will result in a DomainParticipant creation failure.- 3
In Connext DDS 5.3.0, the Builtin Secure Logging Topic did not use Submessage Protection (which did not comply with the DDS Security specification). For backward compatibility, you can choose to disable Submessage Protection in this topic with the
access_control.use_530_logging_protection property
(see Table 7.3).
7.3. Advanced Logging Concepts¶
7.3.1. Interface Between the Logging Plugin and the Connext DDS Builtin Logging System¶
Log messages generated by the Logging Plugin in the Security Plugins and those generated by the Connext DDS Builtin Logging System (which is the default method) have a different structure. For example, the Logging Plugin includes information about the process ID (procid) and the host (hostname, hostip) as fields of the DDSSecurity::BuiltinLoggingType
type. To provide this information when using the Connext DDS Builtin Logging System, security messages use a JSON format, as specified in Connext DDS Builtin Logging System.
The log level values used by these logging systems are also different. Table 7.1 shows the mapping between Logging Plugin log values and the Connext DDS Builtin Logging System log values. For example, messages marked as EMERGENCY
, ALERT
, CRITICAL
, or ERROR
in the Security Plugins are translated to ERROR
when using the Connext DDS Builtin Logging System.
Logging Plugin (Security Plugins) Log Level Values 4 |
Connext DDS Builtin Logging System Log Level Values 5 |
---|---|
|
|
|
|
|
|
|
|
- 4
These values correspond to the values listed in
logging.verbosity
(see Table 7.2).- 5
These values are described in Controlling Messages from Connext DDS in the RTI Connext DDS Core Libraries User’s Manual.
7.3.2. Subscribing to the Builtin Logging Topic¶
To get the security logging information that is being distributed over DDS, you will need to create an application that subscribes to the Builtin Secure Logging Topic:
Topic name:
DDS:Security:LogTopic
Type name:
DDSSecurity::BuiltinLoggingType
Note
Since the log messages are distributed in a secured domain, your subscriber needs an identity (Private Key and Identity Certificate). In addition, it needs to have permission to subscribe to topic DDS:Security:LogTopic
; this permission needs to be included in its Permissions File.
You can subscribe to the Builtin Secure Logging Topic with RTI DDS Spy using the -printSample option.
rtiddsspy -printSample -domainId <domainId> -qosProfile <lib::prof>
Alternatively, to create a custom subscriber, you can start from the IDL containing the definition of the DDSSecurity::BuiltinLoggingType
, which can be found here: <NDDSHOME>/resource/idl/builtin_logging_type.idl
. (See Paths Mentioned in Documentation.)
With the IDL, you can run rtiddsgen to generate type support code and example code. For example, the following command will generate all the files you need to access the DDS:Security:LogTopic
topic from your Connext DDS application:
rtiddsgen -language C -example x64Linux3gcc4.8.2 -unboundedSupport builtin_logging_type.idl
Important
You need to use the command-line option -unboundedSupport because 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 Security Plugins, and you won’t be able to receive any messages. For more information about the use of unbounded support with builtin types, see Managing Memory for Builtin Types in the RTI Connext DDS Core Libraries User’s Manual.
7.4. Properties for Configuring Security Events and Logging¶
The following properties in the DomainParticipant property configure Logging:
Property Name (prefix with |
Property Value Description |
---|---|
|
Optional The logging verbosity level. This setting applies to all methods of security logging (the Connext DDS Builtin Logging System and Distributed Over DDS). All log messages at and below the This property can take any of the following values:
Notes:
Integer: Default: |
|
Optional The logging verbosity level. This setting applies to all methods of security logging (the Connext DDS Builtin Logging System and Distributed Over DDS). All log messages at and below the verbosity level will be logged. This property can take any of the following values (case sensitive):
This property is incompatible with Enum: Default: |
|
Optional Controls which logging methods are used to process the log messages produced by the Logging Plugin. You can specify one of these possible values:
Or any combination of the above, separating each element by When Mask: Default: |
Property Name (prefix with |
Property Value Description |
---|---|
|
Optional QoS Library and QoS Profile used to create logging-related entities (Publisher, Topic and DataWriter). Must be a string of the format String. Default: |
|
Optional Size of the logging thread queue, in bytes. Integer. Default: |
|
Optional Maximum number of log messages in the logging queue. Integer. Default: |
|
Optional Maximum serialized size of a log message in the logging queue. Integer. Default: |
|
Optional Number of bytes to preallocate for the logging message string in the logging thread, beyond which dynamic allocation will occur. Integer. Default: |
|
Optional Number of bytes to preallocate for the plugin method string in the logging thread, beyond which dynamic allocation will occur. Integer. Default: |
|
Optional Number of bytes to preallocate for the plugin class string in the logging thread, beyond which dynamic allocation will occur. Integer. Default: |
|
Optional How to set the value of If If Boolean. Default: |
- 6(1,2)
Assuming you used
com.rti.serv.secure
as the alias to load the plugin. If not, change the prefix to match the string used withcom.rti.serv.load_plugins
, followed by the.
character.- 7
Before version 6.1.0 of Connext DDS, properties for configuring security logging distributed over DDS had a name starting with
logging.distribute
. Starting with Connext DDS 6.1.0, these properties start withlogging.security_topic
. Properties using the former names are deprecated but still usable. If you set a property using both thelogging.distribute
and thelogging.security_topic
forms, the latter will take effect and the former will be ignored.
7.5. Logging Messages¶
Table 7.4 lists security-related events and the log messages they generate.
Event |
Log Level |
Message |
---|---|---|
Failed to allocate memory |
|
insufficient memory
|
allow_unauthenticated_participants = FALSE, and discovered remote participant that is unauthenticable, i.e. has not enabled security |
|
unauthenticated remote participant [participant ID] denied
|
allow_unauthenticated_participants = TRUE, and discovered remote participant that is either unauthenticable or fails authentication |
|
allowing unauthenticated participant [participant ID]
|
Received invalid X509 certificate, from either remote or local participant |
|
failed to decode certificate
|
Couldn’t verify certificate’s signature against neither the certificate of the Identity Certificate Authority nor any alternative CAs |
|
failed to verify certificate
|
Certificate appears in Certificate Revocation List |
|
certificate revoked
|
Upon receiving HandshakeReplyMessageToken or HandshakeFinalMessageToken, couldn’t verify challenge’s signature against peer’s certificate. Peer likely has mismatched private and public keys, so it’s an imposter. |
|
failed to verify challenge signature
|
Another participant has lost liveliness with this one before authentication was completed and is trying to re-authenticate itself (see Re-Authentication). A new authentication should restore communication once the ongoing authentication times out. Or: Network traffic corruption during authentication. Or: Misbehaving remote participant during authentication. |
|
RTI_Security_Authentication_process_handshake:received unexpected handshake message, probably from a participant that lost liveliness with this one before ongoing authentication completed. Once current authentication times out, communication should be restored.
|
RTI_Security_Authentication_process_handshake failed (see previous row). |
|
DDS_DomainParticipantTrustPlugins_forwardProcessHandshake:!security function process_handshake returned VALIDATION_FAILED
|
Couldn’t verify permissions or governance file signature against either the certificate of the Permissions Authority or any alternative permissions authorities |
|
Document signature verification failed. Make sure document was signed by the right permissions authority.
|
Received signed permissions document that is not an XML document |
|
received invalid signed permissions document
|
Received signed governance document that is not an XML document |
|
received invalid signed governance document
|
Couldn’t parse the permissions file for some reason, such as duplicate grants for the same subject name or no grant for the intended subject name |
|
failed to parse permissions file
|
Couldn’t parse the governance file for some reason |
|
failed to parse governance file
|
Denied participant because there is a deny rule explicitly prohibiting the participant |
|
participant not allowed: deny rule found
|
Denied participant because there is no rule for the participant’s domain ID, and the default is to deny |
|
participant not allowed: no rule found for the participant's domainId; default DENY
|
Denied writer or reader because there is a deny rule explicitly prohibiting the writer or reader |
|
endpoint not allowed: deny rule found
|
Denied writer or reader because there is no rule for the writer or reader, and the default is to deny |
|
endpoint not allowed: no rule found; default DENY
|
Parsed publish/subscribe rule in permissions file that does not apply to the writer/reader because no topic expressions match the writer/reader’s topic |
|
This publish/subscribe rule doesn't apply because none of the rule's topic expressions match the endpoint's topic name of [topic name]
|
Parsed publish/subscribe rule in permissions file that does not apply to the writer/reader because even though there’s a matching topic expression, there are no matching partition expressions |
|
This publish/subscribe rule doesn't apply because none of the rule's partition expressions match with any of the endpoint's partitions
|
Another participant, which is not using is_rtps_protected = true or is not using security at all, has sent this one an unprotected RTPS message that is not a participant announcement, handshake message, or key exchange message. This participant is using is_rtps_protected = true, so it drops the message. Or: Network traffic corruption after key exchange. Or: Misbehaving remote participant after key exchange. |
|
MIGInterpreter_parse:received unencoded rtps message. Unacceptable due to is_rtps_protected = true
|
Received authenticated content that has been tampered with, i.e. EVP_DecryptFinal_ex failed because the GCM or GMAC tag verification failed |
|
DecryptFinal failed. Possible GCM authentication failure.
|
Received submessage encrypted with a key whose MasterKeyId hasn’t yet been exchanged via CryptoToken |
|
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
|
Writing a log message over the LogTopic fails due to insufficient logging queue size |
|
Failed to write log message of size = [message size] because the logging queue is full. Try to increase logging.security_topic.queue.message_count_max, which is currently [message_count_max].
|
Parsed publish/subscribe <allow_rule> in permissions file that does not apply to the writer/reader because even though there’s a matching topicexpression, the partition expressions in the QoS are not a subset of the ones in the <allow_rule> |
|
This publish/subscribe rule doesn't apply because endpoint's partitions are not a subset of the rule's partition expressions
|