.. include:: ../vars.rst

.. _chapter-admin-console:

***************************************************************
DDS Security Data Visualization with RTI Administration Console
***************************************************************

|RTI_ADMINCONSOLE| is compatible with |RTI_SP_PRODUCT|. Configuring security in
|ADMINCONSOLE| will allow you to visualize and troubleshoot your DDS Secure
system. The security configuration is under :guilabel:`Preferences` >
:guilabel:`Security`. There, you can secure |ADMINCONSOLE|'s |DPs| by checking
the :guilabel:`Enable Security for specified Domains` checkbox. The security
preferences will only apply to the domains listed in the
:guilabel:`Domain Filter` field. Note that a :value:`*` in this field will apply
security to all domains; you can also use patterns like :value:`2,3` or
:value:`8,9-12,23`.

After setting the :guilabel:`Domain Filter` to the desired domains where you
want to visualize your DDS Secure system, you have to set the security artifacts
that |ADMINCONSOLE|’s |DPs| will use, as shown in
:numref:`Fields to Configure Authentication in Admin Console`,
:numref:`Fields to Configure Access Control in Admin Console`,
:numref:`Fields to Configure Cryptography in Admin Console`,
:numref:`Fields to Configure Logging in Admin Console`.

.. note::

  As a prerequisite for using security in |ADMINCONSOLE|, you need to install
  the |RTI_SP_PRODUCT|. For this, you can follow the instructions in the
  |SP_IG_LINK|.


:numref:`Security Panel in Admin Console's Preferences` is an example of the
values to configure |ADMINCONSOLE| to work with the "Security::SecureAllowAll"
profile of Shapes Demo:

.. figure:: ../static/admin-console-security-conf.png
  :width: 100%
  :alt: Security Panel in Admin Console's Preferences
  :name: Security Panel in Admin Console's Preferences
  :align: center

  Security Panel in |ADMINCONSOLE|'s Preferences


The following tables describe the purpose of each field.

.. note::

  If you are using |ADMINCONSOLE| 5.3.x, make sure to click the
  :guilabel:`Apply` button. This is critical because the settings won't be
  applied if you just click :guilabel:`OK`.


.. list-table:: Fields to Configure Authentication in |ADMINCONSOLE|
  :name: Fields to Configure Authentication in Admin Console
  :widths: 35 65
  :header-rows: 1
  :class: longtable

  * - Field
    - Description

  * - :guilabel:`Key Establishment Algorithm`
    - :required:`Required`

      The algorithm used to establish a |SharedSecret| during authentication, as
      defined by the :property:`dds.sec.auth.key_establishment_algorithm`
      property.

      For details, see :numref:`|RTI_SP_PRODUCT_HEADING| Properties for Configuring Authentication`.

  * - :guilabel:`Identity Certificate Authority`
    - :required:`Required`

      Provides |ADMINCONSOLE|’s |DPs| with the Identity CA, as defined by the
      :property:`dds.sec.auth.identity_ca` property.

      For details, see :numref:`DDS Security Properties for Configuring Authentication`.

  * - :guilabel:`Certificate Revocation List`
    - :required:`Optional`

      The Identity CA can maintain a certificate revocation list (CRL) with
      information about digital certificates that have been revoked before their
      scheduled expiration date and should no longer be trusted.

      With this field you can provide the CRL to the |ADMINCONSOLE|'s |DPs|, as
      defined by the :property:`authentication.crl` property.

      For details, see :numref:`|RTI_SP_PRODUCT_HEADING| Properties for Configuring Authentication`.

  * - :guilabel:`Private Key`
    - :required:`Required`

      Provides |ADMINCONSOLE|’s |DPs| with a |PrivateKey|, as defined by the
      :property:`dds.sec.auth.private_key` property.

      For details, see :numref:`DDS Security Properties for Configuring Authentication`.

      For details, see :numref:`DDS Security Properties for Configuring Authentication`.

  * - :guilabel:`Private Key Password`
    - :required:`Only required if the Private Key is encrypted`

      The password used to decrypt the |PrivateKey|. This field is interpreted
      as the Base64 encoding of the symmetric key that will be used to decrypt
      the |PrivateKey|, as defined by the :property:`dds.sec.auth.password`
      property.

      If the password is wrong, |ADMINCONSOLE| will fail to create the secure
      participants and will report multiple errors in the
      :guilabel:`Console Log`.

  * - :guilabel:`Identity Certificate`
    - :required:`Required`

      Provides |ADMINCONSOLE|'s |DPs| with an |IdentityCert|, as defined by the
      :property:`dds.sec.auth.identity_certificate` property.

  * - :guilabel:`Security Advance Notice Expiration (seconds)`
    - :required:`Required`

      Controls how much time in advance to notify the user when a local |DP|'s
      security artifacts (|IdentityCert| or |PermissionsDoc|) is about to
      expire. For more information, read the documentation on the
      :property:`dds.participant.trust_plugins.expiration_advance_notice_duration.sec`
      property.

.. list-table:: Fields to Configure Access Control in |ADMINCONSOLE|
  :name: Fields to Configure Access Control in Admin Console
  :widths: 35 65
  :header-rows: 1
  :class: longtable

  * - Field
    - Description

  * - :guilabel:`Permissions Certificate Authority`
    - :required:`Required`

      Provides |ADMINCONSOLE|'s |DPs| with the Permissions CA, as defined by the
      :property:`dds.sec.access.permissions_ca` property.

      For details, see :numref:`DDS Security Properties for Configuring Access Control`.

  * - :guilabel:`Governance Document`
    - :required:`Required`

      Provides |ADMINCONSOLE|'s |DPs| with the |GovernanceDoc|, as defined by
      the :property:`dds.sec.access.governance` property.

      For details, see :numref:`DDS Security Properties for Configuring Access Control`.

  * - :guilabel:`Permissions Document`
    - :required:`Required`

      Provides |ADMINCONSOLE|'s |DPs| with the |PermissionsDoc|, as defined by
      the :property:`dds.sec.access.permissions` property.

      For details, see :numref:`DDS Security Properties for Configuring Access Control`.


.. list-table:: Fields to Configure Cryptography in |ADMINCONSOLE|
  :name: Fields to Configure Cryptography in Admin Console
  :widths: 35 65
  :header-rows: 1
  :class: longtable

  * - Field
    - Description

  * - :guilabel:`Encryption Algorithm`
    - :required:`Required`

      The algorithm that the Sender uses for the encryption transformation, as
      defined by the :property:`dds.sec.crypto.symmetric_cipher_algorithm`
      property.

      For details, see :numref:`Properties for Configuring Cryptography Affecting Any Cryptography Plugin`.

  * - :guilabel:`Key Revision Max History Depth`
    - :required:`Optional`

      Number of key revisions used to encode samples in the |DW|'s queues, as
      defined by the :property:`dds.participant.trust_plugins.key_revision_max_history_depth`
      property. If the option is not selected, this property takes a value of
      0 (key revisions are disabled). If the option is selected, the number must
      be between 8 and 1000000.

  * - :guilabel:`Pre-shared secret passphrase`
    - :required:`Only required if pre-shared key protection is enabled`

      Seed used to derive the pre-shared key (in combination with publicly
      available data). The key is used for encoding and decoding RTPS messages.
      It is only effective in |SP_BUILTIN| if the Governance Document configures
      the :xmltag:`rtps_psk_protection_kind` to a value different than
      :xmlval:`NONE`. Otherwise, it has no effect.


.. list-table:: Fields to Configure Logging in |ADMINCONSOLE|
  :name: Fields to Configure Logging in Admin Console
  :widths: 35 65
  :header-rows: 1
  :class: longtable

  * - Field
    - Description

  * - :guilabel:`Security Logging Verbosity (local)`
    - :required:`Required`


      The logging verbosity level, as defined by the
      :property:`logging.verbosity` property.

      For details, see :numref:`|RTI_SP_PRODUCT_HEADING| Properties for Configuring Logging`.

|RTI_ADMINCONSOLE| and the |LIGHT_SP_BUILTIN|
=============================================

|ADMINCONSOLE| loads the |SP_BUILTIN| library (`nddssecurity`) when you check
:guilabel:`Enable Security for specified Domains` in the `Security` panel of
|ADMINCONSOLE|'s preferences.

Currently, there is no Graphical User Interface option to load the |LIGHT_SP_BUILTIN|
library (`nddslightweightsecurity`) instead of the |SP_BUILTIN|. However, you can
still use |ADMINCONSOLE| in combination with |LIGHT_SP_BUILTIN| if you set a custom
QoS profile that loads the |LIGHT_SP_BUILTIN| library. To do so, follow the instructions
in :link_external_community_kb:`Using your own QoS profile in RTI Admin Console <using-your-own-qos-profile-rti-admin-console>`
from our Knowledge Base. A simple QoS file would look like:

   .. code-block:: xml

      <?xml version="1.0"?>
      <dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://community.rti.com/schema/6.1.1/rti_dds_profiles.xsd">
        <qos_library name="ExampleAdminConsole">

          <qos_profile name="BaseProfile" base_name="BuiltinQosLib::Generic.Security">
            <!--
              Copy here the contents of the BaseProfile that you can find in
              $NDDSHOME/resource/xml/RTI_ADMIN_CONSOLE_EXAMPLE_PROFILE.xml

              It is important that now the profile inherits from
              "BuiltinQosLib::Generic.Security".
            -->
          </qos_profile>

          <qos_profile name="Default" base_name="ExampleAdminConsole::BaseProfile">
            <!--
              Copy here the contents of the Default that you can find in
              $NDDSHOME/resource/xml/RTI_ADMIN_CONSOLE_EXAMPLE_PROFILE.xml

              Nothing changes with respect to
              RTI_ADMIN_CONSOLE_EXAMPLE_PROFILE.xml.
            -->
          </qos_profile>

          <!--
            Load the |LIGHT_SP_BUILTIN_HEADING| and set the pre-shared key
            seed.
            You can configure additional QoS values here.
          -->
          <qos_profile name="PreSharedKey" base_name="ExampleAdminConsole::Default">
            <domain_participant_qos>
              <property>
                <value>
                  <element>
                    <name>com.rti.serv.secure.library</name>
                    <value>nddslightweightsecurity</value>
                  </element>
                  <element>
                    <name>dds.sec.crypto.rtps_psk_secret_passphrase</name>
                    <value>UseYourOwnSecretSeed</value>
                  </element>
                </value>
              </property>
            </domain_participant_qos>
          </qos_profile>
        </qos_library>
      </dds>
