.. include:: vars.rst

Security Plugins Properties
***************************

|RTI_SP| includes a set of builtin plugins that implement the plugins defined by the DDS
Security specification.
You can customize these builtin plugins: for example, to accommodate proprietary or
FIPS 140-2 compliant cryptography solutions, take advantage of custom security hardware,
or change the behavior of the plugins in any number of ways.
The |SP_SDK| enables customizing the |SP| to meet your system's security requirements.

All the security properties (described in the `com.rti.serv <../properties_reference/property_full.html#com-rti-serv>`_ list of properties) are validated when the plugin is created.
This validation is done in order to avoid using an unknown or incorrect property name (for example, due to a typo).
Without this validation, |CONNEXT| ignores the unknown property name and you might not know why the property's configuration isn't being applied.
You can find more information in the :link_um:`"Property Validation" <PROPERTY_Qos.htm#PropertyValidationUM>` section of the Core Libraries User's Manual.

If you add a new property to the Property Qos Policy, the creation of the |SP| by default will fail with an error similar to the following:

.. code-block::

    DDS_PropertyQosPolicy_validate_plugin_property_suffixes:Unexpected property: com.rti.serv.secure.new_property. Closest valid property: com.rti.serv.secure.openssl_engine
    RTI_Security_PluginSuite_create:Inconsistent QoS property: com.rti.serv.secure.

This problem can be solved in one of two ways:

Configuring the validation behavior
===================================

You can configure the behavior of the validation by setting the ``com.rti.serv.secure.property_validation_action`` property (see :link_sec_um:`Properties for Enabling Security <p2_core/building_apps.html#properties-for-enabling-security>`) as follows:

.. code-block:: XML

    <domain_participant_qos>
    <property>
        <value>
        <element>
            <name>com.rti.serv.load_plugin</name>
            <value>com.rti.serv.secure</value>
        </element>
        <element>
            <name>com.rti.serv.secure.property_validation_action</name>
            <value>VALIDATION_ACTION_SKIP</value>
        </element>
        </value>
    </property>
    </domain_participant_qos>

Validating your own properties
==============================

The |SP_SDK| properties are validated in the function ``RTI_Security_PluginSuite_create``:

.. code-block:: c

    if (!RTI_Security_Utility_validatePluginPropertySuffixes(
            (struct DDS_PropertyQosPolicy *) properties,
            prefix,
            PROPERTY_PLUGIN_VALID_PUBLIC_PROPERTIES_SECURITY,
            PROPERTY_PLUGIN_VALID_PRIVATE_PROPERTIES_SECURITY,
            /*
             * Do not validate the passed 'dds.sec' properties in the plugin creation,
             * those are already validated by core.
             */
            DDS_TRUST_PLUGIN_PROPERTY_PREFIX,
            validationAction)) {
        RTI_Security_Log_exception(
                &RTI_LOG_INCONSISTENT_PROPERTY_s,
                prefix);
        return;
    }

If you add a new property and still want to validate the properties, you will need to create a new list of properties to validate.
The new list will be a combination of the :link_sec_um:`Properties for Enabling Security <p2_core/building_apps.html#properties-for-enabling-security>` and your new properties.

To create the new list of properties for validation, perform the following steps:

1. Add the following list into the |SP_SDK|.

.. include:: sec_plugin_list_properties.rst
2. Add your new properties to the list ``PROPERTY_CUSTOM_PLUGIN_VALID_PUBLIC_PROPERTIES_SECURITY``.
3. In the function ``RTI_Security_Utility_validatePluginPropertySuffixes``, replace ``PROPERTY_PLUGIN_VALID_PUBLIC_PROPERTIES_SECURITY`` with ``PROPERTY_CUSTOM_PLUGIN_VALID_PUBLIC_PROPERTIES_SECURITY``.
4. Recompile the |SP_SDK|.
5. Your properties will be validated.