Security SDK
============

Introduction
------------

*RTI Security Plugins* introduce a robust set of security capabilities, 
including authentication, encryption, access control and logging. Secure 
multicast support enables efficient and scalable distribution of data to 
many subscribers. Performance is also optimized by fine-grained control 
over the level of security applied to each data flow, such as whether 
encryption or just data integrity is required. 

The |rti_me_security_sdk| includes a set of builtin plugins that implement 
the Service Plugin Interface defined by the DDS Security specification. 

*Security Plugins* are available in a separate package from the 
RTI Support Portal, https://support.rti.com/. 

It is also possible to implement new custom plugins by using the 
Security Plugins SDK bundle (for more information, please contact s
upport@rti.com). See the |rti_security_plugins_rnotes|_ and 
|rti_security_plugins_gsg|_.

Installation
------------

Please refer to the `Installation`_ chapter for how to install 
the |rti_me_security_sdk|.

Examples
--------

For descriptions and examples of the security configuration in this release, 
please consult the HelloWorld_dpde_secure examples under the 
example/[unix, windows]/[C, CPP] directory. |rti_me_security_sdk| supports 
both the C and C++ programming languages.

To use the |rti_me_security_sdk|, you will need to create private keys, identity 
certificates, governance, and permission files, as well as signed versions for 
use in secure authenticated, authorized, and/or encrypted communications.

Enabling RTI Security Plugins
-----------------------------

In order to enable the RTI Security Plugins, the name of a "plugin suite" (i.e.
the collection of security plugins defined by DDS Security) must be specified 
in a DomainParticipant's QoS. Plugin factories for this suite must also be
registered with the RT_Registry before the DomainParticipant is created.

When using |rti_me|'s C API, this can be achieved with the following code::

    RTI_BOOL result = RTI_FALSE;
    struct DDS_DomainParticipantQos dp_qos = DDS_DomainParticipantQos_INITIALIZER;
    struct SECCORE_SecurePluginFactoryProperty sec_plugin_prop = SECCORE_SecurePluginFactoryProperty_INITIALIZER;
    DDS_DomainParticipantFactory *factory =  DDS_DomainParticipantFactory_get_instance();
    RT_Registry_T *registry =  DDS_DomainParticipantFactory_get_registry(factory);

    /* Register factories for built-in security plugins, using default
     * properties and default name */
    if (!SECCORE_SecurePluginFactory_register(
            registry,SECCORE_DEFAULT_SUITE_NAME,&sec_plugin_prop))
    {
        printf("failed to register security plugins\n");
        goto done;
    }
    
    /* In order to enable security, the name used to register the suite of
     * plugins must be set in DomainParticipantQos */
    if (!RT_ComponentFactoryId_set_name(
            &dp_qos->trust.suite, SECCORE_DEFAULT_SUITE_NAME))
    {
        printf("failed to set component id\n");
        goto done;
    }
    
    result = RTI_TRUE;
    
    done:
    
    return result;

For users of |rti_me|'s C++ API, the suite can be registered using the following
code::

    RTI_BOOL result = RTI_FALSE;
    DDS_DomainParticipantQos dp_qos;
    SECCORE_SecurePluginFactoryProperty sec_plugin_prop;
    DDSDomainParticipantFactory *factory = DDSDomainParticipantFactory::get_instance();
    RTRegistry_T *registry = factory->get_registry();
                    
    /* Register factories for built-in security plugins, using default
     * properties and default name */
    if (!SECCORE_SecurePluginFactory::register_suite(
            registry,SECCORE_DEFAULT_SUITE_NAME,sec_plugin_prop))
    {
        printf("failed to register security plugins\n");
        goto done;
    }

    /* In order to enable security, the name used to register the suite of
     * plugins must be set in DomainParticipantQos */
    if (!dp_qos.trust.suite.set_name(SECCORE_DEFAULT_SUITE_NAME))
    {
        printf("failed to set component id\n");
        goto done;
    }
    
    result = RTI_TRUE;
    
    done:
        
    return result;
    
Additional properties can be controlled using (key,value) pairs in a 
DomainParticipant's DDS_PropertyQosPolicy.

Configuration keys (and corresponding valid values) supported by each security
plugin are listed by each plugin's section of this manual.

In |rti_me|, you must set the security-related participant properties before you 
create a participant. You cannot create a participant without security and 
then call DomainParticipant::set_qos() with security properties, even if the 
participant has not yet been enabled.