Security code comments which are doxygen compliant
[platform/upstream/iotivity.git] / resource / csdk / security / include / securevirtualresourcetypes.h
1 //******************************************************************
2 //
3 // Copyright 2015 Intel Mobile Communications GmbH All Rights Reserved.
4 //
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
6 //
7 // Licensed under the Apache License, Version 2.0 (the "License");
8 // you may not use this file except in compliance with the License.
9 // You may obtain a copy of the License at
10 //
11 //      http://www.apache.org/licenses/LICENSE-2.0
12 //
13 // Unless required by applicable law or agreed to in writing, software
14 // distributed under the License is distributed on an "AS IS" BASIS,
15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 // See the License for the specific language governing permissions and
17 // limitations under the License.
18 //
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
20
21 /**
22  * Data type definitions for all oic.sec.* types defined in the
23  * OIC Security Specification.
24  *
25  * Note that throughout, ptrs are used rather than arrays.  There
26  * are two primary reasons for this:
27  * 1) The Spec defines many structures with optional fields, so pre-
28  *    allocating these would be wasteful.
29  * 2) There are in many cases arrays of Strings or arrays of Structs,
30  *    which could not be defined as variable length arrays (e.g. array[])
31  *    without breaking from the structure order and definition in the Spec.
32  *
33  * The primary drawback to this decision is that marshalling functions
34  * will have to be written by hand to marshal these structures (e.g. to/from
35  * Persistent Storage, or across memory boundaries).
36  *
37  * TODO reconcile against latest OIC Security Spec to ensure all fields correct.
38  * (Last checked against v0.95)
39  */
40
41 #ifndef OC_SECURITY_RESOURCE_TYPES_H
42 #define OC_SECURITY_RESOURCE_TYPES_H
43
44 #include <stdint.h> // for uint8_t typedef
45 #include <stdbool.h>
46 #ifdef __WITH_X509__
47 #include "byte_array.h"
48 #endif /* __WITH_X509__ */
49
50 #ifdef __cplusplus
51 extern "C" {
52 #endif
53
54 /**
55  * Values used to create bit-maskable enums for single-value response with
56  * embedded code.
57  */
58 #define ACCESS_GRANTED_DEF            (1 << 0)
59 #define ACCESS_DENIED_DEF             (1 << 1)
60 #define INSUFFICIENT_PERMISSION_DEF   (1 << 2)
61 #define SUBJECT_NOT_FOUND_DEF         (1 << 3)
62 #define RESOURCE_NOT_FOUND_DEF        (1 << 4)
63 #define POLICY_ENGINE_ERROR_DEF       (1 << 5)
64 #define INVALID_PERIOD_DEF            (1 << 6)
65 #define ACCESS_WAITING_DEF            (1 << 7)
66 #define AMS_SERVICE_DEF               (1 << 8)
67 #define REASON_MASK_DEF               (INSUFFICIENT_PERMISSION_DEF | \
68                                        INVALID_PERIOD_DEF | \
69                                        SUBJECT_NOT_FOUND_DEF | \
70                                        RESOURCE_NOT_FOUND_DEF | \
71                                        POLICY_ENGINE_ERROR_DEF)
72
73
74 /**
75  * Access policy in least significant bits (from Spec):
76  * 1st lsb:  C (Create)
77  * 2nd lsb:  R (Read, Observe, Discover)
78  * 3rd lsb:  U (Write, Update)
79  * 4th lsb:  D (Delete)
80  * 5th lsb:  N (Notify)
81  */
82 #define PERMISSION_CREATE       (1 << 0)
83 #define PERMISSION_READ         (1 << 1)
84 #define PERMISSION_WRITE        (1 << 2)
85 #define PERMISSION_DELETE       (1 << 3)
86 #define PERMISSION_NOTIFY       (1 << 4)
87 #define PERMISSION_FULL_CONTROL (PERMISSION_CREATE | \
88                                  PERMISSION_READ | \
89                                  PERMISSION_WRITE | \
90                                  PERMISSION_DELETE | \
91                                  PERMISSION_NOTIFY)
92
93 /**
94  * @brief   Response type for all Action requests from CA layer;
95  *          may include a reason code.
96  *
97  * To extract codes use GetReasonCode function on SRMAccessResponse:
98  *
99  * SRMAccessResponse_t response = SRMRequestHandler(obj, info);
100  * if(SRM_TRUE == IsAccessGranted(response)) {
101  *     SRMAccessResponseReasonCode_t reason = GetReasonCode(response);
102  *     switch(reason) {
103  *         case INSUFFICIENT_PERMISSION:
104  *         ...etc.
105  *     }
106  * }
107  */
108 typedef enum
109 {
110     ACCESS_GRANTED = ACCESS_GRANTED_DEF,
111     ACCESS_DENIED = ACCESS_DENIED_DEF,
112     ACCESS_DENIED_INVALID_PERIOD = ACCESS_DENIED_DEF
113         | INVALID_PERIOD_DEF,
114     ACCESS_DENIED_INSUFFICIENT_PERMISSION = ACCESS_DENIED_DEF
115         | INSUFFICIENT_PERMISSION_DEF,
116     ACCESS_DENIED_SUBJECT_NOT_FOUND = ACCESS_DENIED_DEF
117         | SUBJECT_NOT_FOUND_DEF,
118     ACCESS_DENIED_RESOURCE_NOT_FOUND = ACCESS_DENIED_DEF
119         | RESOURCE_NOT_FOUND_DEF,
120     ACCESS_DENIED_POLICY_ENGINE_ERROR = ACCESS_DENIED_DEF
121         | POLICY_ENGINE_ERROR_DEF,
122     ACCESS_WAITING_FOR_AMS = ACCESS_WAITING_DEF
123         | AMS_SERVICE_DEF,
124     ACCESS_DENIED_AMS_SERVICE_ERROR = ACCESS_DENIED
125         | AMS_SERVICE_DEF
126 } SRMAccessResponse_t;
127
128 /**
129  * Reason code for SRMAccessResponse.
130  */
131 typedef enum
132 {
133     NO_REASON_GIVEN = 0,
134     INSUFFICIENT_PERMISSION = INSUFFICIENT_PERMISSION_DEF,
135     SUBJECT_NOT_FOUND = SUBJECT_NOT_FOUND_DEF,
136     RESOURCE_NOT_FOUND = RESOURCE_NOT_FOUND_DEF,
137 } SRMAccessResponseReasonCode_t;
138
139 /**
140  * Extract Reason Code from Access Response.
141  */
142 static inline SRMAccessResponseReasonCode_t GetReasonCode(
143     SRMAccessResponse_t response)
144 {
145     SRMAccessResponseReasonCode_t reason =
146         (SRMAccessResponseReasonCode_t)(response & REASON_MASK_DEF);
147     return reason;
148 }
149
150 /**
151  * Returns 'true' iff request should be passed on to RI layer.
152  */
153 static inline bool IsAccessGranted(SRMAccessResponse_t response)
154 {
155     if(ACCESS_GRANTED == (response & ACCESS_GRANTED))
156     {
157         return true;
158     }
159     else
160     {
161         return false;
162     }
163 }
164
165 typedef struct OicSecAcl OicSecAcl_t;
166
167 typedef struct OicSecAmacl OicSecAmacl_t;
168
169 typedef struct OicSecCred OicSecCred_t;
170
171 /**
172  * Aid for assigning/testing vals with OicSecCredType_t.
173  * Example:
174  *  OicSecCredType_t ct = PIN_PASSWORD | ASYMMETRIC_KEY;
175  *  if((ct & PIN_PASSWORD) == PIN_PASSWORD)
176  *  {
177  *      // ct contains PIN_PASSWORD flag.
178  *  }
179  */
180 typedef enum OSCTBitmask
181 {
182     NO_SECURITY_MODE                = 0x0,
183     SYMMETRIC_PAIR_WISE_KEY         = (0x1 << 0),
184     SYMMETRIC_GROUP_KEY             = (0x1 << 1),
185     ASYMMETRIC_KEY                  = (0x1 << 2),
186     SIGNED_ASYMMETRIC_KEY           = (0x1 << 3),
187     PIN_PASSWORD                    = (0x1 << 4),
188     ASYMMETRIC_ENCRYPTION_KEY       = (0x1 << 5),
189 } OSCTBitmask_t;
190
191 /**
192  * /oic/sec/credtype (Credential Type) data type.
193  * Derived from OIC Security Spec /oic/sec/cred; see Spec for details.
194  *              0:  no security mode
195  *              1:  symmetric pair-wise key
196  *              2:  symmetric group key
197  *              4:  asymmetric key
198  *              8:  signed asymmetric key (aka certificate)
199  *              16: PIN /password
200  */
201 typedef OSCTBitmask_t OicSecCredType_t;
202
203 typedef struct OicSecDoxm OicSecDoxm_t;
204
205 typedef enum OicSecDpm
206 {
207     NORMAL                          = 0x0,
208     RESET                           = (0x1 << 0),
209     TAKE_OWNER                      = (0x1 << 1),
210     BOOTSTRAP_SERVICE               = (0x1 << 2),
211     SECURITY_MANAGEMENT_SERVICES    = (0x1 << 3),
212     PROVISION_CREDENTIALS           = (0x1 << 4),
213     PROVISION_ACLS                  = (0x1 << 5),
214     // << 6 THROUGH 15 RESERVED
215 } OicSecDpm_t;
216
217 typedef enum OicSecDpom
218 {
219     MULTIPLE_SERVICE_SERVER_DRIVEN  = 0x0,
220     SINGLE_SERVICE_SERVER_DRIVEN    = 0x1,
221     MULTIPLE_SERVICE_CLIENT_DRIVEN  = 0x2,
222     SINGLE_SERVICE_CLIENT_DRIVEN    = 0x3,
223 } OicSecDpom_t;
224
225 typedef enum OicSecSvcType
226 {
227     SERVICE_UNKNOWN                 = 0x0,
228     ACCESS_MGMT_SERVICE             = 0x1,  //urn:oic.sec.ams
229 } OicSecSvcType_t;
230
231
232 //TODO: Need more clarification on deviceIDFormat field type.
233 #if 0
234 typedef enum
235 {
236     URN = 0x0
237 }OicSecDvcIdFrmt_t;
238 #endif
239
240 typedef enum
241 {
242     OIC_JUST_WORKS                          = 0x0,
243     OIC_RANDOM_DEVICE_PIN                   = 0x1,
244     OIC_MANUFACTURER_CERTIFICATE           = 0x2,
245     OIC_OXM_COUNT
246 }OicSecOxm_t;
247
248 typedef struct OicSecJwk OicSecJwk_t;
249
250 typedef struct OicSecPstat OicSecPstat_t;
251
252 typedef struct OicSecRole OicSecRole_t;
253
254 typedef struct OicSecSacl OicSecSacl_t;
255
256 typedef struct OicSecSvc OicSecSvc_t;
257
258 typedef char *OicUrn_t; //TODO is URN type defined elsewhere?
259
260 typedef struct OicUuid OicUuid_t; //TODO is UUID type defined elsewhere?
261
262
263 #ifdef __WITH_X509__
264 typedef struct OicSecCrl OicSecCrl_t;
265 #endif /* __WITH_X509__ */
266
267 /**
268  * /oic/uuid (Universal Unique Identifier) data type.
269  */
270 #define UUID_LENGTH 128/8 // 128-bit GUID length
271 //TODO: Confirm the length and type of ROLEID.
272 #define ROLEID_LENGTH 128/8 // 128-bit ROLEID length
273 #define OWNER_PSK_LENGTH_128 128/8 //byte size of 128-bit key size
274 #define OWNER_PSK_LENGTH_256 256/8 //byte size of 256-bit key size
275
276 struct OicUuid
277 {
278     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
279     //TODO fill in unless this is defined elsewhere?
280     uint8_t             id[UUID_LENGTH];
281 };
282
283 /**
284  * /oic/sec/jwk (JSON Web Key) data type.
285  * See JSON Web Key (JWK)  draft-ietf-jose-json-web-key-41
286  */
287 #define JWK_LENGTH 256/8 // 256 bit key length
288 struct OicSecJwk
289 {
290     uint8_t                *data;
291     size_t                  len;
292 };
293
294 /**
295  * /oic/sec/acl (Access Control List) data type.
296  * Derived from OIC Security Spec; see Spec for details.
297  */
298 struct OicSecAcl
299 {
300     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
301     OicUuid_t           subject;        // 0:R:S:Y:uuid TODO: this deviates
302                                         // from spec and needs to be updated
303                                         // in spec (where it's a String).
304     size_t              resourcesLen;   // the number of elts in Resources
305     char                **resources;    // 1:R:M:Y:String
306     uint16_t            permission;     // 2:R:S:Y:UINT16
307     size_t              prdRecrLen;     // the number of elts in Periods
308     char                **periods;       // 3:R:M*:N:String (<--M*; see Spec)
309     char                **recurrences;   // 5:R:M:N:String
310     size_t              ownersLen;      // the number of elts in Owners
311     OicUuid_t           *owners;        // 8:R:M:Y:oic.uuid
312     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
313     // SRM version only; this will change to Svc type for full implementation.
314     //TODO change Owners type to oic.sec.svc
315     //OicSecSvc_t         *Owners;        // 6:R:M:Y:oic.sec.svc
316     OicSecAcl_t         *next;
317 };
318
319 /**
320  * /oic/sec/amacl (Access Manager Service Accesss Control List) data type.
321  * Derived from OIC Security Spec; see Spec for details.
322  */
323 struct OicSecAmacl
324 {
325     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
326     size_t              resourcesLen;   // the number of elts in Resources
327     char                **resources;    // 0:R:M:Y:String
328     size_t              amssLen;        // the number of elts in Amss
329     OicUuid_t           *amss;          // 1:R:M:Y:acl
330     size_t              ownersLen;      // the number of elts in Owners
331     OicUuid_t           *owners;        // 2:R:M:Y:oic.uuid
332     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
333     // SRM version only; this will change to Svc type for full implementation.
334     //TODO change Owners type to oic.sec.svc
335     //OicSecSvc_t         *Owners;        // 2:R:M:Y:oic.sec.svc
336     OicSecAmacl_t         *next;
337 };
338
339 /**
340  * /oic/sec/cred (Credential) data type.
341  * Derived from OIC Security Spec; see Spec for details.
342  */
343 struct OicSecCred
344 {
345     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
346     uint16_t            credId;         // 0:R:S:Y:UINT16
347     OicUuid_t           subject;        // 1:R:S:Y:oic.uuid
348     //Note: Need further clarification on roleID data type
349     //NOTE: Need further clarification on roleId datatype.
350     //size_t              roleIdsLen;     // the number of elts in RoleIds
351     //OicSecRole_t        *roleIds;       // 2:R:M:N:oic.sec.role
352     OicSecCredType_t    credType;       // 3:R:S:Y:oic.sec.credtype
353     OicSecJwk_t         publicData;     // 5:R:S:N:oic.sec.jwk
354     OicSecJwk_t         privateData;    // 6:R:S:N:oic.sec.jwk
355     char                *period;        // 7:R:S:N:String
356     size_t              ownersLen;      // the number of elts in Owners
357     OicUuid_t           *owners;        // 8:R:M:Y:oic.uuid
358     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
359     // SRM version only; this will change to Svc type for full implementation.
360     //OicSecSvc_t         *Owners;        // 8:R:M:Y:oic.sec.svc
361     //TODO change Owners type to oic.sec.svc
362     OicSecCred_t        *next;
363 };
364
365 /**
366  * /oic/sec/doxm (Device Owner Transfer Methods) data type
367  * Derived from OIC Security Spec; see Spec for details.
368  */
369 struct OicSecDoxm
370 {
371     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
372     OicUrn_t            *oxmType;       // 0:R:M:N:URN
373     size_t              oxmTypeLen;     // the number of elts in OxmType
374     OicSecOxm_t         *oxm;           // 1:R:M:N:UINT16
375     size_t              oxmLen;         // the number of elts in Oxm
376     OicSecOxm_t         oxmSel;         // 2:R/W:S:Y:UINT16
377     OicSecCredType_t    sct;            // 3:R:S:Y:oic.sec.credtype
378     bool                owned;          // 4:R:S:Y:Boolean
379     //TODO: Need more clarification on deviceIDFormat field type.
380     //OicSecDvcIdFrmt_t   deviceIDFormat; // 5:R:S:Y:UINT8
381     OicUuid_t           deviceID;       // 6:R:S:Y:oic.uuid
382     bool                   dpc;             // 7:R:S:Y:Boolean
383     OicUuid_t           owner;         // 7:R:S:Y:oic.uuid
384     // NOTE: we are using UUID for Owner instead of Svc type for mid-April
385     // SRM version only; this will change to Svc type for full implementation.
386     //OicSecSvc_t       devOwner;        // 7:R:S:Y:oic.sec.svc
387     //OicSecSvc_t       rOwner;        // 8:R:S:Y:oic.sec.svc
388     //TODO change Owner type to oic.sec.svc
389 };
390
391 /**
392  * /oic/sec/pstat (Provisioning Status) data type.
393  * NOTE: this struct is ahead of Spec v0.95 in definition to include Sm.
394  * TODO: change comment when reconciled to Spec v0.96.
395  */
396 struct OicSecPstat
397 {
398     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
399     bool                isOp;           // 0:R:S:Y:Boolean
400     OicSecDpm_t         cm;             // 1:R:S:Y:oic.sec.dpm
401     OicSecDpm_t         tm;             // 2:RW:S:Y:oic.sec.dpm
402     OicUuid_t           deviceID;       // 3:R:S:Y:oic.uuid
403     OicSecDpom_t        om;             // 4:RW:M:Y:oic.sec.dpom
404     size_t              smLen;          // the number of elts in Sm
405     OicSecDpom_t        *sm;            // 5:R:M:Y:oic.sec.dpom
406     uint16_t            commitHash;     // 6:R:S:Y:oic.sec.sha256
407     //TODO: this is supposed to be a 256-bit uint; temporarily use uint16_t
408     //TODO: need to decide which 256 bit and 128 bit types to use... boost?
409 };
410
411 /**
412  * /oic/sec/role (Role) data type.
413  * Derived from OIC Security Spec; see Spec for details.
414  */
415 struct OicSecRole
416 {
417     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
418     //TODO fill in with Role definition
419     uint8_t             id[ROLEID_LENGTH];
420 };
421
422 /**
423  * /oic/sec/sacl (Signed Access Control List) data type.
424  * Derived from OIC Security Spec; see Spec for details.
425  */
426 struct OicSecSacl
427 {
428     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
429     //TODO fill in from OIC Security Spec
430 };
431
432 /**
433  * /oic/sec/svc (Service requiring a secure connection) data type.
434  * Derived from OIC Security Spec; see Spec for details.
435  */
436 struct OicSecSvc
437 {
438     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
439     OicUuid_t               svcdid;                 //0:R:S:Y:oic.uuid
440     OicSecSvcType_t         svct;                   //1:R:M:Y:OIC Service Type
441     size_t                  ownersLen;              //2:the number of elts in Owners
442     OicUuid_t               *owners;                //3:R:M:Y:oic.uuid
443     OicSecSvc_t             *next;
444 };
445
446 #ifdef __WITH_X509__
447 struct OicSecCrl
448 {
449     uint16_t CrlId;
450     ByteArray ThisUpdate;
451     ByteArray CrlData;
452 };
453 #endif /* __WITH_X509__ */
454
455 /**
456  * @brief   direct pairing data type
457  */
458 typedef struct OicPin OicDpPin_t;
459
460 typedef struct OicSecPdAcl OicSecPdAcl_t;
461
462 typedef struct OicSecPconf OicSecPconf_t;
463
464 typedef struct OicSecDpairing OicSecDpairing_t;
465
466 #define DP_PIN_LENGTH 8 // temporary length
467
468 /**
469  * @brief   /oic/sec/prmtype (Pairing Method Type) data type.
470  *              0:  not allowed
471  *              1:  pre-configured pin
472  *              2:  random pin
473  */
474 typedef enum PRMBitmask
475 {
476     PRM_NOT_ALLOWED             = 0x0,
477     PRM_PRE_CONFIGURED        = (0x1 << 0),
478     PRM_RANDOM_PIN               = (0x1 << 1),
479 } PRMBitmask_t;
480
481 typedef PRMBitmask_t OicSecPrm_t;
482
483
484 struct OicPin
485 {
486     uint8_t             val[DP_PIN_LENGTH+1];
487 };
488
489 /**
490  * @brief   oic.sec.dpacltype (Device Pairing Access Control List) data type.
491  */
492 struct OicSecPdAcl
493 {
494     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
495     char                  **resources;        // 0:R:M:Y:String
496     size_t                resourcesLen;      // the number of elts in Resources
497     uint16_t             permission;        // 1:R:S:Y:UINT16
498     char                  **periods;            // 2:R:M*:N:String (<--M*; see Spec)
499     char                  **recurrences;    // 3:R:M:N:String
500     size_t                prdRecrLen;         // the number of elts in Periods/Recurrences
501     OicSecPdAcl_t    *next;
502 };
503
504 /**
505  * @brief   /oic/sec/pconf (Pairing Configuration) data type
506  */
507 struct OicSecPconf
508 {
509     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
510     bool                  edp;                // 0:W:S:M:Boolean
511     OicSecPrm_t      *prm;              // 1:R:M:N:UINT16
512     size_t                prmLen;          // the number of elts in Prm
513     OicDpPin_t          pin;               // 2:R:S:Y:String
514     OicSecPdAcl_t    *pdacls;         // 3:R:M:Y:oic.sec.pdacltype
515     OicUuid_t           *pddevs;        // 4:R:M:Y:oic.uuid
516     size_t                 pddevLen;     // the number of elts in pddev
517     OicUuid_t           deviceID;       // 5:R:S:Y:oic.uuid
518     OicUuid_t           rowner;          // 6:R:S:Y:oic.uuid
519 };
520
521 /**
522  * @brief   /oic/sec/dpairing (Device Pairing) data type
523  */
524 struct OicSecDpairing
525 {
526     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
527     OicSecPrm_t      spm;               // 0:R/W:S:Y:UINT16
528     OicUuid_t           pdeviceID;     // 1:R:S:Y:oic.uuid
529     OicUuid_t           rowner;          // 2:R:S:Y:oic.uuid
530 };
531
532 #ifdef __cplusplus
533 }
534 #endif
535
536 #endif //OC_SECURITY_RESOURCE_TYPES_H