X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fuser-guide%2Fauthentication-and-authorization-services.rst;h=32fcd71a4c117c75e7aa43acc314f3a8fcd10c31;hb=9a9b923cfbee16adc5085f5d64b2ef1db0328cb0;hp=9ff989e8f5f3ed552b690cb523474066270430b1;hpb=0a74269a606de7241c841f41b1f741aa0699b203;p=docs.git diff --git a/docs/user-guide/authentication-and-authorization-services.rst b/docs/user-guide/authentication-and-authorization-services.rst index 9ff989e8f..32fcd71a4 100644 --- a/docs/user-guide/authentication-and-authorization-services.rst +++ b/docs/user-guide/authentication-and-authorization-services.rst @@ -1,46 +1,89 @@ Authentication, Authorization and Accounting (AAA) Services =========================================================== -The Boron AAA services are based on the Apache Shiro Java Security -Framework. The main configuration file for AAA is located at -“etc/shiro.ini” relative to the ODL karaf home directory. +Overview +-------- + +Authentication, Authorization and Accounting (AAA) is a term for a +framework controlling access to resources, enforcing policies to use +those resources and auditing their usage. These processes are the +fundamental building blocks for effective network management and security. + +Authentication provides a way of identifying a user, typically by +having the user enter a valid user name and valid password before access +is granted. The process of authentication is based on each user having a unique +set of criteria for gaining access. The AAA framework compares a user's +authentication credentials with other user credentials stored in a database. +If the credentials match, the user is granted access to the network. +If the credentials don't match, authentication fails and access is denied. + +Authorization is the process of finding out what an authenticated user is +allowed to do within the system, which tasks can do, which API can call, etc. +The authorization process determines whether the user has the authority +to perform such actions. + +Accounting is the process of logging the activity of an authenticated user, +for example, the amount of data a user has sent and/or received during a +session, which APIs called, etc. Terms And Definitions ---------------------- +^^^^^^^^^^^^^^^^^^^^^ + +AAA + Authentication, Authorization and Accounting. Token - A claim of access to a group of resources on the controller + A claim of access to a group of resources on the controller. Domain A group of resources, direct or indirect, physical, logical, or - virtual, for the purpose of access control. ODL recommends using the - default “sdn" domain in the Boron release. + virtual, for the purpose of access control. User A person who either owns or has access to a resource or group of - resources on the controller + resources on the controller. Role Opaque representation of a set of permissions, which is merely a - unique string as admin or guest + unique string as admin or guest. Credential - Proof of identity such as username and password, OTP, biometrics, or - others + Proof of identity such as user name and password, OTP, biometrics, or + others. Client - A service or application that requires access to the controller + A service or application that requires access to the controller. Claim A data set of validated assertions regarding a user, e.g. the role, domain, name, etc. +IdP + Identity Provider. + +TLS + Transport Layer Security + +CLI + Command Line Interface + +Security Framework for AAA services +----------------------------------- + +Since Boron release, the OpenDaylight's AAA services are based on the +`Apache Shiro `_ Java Security Framework. The main +configuration file for AAA is located at “etc/shiro.ini” relative to the +OpenDaylight Karaf home directory. + + How to enable AAA ----------------- -AAA is enabled through installing the odl-aaa-shiro feature. -odl-aaa-shiro is automatically installed as part of the odl-restconf -offering. +AAA is enabled through installing the odl-aaa-shiro feature. The vast majority +of OpenDaylight's northbound APIs (and all RESTCONF APIs) are protected by AAA +by default when installing the +odl-restconf+ feature, since the odl-aaa-shiro +is automatically installed as part of them. In the cases that APIs are *not* +protected by AAA, this will be noted in the per-project release notes. How to disable AAA ------------------ @@ -57,54 +100,12 @@ with /** = anon -Then restart the karaf process. - -.. note:: - - This is a change from the Lithium release, in which - “etc/org.opendaylight.aaa.authn.cfg” was edited to set - “authEnabled=false”. Please use the “shiro.ini” mechanism to disable - AAA going forward. - -How application developers can leverage AAA to provide servlet security ------------------------------------------------------------------------ - -In order to provide security to a servlet, add the following to the -servlet’s web.xml file as the first filter definition: - -:: - - - shiroEnvironmentClass - org.opendaylight.aaa.shiro.web.env.KarafIniWebEnvironment - - - - org.apache.shiro.web.env.EnvironmentLoaderListener - - - - ShiroFilter - org.opendaylight.aaa.shiro.filters.AAAShiroFilter - - - - AAAShiroFilter - /* - - -.. note:: - - It is very important to place this AAAShiroFilter as the first - javax.servlet.Filter, as Jersey applies Filters in the order they - appear within web.xml. Placing the AAAShiroFilter first ensures - incoming HTTP/HTTPS requests have proper credentials before any - other filtering is attempted. +Then restart the Karaf process. AAA Realms ---------- -AAA plugin utilizes realms to support pluggable authentication & +AAA plugin utilizes the Shiro Realms to support pluggable authentication & authorization schemes. There are two parent types of realms: - AuthenticatingRealm @@ -121,14 +122,14 @@ authorization schemes. There are two parent types of realms: based on roles. - Useful for applications in which roles determine allowed - cabilities. + capabilities. -ODL Contains Four Implementations +OpenDaylight contains five implementations: - TokenAuthRealm - An AuthorizingRealm built to bridge the Shiro-based AAA service - with the Lithium h2-based AAA implementation. + with the h2-based AAA implementation. - Exposes a RESTful web service to manipulate IdM policy on a per-node basis. If identical AAA policy is desired across a @@ -138,15 +139,15 @@ ODL Contains Four Implementations - A python script located at “etc/idmtool” is included to help manipulate data contained in the TokenAuthRealm. - - Enabled out of the box. + - Enabled out of the box. This is the realm configured by default. - ODLJndiLdapRealm - An AuthorizingRealm built to extract identity information from IdM data contained on an LDAP server. - - Extracts group information from LDAP, which is translated into ODL - roles. + - Extracts group information from LDAP, which is translated into + OpenDaylight roles. - Useful when federating against an existing LDAP server, in which only certain types of users should have certain access privileges. @@ -161,34 +162,64 @@ ODL Contains Four Implementations - Disabled out of the box. -- ActiveDirectoryRealm +- ODLActiveDirectoryRealm + + - Wraps the generic ActiveDirectoryRealm provided by Shiro. This allows for + enhanced logging as well as isolation of all realms in a single package, + which enables easier import by consuming servlets. + +- KeystoneAuthRealm + + - This realm authenticates OpenDaylight users against the OpenStack’s + Keystone server. + + - Disabled out of the box. .. note:: - More than one Realm implementation can be specified. Realms are - attempted in order until authentication succeeds or all realm - sources are exhausted. + More than one Realm implementation can be specified. Realms are attempted + in order until authentication succeeds or all realm sources are exhausted. + Edit the **securityManager.realms = $tokenAuthRealm** property in shiro.ini + and add all the realms needed separated by commas. -TokenAuthRealm Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +TokenAuthRealm +^^^^^^^^^^^^^^ -TokenAuthRealm stores IdM data in an h2 database on each node. Thus, -configuration of a cluster currently requires configuring the desired -IdM policy on each node. There are two supported methods to manipulate -the TokenAuthRealm IdM configuration: +How it works +~~~~~~~~~~~~ -- idmtool Configuration +The TokenAuthRealm is the default Authorization Realm deployed in OpenDaylight. +TokenAuthRealm uses a direct authentication mechanism as shown in the following +picture: -- RESTful Web Service Configuration +.. figure:: ./images/aaa/direct-authentication.png + :alt: TokenAuthRealm direct authentication mechanism -idmtool Configuration -^^^^^^^^^^^^^^^^^^^^^ + TokenAuthRealm direct authentication mechanism + +A user presents some credentials (e.g., username/password) directly to the +OpenDaylight controller token endpoint /oauth2/token and receives an access +token, which then can be used to access protected resources on the controller. + +Configuring TokenAuthRealm +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The TokenAuthRealm stores IdM data in an h2 database on each node. Thus, +configuration of a cluster currently requires configuring the desired IdM policy +on each node. There are two supported methods to manipulate the TokenAuthRealm +IdM configuration: + +- idmtool configuration tool + +- RESTful Web Service configuration + +**Idmtool** +########### A utility script located at “etc/idmtool” is used to manipulate the -TokenAuthRealm IdM policy. idmtool assumes a single domain (sdn), since -multiple domains are not leveraged in the Boron release. General usage -information for idmtool is derived through issuing the following -command: +TokenAuthRealm IdM policy. idmtool assumes a single domain, the default one +(sdn), since multiple domains are not supported in the Boron release. General +usage information for idmtool is derived through issuing the following command: :: @@ -463,8 +494,8 @@ Get grants for a user ] } -RESTful Web Service -^^^^^^^^^^^^^^^^^^^ +**Configuration using the RESTful Web Service** +############################################### The TokenAuthRealm IdM policy is fully configurable through a RESTful web service. Full documentation for manipulating AAA IdM data is located @@ -563,16 +594,35 @@ Use an OAuth2 Token ] } -ODLJndiLdapRealm Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Token Store Configuration Parameters** +######################################## + +Edit the file “etc/opendaylight/karaf/08-authn-config.xml” and edit the +following: .\ **timeToLive**: Configure the maximum time, in milliseconds, +that tokens are to be cached. Default is 360000. Save the file. + +ODLJndiLdapRealm +^^^^^^^^^^^^^^^^ + +How it works +~~~~~~~~~~~~ LDAP integration is provided in order to externalize identity -management. To configure LDAP parameters, modify "etc/shiro.ini" +management. This configuration allows federation with an external LDAP server. +The user’s OpenDaylight role parameters are mapped to corresponding LDAP +attributes as specified by the groupRolesMap. Thus, an LDAP operator can +provision attributes for LDAP users that support different OpenDaylight role +structures. + +Configuring ODLJndiLdapRealm +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure LDAP parameters, modify "etc/shiro.ini" parameters to include the ODLJndiLdapRealm: :: - # ODL provides a few LDAP implementations, which are disabled out of the box. + # OpenDaylight provides a few LDAP implementations, which are disabled out of the box. # ODLJndiLdapRealm includes authorization functionality based on LDAP elements # extracted through and LDAP search. This requires a bit of knowledge about # how your LDAP system is setup. An example is provided below: @@ -587,14 +637,16 @@ parameters to include the ODLJndiLdapRealm: # Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted. securityManager.realms = $tokenAuthRealm, $ldapRealm -This configuration allows federation with an external LDAP server, and -the user’s ODL role parameters are mapped to corresponding LDAP -attributes as specified by the groupRolesMap. Thus, an LDAP operator can -provision attributes for LDAP users that support different ODL role -structures. +ODLJndiLdapRealmAuthNOnly +^^^^^^^^^^^^^^^^^^^^^^^^^ + +How it works +~~~~~~~~~~~~ + +This is useful for setups where all LDAP users are allowed equal access. -ODLJndiLdapRealmAuthNOnly Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configuring ODLJndiLdapRealmAuthNOnly +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Edit the "etc/shiro.ini" file and modify the following: @@ -608,36 +660,111 @@ Edit the "etc/shiro.ini" file and modify the following: # Stacked realm configuration; realms are round-robbined until authentication succeeds or realm sources are exhausted. securityManager.realms = $tokenAuthRealm, $ldapRealm -This is useful for setups where all LDAP users are allowed equal access. +KeystoneAuthRealm +^^^^^^^^^^^^^^^^^ -Token Store Configuration Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How it works +~~~~~~~~~~~~ -Edit the file “etc/opendaylight/karaf/08-authn-config.xml” and edit the -following: .\ **timeToLive**: Configure the maximum time, in -milliseconds, that tokens are to be cached. Default is 360000. Save the -file. +This realm authenticates OpenDaylight users against the OpenStack's Keystone +server. This realm uses the +`Keystone's Identity API v3 `_ +or later. + +.. figure:: ./images/aaa/keystonerealm-authentication.png + :alt: KeystoneAuthRealm authentication mechanism + + KeystoneAuthRealm authentication/authorization mechanism + +As can shown on the above diagram, once configured, all the RESTCONF APIs calls +will require sending **user**, **password** and optionally **domain** (1). Those +credentials are used to authenticate the call against the Keystone server (2) and, +if the authentication succeeds, the call will proceed to the MDSAL (3). The +credentials must be provisioned in advance within the Keystone Server. The user +and password are mandatory, while the domain is optional, in case it is not +provided within the REST call, the realm will default to (**Default**), +which is hard-coded. The default domain can be also configured through the +*shiro.ini* file (see the :doc:`AAA User Guide <../user-guide/authentication-and-authorization-services>`). + +The protocol between the Controller and the Keystone Server (2) can be either +HTTPS or HTTP. In order to use HTTPS the Keystone Server's certificate +must be exported and imported on the Controller (see the :ref:`Certificate Management ` section). + +Configuring KeystoneAuthRealm +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Edit the "etc/shiro.ini" file and modify the following: + +:: + + # The KeystoneAuthRealm allows for authentication/authorization against an + # OpenStack's Keystone server. It uses the Identity's API v3 or later. + keystoneAuthRealm = org.opendaylight.aaa.shiro.realm.KeystoneAuthRealm + # The URL where the Keystone server exposes the Identity's API v3 the URL + # can be either HTTP or HTTPS and it is mandatory for this realm. + keystoneAuthRealm.url = https://: + # Optional parameter to make the realm verify the certificates in case of HTTPS + #keystoneAuthRealm.sslVerification = true + # Optional parameter to set up a default domain for requests using credentials + # without domain, uncomment in case you want a different value from the hard-coded + # one "Default" + #keystoneAuthRealm.defaultDomain = Default + +Once configured the realm, the mandatory fields are the fully quallified name of +the class implementing the realm *keystoneAuthRealm* and the endpoint where the +Keystone Server is listening *keystoneAuthRealm.url*. + +The optional parameter *keystoneAuthRealm.sslVerification* specifies whether the +realm has to verify the SSL certificate or not. The optional parameter +*keystoneAuthRealm.defaultDomain* allows to use a different default domain from +the hard-coded one *"Default"*. Authorization Configuration --------------------------- -Shiro-Based Authorization -~~~~~~~~~~~~~~~~~~~~~~~~~ +OpenDaylight supports two authorization engines at present, both of which are +roughly similar in behavior: + +- Shiro-Based Authorization + +- MDSAL-Based Dynamic Authorization + +.. note:: + + The preferred mechanism for configuring AAA Authentication is the + MDSAL-Based Dynamic Authorization. Read the following section. + +Shiro-Based Static Authorization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -OpenDaylight AAA has support for Role Based Access Control based on the -Apache Shiro permissions system. Configuration of the authorization -system is done offline; authorization currently cannot be configured -after the controller is started. Thus, Authorization in the Beryllium -release is aimed towards supporting coarse-grained security policies, -with the aim to provide more robust configuration capabilities in the -future. Shiro-based Authorization is documented on the Apache Shiro -website (http://shiro.apache.org/web.html#Web-%7B%7B%5Curls%5C%7D%7D). +OpenDaylight AAA has support for Role Based Access Control (RBAC) based +on the Apache Shiro permissions system. Configuration of the authorization +system is done off-line; authorization currently cannot be configured +after the controller is started. The Authorization provided by this mechanism +is aimed towards supporting coarse-grained security policies, the MDSAL-Based +mechanism allows for a more robust configuration capabilities. `Shiro-based +Authorization `_ +describes how to configure the Authentication feature in detail. + +.. notes:: + + The Shiro-Based Authorization that uses the *shiro.ini* URLs section to + define roles requirements is **deprecated** and **discouraged** since the + changes made to the file are only honored on a controller restart. + + Shiro-Based Authorization is not **cluster-aware**, so the changes made on + the *shiro.ini* file have to be replicated on every controller instance + belonging to the cluster. + + The URL patterns are matched relative to the Servlet context leaving room + for ambiguity, since many endpoints may match (i.e., "/restconf/modules" and + "/auth/modules" would both match a "/modules/\**" rule). Enable “admin” Role Based Access to the IdMLight RESTful web service ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Edit the “etc/shiro.ini” configuration file and add “/auth/v1/\ **= -authcBasic, roles[admin]” above the line “/** = authcBasic” within the +Edit the “etc/shiro.ini” configuration file and add “/auth/v1/\**= +authcBasic, roles[admin]” above the line “/\** = authcBasic” within the “urls” section. :: @@ -652,52 +779,298 @@ role must be present for the requesting user. The ordering of the authorization rules above is important! -AuthZ Broker Facade -~~~~~~~~~~~~~~~~~~~ +MDSAL-Based Dynamic Authorization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The MDSAL-Based Dynamic authorization uses the MDSALDynamicAuthorizationFilter +engine to restrict access to particular URL endpoint patterns. Users may define +a list of policies that are insertion-ordered. Order matters for that list of +policies, since the first matching policy is applied. This choice was made to +emulate behavior of the Shiro-Based Authorization mechanism. -ODL includes an experimental Authorization Broker Facade, which allows -finer grained access control for REST endpoints. Since this feature was -not well tested in the Boron release, it is recommended to use the -Shiro-based mechanism instead, and rely on the Authorization Broker -Facade for POC use only. +A **policy** is a key/value pair, where the key is a **resource** +(i.e., a "URL pattern") and the value is a list of **permissions** for the +resource. The following describes the various elements of a policy: -AuthZ Broker Facade Feature Installation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +- **Resource**: the resource is a string URL pattern as outlined by + Apache Shiro. For more information, see http://shiro.apache.org/web.html. -To install the authorization broker facade, please issue the following -command in the karaf shell: +- **Description**: an optional description of the URL endpoint and why it is + being secured. -:: - - feature:install odl-restconf odl-aaa-authz +- **Permissions list**: a list of permissions for a particular policy. If more + than one permission exists in the permissions list they are evaluated using + logical "OR". A permission describes the prerequisites to perform HTTP + operations on a particular endpoint. The following describes the various + elements of a permission: -Add an Authorization Rule -^^^^^^^^^^^^^^^^^^^^^^^^^ + + **Role**: the role required to access the target URL endpoint. + + **Actions list**: a leaf-list of HTTP permissions that are allowed for a + Subject possessing the required role. -The following shows how one might go about securing the controller so -that only admins can access restconf. +This an example on how to limit access to the modules endpoint: :: - curl -u admin:admin -H “Content-Type: application/xml” --data-binary @./rule.json http://localhost:8181/restconf/config/authorization-schema:simple-authorization/policies/RestConfService/ - cat ./rule.json - { - "policies": { - "resource": "*", - "service":"RestConfService", - "role": "admin" + HTTP Operation: + put URL: /restconf/config/aaa:http-authorization/policies + + headers: Content-Type: application/json Accept: application/json + + body: + { "aaa:policies": + { "aaa:policies": + [ { "aaa:resource": "/restconf/modules/**", + "aaa:permissions": [ { "aaa:role": "admin", + "aaa:actions": [ "get", + "post", + "put", + "patch", + "delete" + ] + } + ] + } + ] } - } + } + +The above example locks down access to the modules endpoint (and any URLS +available past modules) to the "admin" role. Thus, an attempt from the OOB +*admin* user will succeed with 2XX HTTP status code, while an attempt from the +OOB *user* user will fail with HTTP status code 401, as the user *user* is not +granted the "admin" role. Accounting Configuration ------------------------ -All AAA logging is output to the standard karaf.log file. +Accounting is handled through the standard slf4j logging mechanisms used by the +rest of OpenDaylight. Thus, one can control logging verbosity through +manipulating the log levels for individual packages and classes directly through +the Karaf console, JMX, or etc/org.ops4j.pax.logging.cfg. In normal operations, +the default levels exposed do not provide much information about AAA services; +this is due to the fact that logging can severely degrade performance. + +All AAA logging is output to the standard karaf.log file. For debugging purposes +(i.e., to enable maximum verbosity), issue the following command: :: log:set TRACE org.opendaylight.aaa -This command enables the most verbose level of logging for AAA -components. +Enable Successful/Unsuccessful Authentication Attempts Logging +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, successful/unsuccessful authentication attempts are NOT logged. This +is due to the fact that logging can severely decrease REST performance. +To enable logging of successful/unsuccessful REST attempts, issue the following +command in Karaf's console: + +:: + + log:set DEBUG org.opendaylight.aaa.shiro.filters.AuthenticationListener + +It is possible to add custom AuthenticationListener(s) to the Shiro-based +configuration, allowing different ways to listen for successful/unsuccessful +authentication attempts. Custom AuthenticationListener(s) must implement +the org.apache.shiro.authc.AuthenticationListener interface. + +.. _certificate-management: +Certificate Management +---------------------- + +The **Certificate Management Service** is used to manage the keystores and +certificates at the OpenDaylight distribution to easily provides the TLS +communication. + +The Certificate Management Service managing two keystores: + +1. **OpenDaylight Keystore** which holds the OpenDaylight distribution + certificate self sign certificate or signed certificate from a root CA based + on generated certificate request. + +2. **Trust Keystore** which holds all the network nodes certificates that shall + to communicate with the OpenDaylight distribution through TLS communication. + +The Certificate Management Service stores the keystores (OpenDaylight & Trust) +as *.jks* files under configuration/ssl/ directory. Also the keystores +could be stored at the MD-SAL datastore in case OpenDaylight distribution +running at cluster environment. When the keystores are stored at MD-SAL, +the Certificate Management Service rely on the **Encryption-Service** to encrypt +the keystore data before storing it to MD-SAL and decrypted at runtime. + +How to use the Certificate Management Service to manage the TLS communication +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following are the steps to configure the TLS communication: + +1. After starting the distribution, the *odl-aaa-cert* feature has to get +installed. Use the following command at Karaf CLI to check. + +.. code-block:: bash + + opendaylight-user@root>feature:list -i | grep aaa-cert + odl-aaa-cert | 0.5.0-SNAPSHOT | x | odl-aaa-0.5.0-SNAPSHOT | OpenDaylight :: AAA :: aaa certificate Service + +2. The initial configuration of the Certificate Manager Service exists under +the distribution directory etc/opendaylight/datastore/initial/config/aaa-cert-config.xml. + +.. code-block:: xml + + + false + false + opendaylight + + ctl.jks + controller + + CN=ODL, OU=Dev, O=LinuxFoundation, L=QC Montreal, C=CA + 365 + RSA + SHA1WithRSAEncryption + 1024 + + + + + + truststore.jks + + + + + +Now as it is explained above, the Certificate Manager Service support two mode +of operations; cluster mode and single mode. To use the single mode change the +use-config to true and it is recommended as long as there is no need for +cluster environment. To use the cluster mode change the use-config and +use-mdsal configurations to true and the keystores will be stored and shard +across the cluster nodes within the MD-SAL datastore. + +The initial password become randomly generated when the *aaa-cert* feature is +installed. + +The cipher suites can be restricted by changing the **** +configuration, however, the JDK has to be upgraded by installing the `Java +Cryptography Extension +`_ +policy. + +.. code-block:: xml + + + TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 + + + TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 + + + TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 + + +3. The new configurations will take affect after restarting the distribution. + +4. Now to add or get certificate to the OpenDaylight and Trust keystores, the +Certificate Manager Service provides the following RPCs. + +:: + + a) Set the node certificate that will communicate with OpeDaylight through TLS + connection. + POST /operations/aaa-cert-rpc:setNodeCertifcate + { + "input": { + "node-cert": "string", + "node-alias": "string" + } + } + +:: + + b) Get the node certificate based on node alias. + POST /operations/aaa-cert-rpc:getNodeCertifcate + { + "input": { + "node-alias": "string" + } + } + +:: + + c) Get the OpeDaylight keystore certificate. + POST /operations/aaa-cert-rpc:getODLCertificate + { + output { + odl-cert "string" + } + } + +:: + + d) Generate a certificate request from the OpeDaylight keystore to be signed + by a CA. + POST /operations/aaa-cert-rpc:getODLCertificateReq + { + output { + odl-cert-req "string" + } + } + +:: + + e) Set the OpeDaylight certificate, the certificate should be generated + based on a certificate request generated from the ODL keystore otherwise the + certificated will not be added. + POST /operations/aaa-cert-rpc:setODLCertificate + { + "input": { + "odl-cert-alias": "string", + "odl-cert": "string" + } + } + +.. note:: + + The Certificate Manager Service RPCs are allowed only to the Role Admin Users + and it could be completely disabled through the shiro.ini config file. Check + the URL section at the shiro.ini. + +Encryption Service +------------------ + +The **AAA Encryption Service** is used to encrypt the OpenDaylight's users' +passwords and TLS communication certificates. This section shows how to use the +AAA Encryption Service with an OpenDaylight distribution project to encrypt data. + +The following are the steps to configure the Encryption Service: + +1. After starting the distribution, the *aaa-encryption-service* feature has to + get installed. Use the following command at Karaf CLI to check. + + .. code-block:: bash + + opendaylight-user@root>feature:list -i | grep aaa-encryption-service + odl-aaa-encryption-service | 0.5.0-SNAPSHOT | x | odl-aaa-0.5.0-SNAPSHOT | OpenDaylight :: AAA :: Encryption Service + +2. The initial configuration of the Encryption Service exists under the + distribution directory etc/opendaylight/datastore/initial/config/aaa-encrypt-service-config.xml + + .. code-block:: xml + + + + + PBKDF2WithHmacSHA1 + AES + 32768 + 128 + AES/CBC/PKCS5Padding + + + .. note:: + + Both the initial encryption key and encryption salt become randomly generated + when the *aaa-encryption-service* feature is installed. +3. Finally the new configurations will take affect after restarting the + distribution.