1# OpenThread CLI - CoAPS Example 2 3The OpenThread CoAPS APIs may be invoked via the OpenThread CLI. 4 5## Quick Start 6 7### Form Network 8 9Form a network with at least two devices. 10 11### Configure DTLS ciphersuite. 12 13CoAPS uses DTLS to establish a secure, end-to-end connection. 14 15This example supports two ciphersuites: 16 17- TLS_PSK_WITH_AES_128_CCM_8 18 19 ```bash 20 > coaps psk <your-psk> <your-psk-id> 21 Done 22 ``` 23 24- TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8 25 ```bash 26 > coaps x509 27 Done 28 ``` 29 The X.509 certificate stored in `core/cli/x509_cert_key.hpp`. 30 31### Node 1 32 33On node 1, setup CoAPS server with resource `test-resource`. 34 35```bash 36> coaps start 37Done 38> coaps resource test-resource 39Done 40``` 41 42### Node 2 43 44```bash 45> coaps start 46Done 47> coaps connect <peer-ip6-address> 48Done 49coaps connected 50> coaps get test-resource 51Done 52coaps response from fdde:ad00:beef:0:9903:14b:27e0:5744 with payload: 68656c6c6f576f726c6400 53> coaps put test-resource con payload 54Done 55coaps response from fdde:ad00:beef:0:9903:14b:27e0:5744 56``` 57 58### Result 59 60On node 1, you should see output similar to below: 61 62```bash 63coaps request from fdde:ad00:beef:0:9e68:576f:714c:f395 GET 64coaps response sent 65coaps request from fdde:ad00:beef:0:9e68:576f:714c:f395 PUT with payload: 7061796c6f6164 66coaps response sent 67``` 68 69## Generate Elliptic Curve Private Key and X.509 Certificate 70 71### EC Private Key 72 73```bash 74> openssl ecparam -genkey -name prime256v1 -noout -out ec_private.pem 75``` 76 77### X.509 Certificate 78 79```bash 80> openssl req -x509 -new -key ec_private.pem -out x509_cert.pem -days 30 81``` 82 83## Command List 84 85- [help](#help) 86- [connect](#connect-address) 87- [delete](#delete-uri-path-type-payload) 88- [disconnect](#disconnect) 89- [get](#get-uri-path-type) 90- [isclosed](#isclosed) 91- [isconnactive](#isconnactive) 92- [isconnected](#isconnected) 93- [post](#post-uri-path-type-payload) 94- [psk](#psk-psk-pskid) 95- [put](#put-uri-path-type-payload) 96- [resource](#resource-uri-path) 97- [set](#set-new-content) 98- [start](#start) 99- [stop](#stop) 100- [x509](#x509) 101 102## Command Details 103 104### help 105 106```bash 107> coaps help 108connect 109delete 110disconnect 111get 112isclosed 113isconnactive 114isconnected 115post 116psk 117put 118resource 119set 120start 121stop 122x509 123Done 124``` 125 126List the CoAPS CLI commands. 127 128### connect \<address\> 129 130Establish DTLS session. 131 132- address: IPv6 address of the peer. 133 134```bash 135> coaps connect fdde:ad00:beef:0:9903:14b:27e0:5744 136Done 137coaps connected 138``` 139 140### delete \<uri-path\> \[type\] \[payload\] 141 142- uri-path: URI path of the resource. 143- type: "con" for Confirmable or "non-con" for Non-confirmable (default). 144- payload: CoAPS request payload. 145 146```bash 147> coaps delete test-resource con payload 148Done 149``` 150 151### disconnect 152 153```bash 154> coaps disconnect 155coaps disconnected 156Done 157``` 158 159### get \<uri-path\> \[type\] 160 161- uri-path: URI path of the resource. 162- type: "con" for Confirmable or "non-con" for Non-confirmable (default). Use "block-<block-size>" if the response should be transferred block-wise. ("block-16","block-32","block-64","block-128","block-256","block-512","block-1024") 163 164```bash 165> coaps get test-resource 166Done 167``` 168 169```bash 170> coaps get test-resource block-1024 171Done 172``` 173 174### post \<uri-path\> \[type\] \[payload\] 175 176- uri-path: URI path of the resource. 177- type: "con" for Confirmable or "non-con" for Non-confirmable (default). Use "block-<block-size>" to send blocks with random payload. ("block-16","block-32","block-64","block-128","block-256","block-512","block-1024") 178- payload: CoAP request payload. If \[type\] is "block-<block-size>", the amount of blocks to be sent can be set here. 179 180```bash 181> coaps post test-resource con payload 182Done 183``` 184 185```bash 186> coaps post test-resource block-1024 10 187Done 188``` 189 190### psk \<psk\> \<pskid\> 191 192Set DTLS ciphersuite to `TLS_PSK_WITH_AES_128_CCM_8`. 193 194- psk: pre-shared key 195- pskid: pre-shared key identifier 196 197```bash 198> coaps psk 123 pskid 199Done 200``` 201 202### put \<uri-path\> \[type\] \[payload\] 203 204- uri-path: URI path of the resource. 205- type: "con" for Confirmable or "non-con" for Non-confirmable (default). Use "block-<block-size>" to send blocks with random payload. ("block-16","block-32","block-64","block-128","block-256","block-512","block-1024") 206- payload: CoAP request payload. If \[type\] is "block-<block-size>", the amount of blocks to be sent can be set here. 207 208```bash 209> coaps put test-resource con payload 210Done 211``` 212 213```bash 214> coaps put test-resource block-1024 10 215Done 216``` 217 218### resource \[uri-path\] 219 220Sets the URI path for the test resource. 221 222```bash 223> coaps resource test-resource 224Done 225> coaps resource 226test-resource 227Done 228``` 229 230### set \[new-content\] 231 232Sets the content sent by the test resource. 233 234```bash 235> coaps set Testing123 236Done 237``` 238 239### start \[check-peer-cert\|max-conn-attempts\] 240 241Starts the application coaps service. 242 243The `check-peer-cert` parameter determines if the peer-certificate check is enabled (default) or disabled. The `max-conn-attempts` parameter sets the maximum number of allowed attempts, successful or failed, to connect to the CoAP Secure server. The default value of this parameter is 0, which means that there is no limit to the number of attempts. The `check-peer-cert` and `max-conn-attempts` parameters work together in the following combinations, even though you can only specify one argument: 244 245- No argument specified: Defaults are used. 246- Setting `check-peer-cert` to `true`: Has the same effect as as omitting the argument, which is that the `check-peer-cert` value is `true`, and the `max-conn-attempts` value is 0. 247- Setting `check-peer-cert` to `false`: `check-peer-cert` value is `false`, and the `max-conn-attempts` value is `0`. 248- Specifying a number: `check-peer-cert` is `true`, and the `max-conn-attempts` value is the number specified in the argument. 249 250```bash 251> coaps start 252Done 253``` 254 255### stop 256 257Stops the application coaps service. 258 259```bash 260> coaps stop 261Done 262``` 263 264### isconnected 265 266Indicates whether or not the CoAP secure service is connected. 267 268```bash 269> coaps isconnected 270yes 271Done 272``` 273 274### isconnactive 275 276Indicates whether or not the CoAP secure service connection is active (already connected or establishing a connection). 277 278```bash 279> coaps isconnactive 280yes 281Done 282``` 283 284### isclosed 285 286Indicates whether or not the CoAP secure service is closed. 287 288```bash 289> coaps isclosed 290no 291Done 292``` 293 294### x509 295 296Set DTLS ciphersuite to `TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8`. 297 298The X.509 certificate stored in [`src/cli/x509_cert_key.hpp`](x509_cert_key.hpp). 299 300```bash 301> coaps x509 302Done 303``` 304
