From 5032a8e9c5605bb2a48b9bc56df799bc0c675591 Mon Sep 17 00:00:00 2001 From: Oleksandr Zharov Date: Thu, 25 Jan 2024 12:14:37 +0100 Subject: [PATCH] Update user guide with key-based auth Added example payload for device creation using key-based authentication. JIRA: NETCONF-1186 Change-Id: Iadb4f6651091113631d3ed1707ba86f00931a4ac Signed-off-by: Oleksandr Zharov --- docs/user-guide.rst | 277 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 273 insertions(+), 4 deletions(-) diff --git a/docs/user-guide.rst b/docs/user-guide.rst index ac21d62690..62df15cd23 100644 --- a/docs/user-guide.rst +++ b/docs/user-guide.rst @@ -125,7 +125,7 @@ without specifying the node in the URL: * - rfc8040 - http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf -Payload: +Payload for password authentication: .. tabs:: @@ -207,6 +207,180 @@ Payload: Additionally, it is important to ensure that the entire password is encoded in base64 format and that its length is a multiple of 16 bytes for successful authentication. +There is also option of using key-based authentication instead +of password. First we need to create key in datastore. + +*Adding a client private key credential to the netconf-keystore* + +.. code-block:: + + POST HTTP/1.1 + /rests/operations/netconf-keystore:add-keystore-entry + Content-Type: application/json + Accept: application/json + +.. code-block:: json + + { + "input": { + "key-credential": [ + { + "key-id": "example-client-key-id", + "private-key": "PEM-format-private-key", + "passphrase": "passphrase" + } + ] + } + } + +After we can use this key to create connector using this key. + +Payload for key-based authentication via SSH: + +.. tabs:: + + .. tab:: XML + + **Content-type:** ``application/xml`` + + **Accept:** ``application/xml`` + + **Authentication:** ``admin:admin`` + + .. code-block:: xml + + + new-netconf-device + 127.0.0.1 + 17830 + + admin + key-id + + false + + false + 20000 + 0 + 2000 + 1800000 + 1.5 + + 120 + + + .. tab:: JSON + + **Content-type:** ``application/json`` + + **Accept:** ``application/json`` + + **Authentication:** ``admin:admin`` + + .. code-block:: json + + { + "node": [ + { + "node-id": "new-netconf-device", + "netconf-node-topology:port": 17830, + "netconf-node-topology:reconnect-on-changed-schema": false, + "netconf-node-topology:connection-timeout-millis": 20000, + "netconf-node-topology:tcp-only": false, + "netconf-node-topology:max-connection-attempts": 0, + "netconf-node-topology:key-based": { + "netconf-node-topology:username": "admin", + "netconf-node-topology:key-id": "key-id" + }, + "netconf-node-topology:host": "127.0.0.1", + "netconf-node-topology:min-backoff-millis": 2000, + "netconf-node-topology:max-backoff-millis": 1800000, + "netconf-node-topology:backoff-multiplier": 1.5, + "netconf-node-topology:keepalive-delay": 120 + } + ] + } + +Connecting via TLS protocol is similar to SSH. First setup keystore +by using three RPCs from `Configure device to connect over TLS protocol`_ +to add a client private key, associate a private key with a client and CA +certificates chain and add a list of trusted CA and server certificates. +Only after that we can process and create a new NETCONF connector you need +to send the following PUT request. + +Payload for key-based authentication via TLS: + +.. tabs:: + + .. tab:: XML + + **Content-type:** ``application/xml`` + + **Accept:** ``application/xml`` + + **Authentication:** ``admin:admin`` + + .. code-block:: xml + + + new-netconf-device + 127.0.0.1 + 17830 + + admin + key-id + + false + + false + 20000 + 0 + 2000 + 1800000 + 1.5 + + 120 + + TLS + + + + .. tab:: JSON + + **Content-type:** ``application/json`` + + **Accept:** ``application/json`` + + **Authentication:** ``admin:admin`` + + .. code-block:: json + + { + "node": [ + { + "node-id": "new-netconf-device", + "netconf-node-topology:port": 17830, + "netconf-node-topology:reconnect-on-changed-schema": false, + "netconf-node-topology:connection-timeout-millis": 20000, + "netconf-node-topology:tcp-only": false, + "netconf-node-topology:max-connection-attempts": 0, + "netconf-node-topology:key-based": { + "netconf-node-topology:username": "admin", + "netconf-node-topology:key-id": "key-id" + }, + "netconf-node-topology:host": "127.0.0.1", + "netconf-node-topology:min-backoff-millis": 2000, + "netconf-node-topology:max-backoff-millis": 1800000, + "netconf-node-topology:backoff-multiplier": 1.5, + "netconf-node-topology:keepalive-delay": 120, + "protocol": { + "name": "TLS" + } + } + ] + } + + Note that the device name in element must match the last element of the restconf URL. @@ -995,7 +1169,102 @@ Preconditions: - Netopeer is up and running in docker -Now just follow the section: `Spawning new NETCONF connectors`_. +Now just follow the section: `Spawning new NETCONF connectors`_ for +password authentication. +In the payload change the: + +- name, e.g., to netopeer + +- username/password to your system credentials + +- ip to localhost + +- port to 830. + +After netopeer is mounted successfully, its configuration can be read +using RESTCONF by invoking: + +GET +http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=netopeer/yang-ext:mount?content:config + +Mounting netopeer NETCONF server using key-based authentication SSH +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Install docker https://docs.docker.com/get-started/ + +2. Create RSA key pair - it will be user for connection. + +3. Start the netopeer image(this command will also copy you pub key + into docker container): + + :: + + docker run -dt -p 830:830 -v {path-to-pub-key}:/home/{netopeer-username}/.ssh/authorized_keys sysrepo/sysrepo-netopeer2:latest netopeer2-server -d -v 2 + +4. Verify netopeer is running by invoking (netopeer should send its + HELLO message right away: + + :: + + ssh root@localhost -p 830 -s netconf + (password root) + +Now just follow the section: `Spawning new NETCONF connectors`_ for +key-based authentication(SSH) to create device. +In the payload change the: + +- name, e.g., to netopeer + +- username/password to your system credentials + +- ip to localhost + +- port to 830. + +After netopeer is mounted successfully, its configuration can be read +using RESTCONF by invoking: + +GET +http://localhost:8181/rests/data/network-topology:network-topology/topology=topology-netconf/node=netopeer/yang-ext:mount?content:config + +Mounting netopeer NETCONF server using key-based authentication TLS +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +1. Install docker https://docs.docker.com/get-started/ + +2. Run netopeer2 + + :: + + docker pull sysrepo/sysrepo-netopeer2 + docker run -it --name sysrepo -p 830:830 --rm sysrepo/sysrepo-netopeer2:latest + +3. Enable TLS communication on server netopeer2 + + :: + + ssh root@localhost -p 830 -s netconf + (type password root) + + After successful connecting to netopeer2 setup your + TLS configuration xml + (See: https://github.com/CESNET/netopeer2/tree/master/example_configuration). + +4. Run ODL: + +- :~/netconf/karaf/target/assembly/bin$ ./karaf + +- feature:install odl-netconf-topology odl-restconf-nb-bierman02 odl-mdsal-apidocs + +5. Set up ODL netconf keystore + + To setup keystore is needed to send three RPCs from + `Configure device to connect over TLS protocol`_ + to add a client private key, associate a private key with a client and CA + certificates chain and add a list of trusted CA and server certificates. + +Now just follow the section: `Spawning new NETCONF connectors`_ for +key-based authentication(TLS) to create device. In the payload change the: - name, e.g., to netopeer @@ -1004,7 +1273,7 @@ In the payload change the: - ip to localhost -- port to 1831. +- port to 830. After netopeer is mounted successfully, its configuration can be read using RESTCONF by invoking: @@ -1537,7 +1806,7 @@ storing them within the netconf-keystore. "key-credential": [ { "key-id": "example-client-key-id", - "private-key": "base64encoded-private-key", + "private-key": "PEM-format-private-key", "passphrase": "passphrase" } ] -- 2.36.6