diff --git a/src/cli/README.md b/src/cli/README.md index f3494b924..fb4a47271 100644 --- a/src/cli/README.md +++ b/src/cli/README.md @@ -14,8 +14,8 @@ OpenThread test scripts use the CLI to execute test cases. * [childip](#childip) * [childmax](#childmax) * [childtimeout](#childtimeout) -* [coap](#coap-start) -* [coaps](#coaps-start-checkpeercert) +* [coap](README_COAP.md) +* [coaps](README_COAPS.md) * [commissioner](#commissioner-start-provisioningurl) * [contextreusedelay](#contextreusedelay) * [counters](#counters) @@ -232,157 +232,6 @@ Set the Thread Child Timeout value. Done ``` -### coap start - -Starts the application coap service. - -```bash -> coap start -Coap service started: Done -``` - -### coap stop - -Stops the application coap service. - -```bash -> coap stop -Coap service stopped: Done -``` - -### coap resource \[uri-path\] - -Sets the URI-Path for the test resource. - -```bash -> coap resource test -Resource name is 'test': Done -> coap resource -Resource name is 'test': Done -``` - -### coap \ \ \ \[payload\] \[type\] - -* method: CoAP method to be used (GET/PUT/POST/DELETE). -* address: IP address of the CoAP server to query. -* uri: URI String of the resource on the CoAP server. -* payload: In case of PUT/POST/DELETE a payload can be encapsulated. -* type: Switch between confirmable ("con") and non-confirmable (default). - -```bash -> coap get fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc test -Sending coap message: Done -Received coap request from [fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc]: GET -coap response sent successfully! -Received coap response with payload: 30 -> coap put fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc test non-con somePayload -Sending coap message: Done -Received coap request from [fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc]: PUT with payload: 73 6f 6d 65 50 61 79 6c 6f 61 64 -> coap put fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc test con 123 -Sending coap message: Done -Received coap request from [fdde:ad00:beef:0:dbaa:f1d0:8afb:30dc]: PUT with payload: 31 32 33 -coap response sent successfully! -Received coap response -``` - -### coaps start \ - -Starts the Application CoAP Secure Service. - -* checkPeerCert: Peer Certificate Check can be disabled by typing false. - -```bash -> coaps start false -Verify Peer Certificate: false. Coap Secure service started: Done -> coaps start -Verify Peer Certificate: true. Coap Secure service started: Done -``` - -### coaps stop - -Stops the Application CoAP Secure Service. - -```bash -> coaps stop -Coap Secure service stopped: Done -``` - -### coaps set psk \ \ - -Set a pre-shared key with his identifier and the ciphersuite -"DTLS_PSK_WITH_AES_128_CCM_8" for the dtls session. - -* preSharedKey: The pre-shared key (PSK) for dtls session. -* keyIdentity: The identifier for the PSK. - -```bash -> coaps set psk myPreSharedSecret myIdentifier -Coap Secure set PSK: Done -``` - -### coaps set x509 - -Set X.509 Certificate with his private key, which is saved in -src/cli/x509_cert_key.hpp. - -```bash -> coaps set x509 -Coap Secure set own .X509 certificate: Done -``` - -### coaps connect \ \[port\] - -Open a dtls session to a CoAP Secure Server. - -* serverAddress: IPv6 address of Server - -```bash -> coaps connect 2001:1234::321 -Coap Secure connect: Done -CoAP Secure connected! -``` - -### coaps disconnect - -Terminate the dtls session to the Server. - -```bash -> coaps disconnect -CoAP Secure not connected or disconnected. -Done -``` - -### coaps \ \ \ \[type\] \[payload\] - -* method: CoAP method to be used (GET/PUT/POST/DELETE). -* address: IPv6 address of the CoAP Secure server to query. -* uri: URI String of the resource on the CoAP server. -* type: Switch between confirmable ("con") and non-confirmable (default). -* payload: In case of PUT/POST/DELETE a payload can be encapsulated. - -```bash -> coaps get 2001:1234::321 secret -Sending coap secure request: Done -Received coap secure response - CoapSecure RX Header Informations: - Type 16 (NON CONF) - Code 69 (Coap Code CONTENT) - With payload (hex): -4a756e2031322031353a30373a3336 -> coaps put 2001:1234::321 test non-con hello -Sending coap secure request: Done -> coaps post 2001:1234::321 test con -Sending coap secure request: Done -Received coap secure response - CoapSecure RX Header Informations: - Type 32 (NON CONF) - Code 69 (Coap Code CONTENT) - With payload (hex): -4a756e2031322031353a30373a3336 -> coaps delete 2001:1234::321 test -Sending coap secure request: Done -``` - ### commissioner start \ Start the Commissioner role. diff --git a/src/cli/README_COAPS.md b/src/cli/README_COAPS.md index a0f7f76a8..a0c9edfa3 100644 --- a/src/cli/README_COAPS.md +++ b/src/cli/README_COAPS.md @@ -1,155 +1,245 @@ -# OpenThread CLI - COAPS Example +# OpenThread CLI - CoAPS Example -The OpenThread CoAP Secure APIs may be invoked via the OpenThread CLI. +The OpenThread CoAPS APIs may be invoked via the OpenThread CLI. -CoAP Secure use DTLS (over UDP) to make an end to end encrypted connection. +## Quick Start -### For use PSK with AES128 CCM8 +### Build with CoAPS API support + +Use the `COAPS=1` build switch to enable CoAPS API support. - 1a. enter your psk and his identifier - ```bash -coaps set psk +> ./bootstrap +> make -f examples/Makefile-posix COAPS=1 ``` -### For use ECDHE ECDSA with AES128 CCM8 +### Form Network - 1b. set the private key and .X509 certificate stored in core/cli/x509_cert_key.hpp. - - > _optional_: add your [own](#create-ec-private-key) X.509 certificate and private key to 'core/cli/x509_cert_key.hpp'. - -```bash -coaps set x509 -``` +Form a network with at least two devices. -## Start CoAPS Service (for Server and Client) +### Configure DTLS ciphersuite. + +CoAPS uses DTLS to establish a secure, end-to-end connection. + +This example supports two ciphersuites: + +* TLS_PSK_WITH_AES_128_CCM_8 + ```bash + > coaps psk + Done + ``` + +* TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 + ```bash + > coaps x509 + Done + ``` +The X.509 certificate stored in `core/cli/x509_cert_key.hpp`. + +### Node 1 + +On node 1, setup CoAPS server with resource `test-resource`. - 2. start (init) the coaps api and starts listen on coaps port (5684) - ```bash > coaps start +Done +> coaps resource test-resource +Done ``` -## CoAP Secure Server - - * add a coap resource to provide to a coap client - -```bash -coaps resource -``` - -## Connect to a DTLS Server - - * connect to a dtls server - -```bash -coaps connect (port, if not default) -``` - -## CoAP Secure Client - -* get a resource form the server +### Node 2 ```bash -coaps get (serversIp) (Con/NotCon) (payload) +> coaps start +Done +> coaps connect +Done +coaps connected +> coaps get test-resource +Done +coaps response from [fdde:ad00:beef:0:9903:14b:27e0:5744] with payload: 68656c6c6f576f726c6400 +> coaps put test-resource con payload +Done +coaps response from [fdde:ad00:beef:0:9903:14b:27e0:5744] ``` -> post, put and delete also possible - - -<> must -() opt - - -## Complete example for DTLS/CoAP server (Node 1) +### Result -In this example the coap server is also the dtls server. -The dtls server waits for incoming connection on coaps port 5684. -The [Node 2](#complete-example-dtlscoap-client-node-2) below is able to connect to this coaps server. - -> Note: Node 1 and Node 2 must use the same mode. Either PSK or Certificate based. - -``` - Node 1 ---------- -|CoAPS | -|Server | <--Listen on Port 5684-- (Node 2) -| | ---------- -``` - -### with PSK +On node 1, you should see output similar to below: ```bash -coaps set psk secretPSK Client_identity -coaps start -coaps resource test +coaps request from [fdde:ad00:beef:0:9e68:576f:714c:f395] GET +coaps response sent +coaps request from [fdde:ad00:beef:0:9e68:576f:714c:f395] PUT with payload: 7061796c6f6164 +coaps response sent ``` -### with Certificate +## Generate Elliptic Curve Private Key and X.509 Certificate + +### EC Private Key ```bash -coaps set x509 -coaps start (false) -coaps resource test +> openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem ``` -* param false: optional, disables peer certificate validation. - -## Complete example DTLS/CoAP client (Node 2) - -In this example the coap client is also the dtls client. -The dlts client can connect to a coaps server which is listen on coaps port 5684, e.g to the [Node 1](#complete-example-for-dtlscoap-server-node-1) above. - -> Note: Node 1 and Node 2 must use the same mode. Either PSK or Certificate based. - -``` - Node 2 ---------- -|CoAPS | -|Client |--Connect to Server on Port 5684--> (Node 1) -| | ---------- -``` - -### with PSK +### X.509 Certificate ```bash -coaps set psk secretPSK Client_identity -coaps start -coaps connect 2001:620:190:ffa1::321 -coaps get test -coaps disconnect +> openssl req -x509 -new -key ec_private.pem -out x509_cert.pem -days 30 ``` -### with Certificate +## Command List + +* [help](#help) +* [connect](#connect-address) +* [delete](#delete-uri-path-type-payload) +* [disconnect](#disconnect) +* [get](#get-uri-path-type) +* [post](#post-uri-path-type-payload) +* [psk](#psk-psk-pskid) +* [put](#put-uri-path-type-payload) +* [resource](#resource-uri-path) +* [start](#start) +* [stop](#stop) +* [x509](#x509) + +## Command Details + +### help ```bash -coaps set x509 -coaps start (false) -coaps connect -coaps get test -coaps disconnect +> coaps help +help +connect +delete +disconnect +get +post +psk +put +resource +start +stop +x509 +Done ``` -* param false: optional, disables peer certificate validation. +List the CoAPS CLI commands. -## Create own Private Key with a .X509 Certificate +### connect \ -### Create EC Private Key +Establish DTLS session. + +* address: IPv6 address of the peer. ```bash -openssl ecparam -genkey -out myECKey.pem -name prime256v1 -noout +> coaps connect fdde:ad00:beef:0:9903:14b:27e0:5744 +Done +coaps connected ``` -* ecparam: Key for Elliptic Curve Algorithms -* -name: The elliptic curve to chose. a list of available curves `openssl ecparam -list_curves` -* -noout: private key without EC Parameters +### delete \ \[type\] \[payload\] -### Create .X509 Certificate +* uri-path: URI path of the resource. +* type: "con" for Confirmable or "non-con" for Non-confirmable (default). +* payload: CoAPS request payload. ```bash -openssl req -x509 -new -key myECKey.pem -out myX509Cert.pem -days 30 +> coaps delete test-resource con payload +Done ``` -* -days: validity time of certificate +### disconnect + +```bash +> coaps disconnect +coaps disconnected +Done +``` + +### get \ \[type\] + +* uri-path: URI path of the resource. +* type: "con" for Confirmable or "non-con" for Non-confirmable (default). + +```bash +> coaps get test-resource +Done +``` + +### post \ \[type\] \[payload\] + +* uri-path: URI path of the resource. +* type: "con" for Confirmable or "non-con" for Non-confirmable (default). +* payload: CoAPS request payload. + +```bash +> coaps post test-resource con payload +Done +``` + +### psk \ \ + +Set DTLS ciphersuite to `TLS_PSK_WITH_AES_128_CCM_8`. + +* psk: pre-shared key +* pskid: pre-shared key identifier + +```bash +> coaps psk 123 pskid +Done +``` + +### put \ \[type\] \[payload\] + +* uri-path: URI path of the resource. +* type: "con" for Confirmable or "non-con" for Non-confirmable (default). +* payload: CoAPS request payload. + +```bash +> coaps put test-resource con payload +Done +``` + +### resource \[uri-path\] + +Sets the URI path for the test resource. + +```bash +> coaps resource test-resource +Done +> coaps resource +test-resource +Done +``` + +### start + +Starts the application coaps service. + +* checkPeerCert: Peer Certificate Check can be disabled by typing false. + +```bash +> coaps start +Done +``` + +### stop + +Stops the application coaps service. + +```bash +> coaps stop +Done +``` + +### x509 + +Set DTLS ciphersuite to `TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8`. + +The X.509 certificate stored in [`src/cli/x509_cert_key.hpp`](x509_cert_key.hpp). + +```bash +> coaps x509 +Done +```