2cda31486f4d376b9b89f9e7b2eec9eb895cc2a6
[iotivity.git] / examples / OCFSecure / README.md
1 # Introduction
2 This is a sample secure application using the "justworks" security model
3 There are 2 applications; server and client, which need to be running from 2
4 different terminals regardless whether those 2 terminals are running within
5 the same machine or not as long as they can discover each other.
6 These 2 applications are verified on
7 * a regular Ubuntu machine
8 * Ubuntu running on Intel Joule
9 * Raspbian running on Raspberry Pi 3 and Raspberry Pi Zero W
10
11 These applications can be used to verify the build environment is setup
12 properly. They can serve as a baseline and a reference for new developers to
13 learn how to write simple server and client applications and implement OCF
14 security and pass the OCF certification test tool.
15
16 # Building the applications
17
18 To build the applications, type the following scons command from the root
19 directory of IoTivity
20
21 ```
22 $ scons examples/OCFSecure TARGET_TRANSPORT=IP
23 ```
24
25 To speed up the build procerss and utilize more than a single core, you can
26 add the -j option followed by the number of cores to utilize for building
27 the applications
28
29 To build the applications in the debug mode, you can add the following option
30 to the scons command RELEASE=0
31
32 # Running the applications
33
34 To run the applications on a regular machine with Ubuntu, change the directory
35 to out/linux/x86_64/release/examples/OCFSecure with the following command
36 ```
37 $ cd out/linux/x86_64/release/examples/OCFSecure/
38 ```
39 Next, run the server application with the following command
40 ```
41 $ ./server
42 ```
43 open up another terminal window within the same directory
44 (shortcut:Ctrl+Shift+n) and run the client application with the following
45 command.
46 ```
47 $ ./client
48 ```
49 Since there is no physical led attached to a regular machine with Ubuntu, the
50 led resource will be simulated. Otherwise, if you are running these
51 applications on a Raspberry Pi or Intel Joule board then you would need to
52 run the server application with the sudo command so the server application
53 can have access to the hardware of the board.
54
55 If successful, you should be able to see the list of discovered resources
56 in the client terminal as shown below.
57 ```
58 Discovered Resources:
59     #0: /oic/res    @224.0.1.187:5683    resource type: nil
60     #1: /oic/sec/doxm    @fe80::3749:e171:d50f:966d%enp0s3:42825    resource type
61     #2: /oic/sec/pstat    @fe80::3749:e171:d50f:966d%enp0s3:0    resource type
62     #3: /oic/sec/acl2    @10.0.2.15:47132    resource type: oic.r.acl2
63     #4: /oic/sec/cred    @10.0.2.15:47132    resource type: oic.r.cred
64     #5: /oic/sec/crl    @10.0.2.15:47132    resource type: oic.r.crl
65     #6: /oic/sec/csr    @10.0.2.15:47132    resource type: oic.r.csr
66     #7: /oic/sec/roles    @10.0.2.15:47132    resource type: oic.r.roles
67     #8: /oic/d    @10.0.2.15:47132    resource type: oic.wk.d
68     #9: /oic/p    @10.0.2.15:0    resource type: oic.wk.p
69     #10: /introspection    @10.0.2.15:0    resource type: oic.wk.introspection
70
71 Request Methods:    1: GET    4: POST
72 Usage:\<resource number> \<request method> :
73 ```
74 Usually, you might need to press enter a couple of times to refresh the stdout
75 to finally see the complete list like so.
76 ```
77 Discovered Resources:
78     #0: /oic/res    @224.0.1.187:5683    resource type: nil
79     #1: /oic/sec/doxm    @fe80::3749:e171:d50f:966d%enp0s3:42825    resource type
80     #2: /oic/sec/pstat    @fe80::3749:e171:d50f:966d%enp0s3:0    resource type
81     #3: /oic/sec/acl2    @10.0.2.15:47132    resource type: oic.r.acl2
82     #4: /oic/sec/cred    @10.0.2.15:47132    resource type: oic.r.cred
83     #5: /oic/sec/crl    @10.0.2.15:47132    resource type: oic.r.crl
84     #6: /oic/sec/csr    @10.0.2.15:47132    resource type: oic.r.csr
85     #7: /oic/sec/roles    @10.0.2.15:47132    resource type: oic.r.roles
86     #8: /oic/d    @10.0.2.15:47132    resource type: oic.wk.d
87     #9: /oic/p    @10.0.2.15:0    resource type: oic.wk.p
88     #10: /introspection    @10.0.2.15:0    resource type: oic.wk.introspection
89     #11: /oic/sec/doxm    @fe80::5c79:f160:691d:40bd%enp0s8:42825    resource type
90     #12: /oic/sec/pstat    @fe80::5c79:f160:691d:40bd%enp0s8:0    resource type
91     #13: /oic/sec/acl2    @192.168.56.101:47132    resource type: oic.r.acl2
92     #14: /oic/sec/cred    @192.168.56.101:47132    resource type: oic.r.cred
93     #15: /oic/sec/crl    @192.168.56.101:47132    resource type: oic.r.crl
94     #16: /oic/sec/csr    @192.168.56.101:47132    resource type: oic.r.csr
95     #17: /oic/sec/roles    @192.168.56.101:47132    resource type: oic.r.roles
96     #18: /oic/d    @192.168.56.101:47132    resource type: oic.wk.d
97     #19: /oic/p    @192.168.56.101:0    resource type: oic.wk.p
98     #20: /introspection    @192.168.56.101:0    resource type: oic.wk.introspection
99     #21: /oic/sec/doxm    @fe80::3749:e171:d50f:966d%enp0s3:59488    resource type
100     #22: /oic/sec/pstat    @fe80::3749:e171:d50f:966d%enp0s3:0    resource type
101     #23: /oic/sec/acl2    @10.0.2.15:50400    resource type: oic.r.acl2
102     #24: /oic/sec/cred    @10.0.2.15:50400    resource type: oic.r.cred
103     #25: /oic/sec/crl    @10.0.2.15:50400    resource type: oic.r.crl
104     #26: /oic/sec/csr    @10.0.2.15:50400    resource type: oic.r.csr
105     #27: /oic/sec/roles    @10.0.2.15:50400    resource type: oic.r.roles
106     #28: /oic/d    @10.0.2.15:50400    resource type: oic.wk.d
107     #29: /oic/p    @10.0.2.15:0    resource type: oic.wk.p
108     #30: /introspection    @10.0.2.15:0    resource type: oic.wk.introspection
109     #31: /switch    @10.0.2.15:50400    resource type: oic.r.switch.binary
110     #32: /oic/sec/doxm    @fe80::5c79:f160:691d:40bd%enp0s8:59488    resource type
111     #33: /oic/sec/pstat    @fe80::5c79:f160:691d:40bd%enp0s8:0    resource type
112     #34: /oic/sec/acl2    @192.168.56.101:50400    resource type: oic.r.acl2
113     #35: /oic/sec/cred    @192.168.56.101:50400    resource type: oic.r.cred
114     #36: /oic/sec/crl    @192.168.56.101:50400    resource type: oic.r.crl
115     #37: /oic/sec/csr    @192.168.56.101:50400    resource type: oic.r.csr
116     #38: /oic/sec/roles    @192.168.56.101:50400    resource type: oic.r.roles
117     #39: /oic/d    @192.168.56.101:50400    resource type: oic.wk.d
118     #40: /oic/p    @192.168.56.101:0    resource type: oic.wk.p
119     #41: /introspection    @192.168.56.101:0    resource type: oic.wk.introspection
120     #42: /switch    @192.168.56.101:50400    resource type: oic.r.switch.binary
121
122 Request Methods:    1: GET    4: POST
123 Usage:\<resource number> \<request method> :
124 ```
125 Notice the "/switch" uri on resources #31 and #42. This is a known issue will
126 be fixed at the soonest chance. be aware, the "/switch" uri might occure more
127 than twice and not all of them are going to work. However, one of them will
128 work.
129
130 As instructed in the client application. you can enter the number of the
131 discovered resource you want to interact with (which is either 31 or 42 in this
132 case) followed by 1 for issuing a GET request or 4 for a POST request.
133 If you decided to issue a GET request, you should see the following GET
134 response if everything went OK.
135
136 ```
137 =========================================================
138 Result: (0) - OC_STACK_OK
139 07:12.062 INFO: PayloadLog: Payload Type: Representation
140 07:12.062 INFO: PayloadLog:     Resource #1
141 07:12.062 INFO: PayloadLog:     Resource Types:
142 07:12.062 INFO: PayloadLog:         oic.r.switch.binary
143 07:12.062 INFO: PayloadLog:     Interfaces:
144 07:12.062 INFO: PayloadLog:         oic.if.baseline
145 07:12.062 INFO: PayloadLog:         oic.if.a
146 07:12.062 INFO: PayloadLog:     Values:
147 07:12.062 INFO: PayloadLog:         value(bool):false
148 ==========================================================
149 ```
150 If you decided to issue a POST request, you will be prompted to create a custom
151 payload to be attached to the POST request. As of right now, the only supported
152 feature is turning the led on and off. As a result, type 0 to select the
153 boolean data type then follow it with the name of the property (the key) which
154 is "value" (without quotes as it is writing in the GET response above)
155 and then follow that with (the value) either 1 to turn the led on
156 or 0 to turn the led off. Next press ENTER twice; once to end the first
157 key-value pair entry and once again for completing the custom payload creation.
158
159 Below is a copy of an example usage.
160 ```
161     #42: /switch    @192.168.56.101:50400    resource type: oic.r.switch.binary
162
163 Request Methods:    1: GET    4: POST
164 Usage:<resource number> <request method> :42 4
165
166 Need to create a custom POST payload
167 Enter key value pairs as:    <type(int)> <key> <value>
168 Type: 0:bool      1:int      2:double      3:string
169 press ENTER to finish :0 value 1
170 press ENTER to finish :
171 ```
172
173 If successful, you should see the following POST response
174 ```
175 ==========================================================
176 Result: (4) - OC_STACK_RESOURCE_CHANGED
177 08:24.366 INFO: PayloadLog: Payload Type: Representation
178 08:24.366 INFO: PayloadLog:     Resource #1
179 08:24.366 INFO: PayloadLog:     Resource Types:
180 08:24.366 INFO: PayloadLog:         oic.r.switch.binary
181 08:24.366 INFO: PayloadLog:     Interfaces:
182 08:24.366 INFO: PayloadLog:         oic.if.baseline
183 08:24.366 INFO: PayloadLog:         oic.if.a
184 08:24.366 INFO: PayloadLog:     Values:
185 08:24.366 INFO: PayloadLog:         value(bool):true
186 ==========================================================
187 ```
188 If for whatever reason you noticed the following response instead, then there
189 is a security issue. Hopefully, you will not see this!
190 ```
191 ==========================================================
192 Result: (46) - OC_STACK_UNAUTHORIZED_REQ
193 10:16.370 INFO: PayloadLog: NULL Payload
194 ==========================================================
195 ```
196 To run the applications on either the Intel Joule or the Raspberry Pi, the mraa
197 library must be installed! this is the library that is used to control the
198 physical hardware. Without it, you will still get the simulated led but it is
199 not as fun as the real led turning on and off in the physical world that you
200 can control with your own software! Install it, it is worth it ;)
201
202 Installing mraa on the intel joule. From the home directory, type commands
203 * $sudo add-apt-repository ppa:mraa/mraa
204 * $sudo apt-get update
205 * $sudo apt-get install libmraa1 libmraa-dev mraa-tools python-mraa python3-mraa
206
207 Installing mraa on the raspberry pi, from the parent directory of IoTivity's
208 root directory, type the following commands.
209 * $ git clone https://github.com/intel-iot-devkit/mraa.git
210 * $ cd mraa && mkdir build && cd build && cmake .. && make
211 * $ sudo make install
212
213 To run the applications on Intel Joule running ubuntu then the built-in
214 led on gpio 100 will be connected to the server and you would be able to
215 control it with the client application. It is important to remember to run the
216 server applications in sudo mode as hardware access is a super user privilege!
217 ```
218 $ sudo ./server
219 ```
220 Otherwise, you would get an error with unknown gpio or sometimes you will not
221 get any errors but the built-in led will not respond to your control. It is the
222 same usage as running the applications on a regular machine with Ubuntu which
223 should be described above.
224
225 To run the applications on Raspberry Pi with Raspian then make sure to connect
226 an LED on hardware pin 4 which is gpio 7! The pin mapping of raspberry pi is
227 just messed up like that! Google raspberry pi pinout
228 This pin has all the following names
229 * BCM pin 4
230 * Physical pin 7
231 * Wiring Pi pin 7
232
233 Anyways, have a jumper wire from GPIO 7 to the positive terminal of the led.
234 Then connect a resistor from the negative terminal of the led to ground.
235
236 Also, it is important to remember to run the server application in sudo mode as
237 hardware access is a super user privilege. Otherwise, you might get an error of
238 unknown gpio or the app might run but will not control the led and you might
239 think you connected the led on the wrong pin which may not be the case.
240
241 You can also connect the Enviro pHat sensor board if you have it. Its LED is
242 already connected to gpio 7.
243
244 # Testing the server app against CTT
245 You need to install the OCF Certification Test Tool 2.0 on a Windows machine
246 and start it and if the windows machine on the same network as the server and
247 the server app is running then the CTT should discover the server. If not,
248 please check the correct network interface from the options menu and then
249 press the Select IUT button or from the File menu. A pop-up window will
250 show the discovered devices and you should be able to see the server device
251 as 12345678-1234-1234-1234-123456789012 and in the details section, you
252 should be able to see the /switch uri. click on Next. Now, browse to select
253 the PICS file which should be included in this example named
254 PICS_server_OCF10_vprime.json then click on Next. From the Testing Profiles
255 uncheck everything and check OCF 1.0 Server. Next, click on
256 Run All Test Cases button. Most likely, you will get a prompt saying
257 "Please initiate device to revert to "ready for OTM" state" and there are
258 2 options to click on; OK and Cancel because this sample is shipped in the
259 "Ready for Normal Operation" state. In this case, kill the server with
260 Ctrl+C and from the output directory where the server is running, copy the
261 ocf_svr_db_server_RFOTM.dat from the project directory to the project output
262 directory and name it as ocf_svr_db_server.dat as shown in the following
263 command then re-run the server app then press OK on the prompt once the
264 server is running again.
265 ```
266 cp ~/iot/iotivity/examples/OCFSecure/ocf_svr_db_server_RFOTM.dat ocf_svr_db_server.dat
267 ```
268 You might get this prompt again since the CTT does not un-onboard the device
269 but now you know what to do!
270 Also, you will be prompt to power cycle the device. In this case, you can
271 either kill the server app and restart it again or literally power cycle
272 your device and re-run the server app once your device is back up and
273 connected to the same network.
274 Please note, you might see tests passing with warnings and CT1.7.8.11 test
275 Case failing but that is OK.
276
277 # Known issues
278
279 1. Sometimes, the applications will not run because of not finding some library.
280 In this case, you would need to export the LD_LIBRARY_PATH to the environment.
281     ```
282     export LD_LIBRARY_PATH=<output dir orwherever the library is>
283     ```
284     Also, since you would need to run the server application in sudo mode, you
285 would need to type this command
286     ```
287     $sudo ldconfig
288     ```
289 and you might also need to type
290     ```
291     $sudo env LD_LIBRARY_PATH=<output dir or wherever the library is>
292     ```
293 Hopefully, you will not run into any library issues but if you run into any
294 issue with this application, please send me an e-mail at ralshafi@vprime.com
295 and file a bug in JIRA and assign it to me (username: alshafi).
296
297 2. Multiple endpoints get discovered and they need to be filtered out
298 eventually. In the meantime, there will be multiple /switch links and only one
299 of them works and the user will need to issues GET requests to all of them
300 until the good one is found. The wrong /switch links will result in
301 Result: (255) - OC_STACK_ERROR.
302 The correct /a/led link will result in Result: (0) - OC_STACK_OK
303
304 # Example Directory
305
306 There are 16 files in the example directory.
307 * client.c
308     * This is the client program
309 * device_properties.dat
310     * This is a file storing the device properties in cbor format which is
311 generated automatically by the server application
312 * ocf_svr_db_client.dat
313     * This is the cbor format of the secure virtual resource database, defined
314 by the human-readable version ocf_svr_db_client.json file, and it is used by
315 the client application
316 * ocf_svr_db_client.json
317     * This is the human-readable version of ocf_svr_db_client.dat
318 * ocf_svr_db_server.dat
319     * This is the cbor format of the secure virtual resource database and it is
320 an exact copy from the ocf_svr_db_server_RFNOP.dat which is the cbor version of
321 the human-readable version ocf_svr_db_server_RFNOP.json file. This is the case
322 because the client application does not support the onboarding and provisioning
323 process currently and we need to set the state in the "Ready For Normal
324 Operation" manually.
325 We also need to set the state in the "Ready For Ownership Method Transfer"
326 when testing the application with the OCF Certification Test Tool (CTT).
327 In this case, you would need to copy ocf_svr_db_server_RFOTM.dat into
328 ocf_svr_db_server.dat since that is the file that will be read by the server.
329 * ocf_svr_db_server_RFNOP.dat
330     * This is the cbor format of the secure virtual resource database, defined
331 by the human-readable version ocf_svr_db_server_RFNOP.json file and it is *NOT*
332 used by the server application. Rename it without the _RFNOP suffix to be read
333 by the server
334 * ocf_svr_db_server_RFNOP.json
335     * This is the human-readable version of ocf_svr_db_server_RFNOP.dat
336 * ocf_svr_db_server_RFOTM.dat
337     * This is the cbor format of the secure virtual resource database, defined
338 by the human-readable version ocf_svr_db_server_RFOTM.json file and it is *NOT*
339 used by the server application. Rename it without the _RFOTM suffix to be read
340 by the server
341 * ocf_svr_db_server_RFOTM.json
342     * This is the human-readable version of ocf_svr_db_server_RFOTM.dat
343 * PICS_server_OCF10_vprime.json
344     * This is the file that was used as the input to the OCF Certification
345 Test Tool.
346 * README.md
347     * This is this file :)
348 * SConscript
349     * This is the script that is being used by the scons tool to know how
350 to build the sample applications and what needs to be copied to the output
351 directory.
352 * server.cpp
353     * This is the server program.
354 * switch_introspection.dat
355     * This is the cbor format of the introspection file (also known as
356 Introspection Device Data IDD) the server needs to read to implement
357 the introspection feature.
358 * switch_introspection.json
359     * This is the human-readable version of switch_introspection.dat file
360 which is also know as the "swagger" file.
361 * utilities.c
362     * this is a supplementary program containing custom utility c functions
363 that help with reporting log messages mainly as of current.