Prepare for merge. Improved consistency and style.
[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 #include "platform_features.h"
51
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
55
56 /**
57  * Values used to create bit-maskable enums for single-value response with
58  * embedded code.
59  */
60 #define ACCESS_GRANTED_DEF            (1 << 0)
61 #define ACCESS_DENIED_DEF             (1 << 1)
62 #define INSUFFICIENT_PERMISSION_DEF   (1 << 2)
63 #define SUBJECT_NOT_FOUND_DEF         (1 << 3)
64 #define RESOURCE_NOT_FOUND_DEF        (1 << 4)
65 #define POLICY_ENGINE_ERROR_DEF       (1 << 5)
66 #define INVALID_PERIOD_DEF            (1 << 6)
67 #define ACCESS_WAITING_DEF            (1 << 7)
68 #define AMS_SERVICE_DEF               (1 << 8)
69 #define REASON_MASK_DEF               (INSUFFICIENT_PERMISSION_DEF | \
70                                        INVALID_PERIOD_DEF | \
71                                        SUBJECT_NOT_FOUND_DEF | \
72                                        RESOURCE_NOT_FOUND_DEF | \
73                                        POLICY_ENGINE_ERROR_DEF)
74
75
76 /**
77  * Access policy in least significant bits (from Spec):
78  * 1st lsb:  C (Create)
79  * 2nd lsb:  R (Read, Observe, Discover)
80  * 3rd lsb:  U (Write, Update)
81  * 4th lsb:  D (Delete)
82  * 5th lsb:  N (Notify)
83  */
84 #define PERMISSION_CREATE       (1 << 0)
85 #define PERMISSION_READ         (1 << 1)
86 #define PERMISSION_WRITE        (1 << 2)
87 #define PERMISSION_DELETE       (1 << 3)
88 #define PERMISSION_NOTIFY       (1 << 4)
89 #define PERMISSION_FULL_CONTROL (PERMISSION_CREATE | \
90                                  PERMISSION_READ | \
91                                  PERMISSION_WRITE | \
92                                  PERMISSION_DELETE | \
93                                  PERMISSION_NOTIFY)
94
95 /**
96  * @brief   Response type for all Action requests from CA layer;
97  *          may include a reason code.
98  *
99  * To extract codes use GetReasonCode function on SRMAccessResponse:
100  *
101  * SRMAccessResponse_t response = SRMRequestHandler(obj, info);
102  * if(SRM_TRUE == IsAccessGranted(response)) {
103  *     SRMAccessResponseReasonCode_t reason = GetReasonCode(response);
104  *     switch(reason) {
105  *         case INSUFFICIENT_PERMISSION:
106  *         ...etc.
107  *     }
108  * }
109  */
110 typedef enum
111 {
112     ACCESS_GRANTED = ACCESS_GRANTED_DEF,
113     ACCESS_DENIED = ACCESS_DENIED_DEF,
114     ACCESS_DENIED_INVALID_PERIOD = ACCESS_DENIED_DEF
115         | INVALID_PERIOD_DEF,
116     ACCESS_DENIED_INSUFFICIENT_PERMISSION = ACCESS_DENIED_DEF
117         | INSUFFICIENT_PERMISSION_DEF,
118     ACCESS_DENIED_SUBJECT_NOT_FOUND = ACCESS_DENIED_DEF
119         | SUBJECT_NOT_FOUND_DEF,
120     ACCESS_DENIED_RESOURCE_NOT_FOUND = ACCESS_DENIED_DEF
121         | RESOURCE_NOT_FOUND_DEF,
122     ACCESS_DENIED_POLICY_ENGINE_ERROR = ACCESS_DENIED_DEF
123         | POLICY_ENGINE_ERROR_DEF,
124     ACCESS_WAITING_FOR_AMS = ACCESS_WAITING_DEF
125         | AMS_SERVICE_DEF,
126     ACCESS_DENIED_AMS_SERVICE_ERROR = ACCESS_DENIED
127         | AMS_SERVICE_DEF
128 } SRMAccessResponse_t;
129
130 /**
131  * Reason code for SRMAccessResponse.
132  */
133 typedef enum
134 {
135     NO_REASON_GIVEN = 0,
136     INSUFFICIENT_PERMISSION = INSUFFICIENT_PERMISSION_DEF,
137     SUBJECT_NOT_FOUND = SUBJECT_NOT_FOUND_DEF,
138     RESOURCE_NOT_FOUND = RESOURCE_NOT_FOUND_DEF,
139 } SRMAccessResponseReasonCode_t;
140
141 /**
142  * Extract Reason Code from Access Response.
143  */
144 INLINE_API SRMAccessResponseReasonCode_t GetReasonCode(
145     SRMAccessResponse_t response)
146 {
147     SRMAccessResponseReasonCode_t reason =
148         (SRMAccessResponseReasonCode_t)(response & REASON_MASK_DEF);
149     return reason;
150 }
151
152 /**
153  * Returns 'true' iff request should be passed on to RI layer.
154  */
155 INLINE_API bool IsAccessGranted(SRMAccessResponse_t response)
156 {
157     if(ACCESS_GRANTED == (response & ACCESS_GRANTED))
158     {
159         return true;
160     }
161     else
162     {
163         return false;
164     }
165 }
166
167 typedef struct OicSecAcl OicSecAcl_t;
168
169 typedef struct OicSecAmacl OicSecAmacl_t;
170
171 typedef struct OicSecCred OicSecCred_t;
172
173 /**
174  * Aid for assigning/testing vals with OicSecCredType_t.
175  * Example:
176  *  OicSecCredType_t ct = PIN_PASSWORD | ASYMMETRIC_KEY;
177  *  if((ct & PIN_PASSWORD) == PIN_PASSWORD)
178  *  {
179  *      // ct contains PIN_PASSWORD flag.
180  *  }
181  */
182 typedef enum OSCTBitmask
183 {
184     NO_SECURITY_MODE                = 0x0,
185     SYMMETRIC_PAIR_WISE_KEY         = (0x1 << 0),
186     SYMMETRIC_GROUP_KEY             = (0x1 << 1),
187     ASYMMETRIC_KEY                  = (0x1 << 2),
188     SIGNED_ASYMMETRIC_KEY           = (0x1 << 3),
189     PIN_PASSWORD                    = (0x1 << 4),
190     ASYMMETRIC_ENCRYPTION_KEY       = (0x1 << 5),
191 } OSCTBitmask_t;
192
193 /**
194  * /oic/sec/credtype (Credential Type) data type.
195  * Derived from OIC Security Spec /oic/sec/cred; see Spec for details.
196  *              0:  no security mode
197  *              1:  symmetric pair-wise key
198  *              2:  symmetric group key
199  *              4:  asymmetric key
200  *              8:  signed asymmetric key (aka certificate)
201  *              16: PIN /password
202  */
203 typedef OSCTBitmask_t OicSecCredType_t;
204
205 typedef struct OicSecDoxm OicSecDoxm_t;
206
207 typedef enum OicSecDpm
208 {
209     NORMAL                          = 0x0,
210     RESET                           = (0x1 << 0),
211     TAKE_OWNER                      = (0x1 << 1),
212     BOOTSTRAP_SERVICE               = (0x1 << 2),
213     SECURITY_MANAGEMENT_SERVICES    = (0x1 << 3),
214     PROVISION_CREDENTIALS           = (0x1 << 4),
215     PROVISION_ACLS                  = (0x1 << 5),
216     // << 6 THROUGH 15 RESERVED
217 } OicSecDpm_t;
218
219 typedef enum OicSecDpom
220 {
221     MULTIPLE_SERVICE_SERVER_DRIVEN  = 0x0,
222     SINGLE_SERVICE_SERVER_DRIVEN    = 0x1,
223     MULTIPLE_SERVICE_CLIENT_DRIVEN  = 0x2,
224     SINGLE_SERVICE_CLIENT_DRIVEN    = 0x3,
225 } OicSecDpom_t;
226
227 typedef enum OicSecSvcType
228 {
229     SERVICE_UNKNOWN                 = 0x0,
230     ACCESS_MGMT_SERVICE             = 0x1,  //urn:oic.sec.ams
231 } OicSecSvcType_t;
232
233
234 //TODO: Need more clarification on deviceIDFormat field type.
235 #if 0
236 typedef enum
237 {
238     URN = 0x0
239 }OicSecDvcIdFrmt_t;
240 #endif
241
242 typedef enum
243 {
244     OIC_R_ACL_TYPE = 0,
245     OIC_R_AMACL_TYPE,
246     OIC_R_CRED_TYPE,
247     OIC_R_CRL_TYPE,
248     OIC_R_DOXM_TYPE,
249     OIC_R_DPAIRING_TYPE,
250     OIC_R_PCONF_TYPE,
251     OIC_R_PSTAT_TYPE,
252     OIC_R_SACL_TYPE,
253     OIC_R_SVC_TYPE,
254     OIC_SEC_SVR_TYPE_COUNT, //define the value to number of SVR
255     NOT_A_SVR_RESOURCE = 99
256 }OicSecSvrType_t;
257
258 typedef enum
259 {
260     OIC_JUST_WORKS                          = 0x0,
261     OIC_RANDOM_DEVICE_PIN                   = 0x1,
262     OIC_MANUFACTURER_CERTIFICATE           = 0x2,
263     OIC_OXM_COUNT
264 }OicSecOxm_t;
265
266 typedef struct OicSecKey OicSecKey_t;
267
268 typedef struct OicSecPstat OicSecPstat_t;
269
270 typedef struct OicSecRole OicSecRole_t;
271
272 typedef struct OicSecSacl OicSecSacl_t;
273
274 typedef struct OicSecSvc OicSecSvc_t;
275
276 typedef char *OicUrn_t; //TODO is URN type defined elsewhere?
277
278 typedef struct OicUuid OicUuid_t; //TODO is UUID type defined elsewhere?
279
280
281 #ifdef __WITH_X509__
282 typedef struct OicSecCrl OicSecCrl_t;
283 typedef ByteArray OicSecCert_t;
284 #else
285 typedef void OicSecCert_t;
286 #endif /* __WITH_X509__ */
287
288 /**
289  * /oic/uuid (Universal Unique Identifier) data type.
290  */
291 #define UUID_LENGTH 128/8 // 128-bit GUID length
292 //TODO: Confirm the length and type of ROLEID.
293 #define ROLEID_LENGTH 128/8 // 128-bit ROLEID length
294 #define OWNER_PSK_LENGTH_128 128/8 //byte size of 128-bit key size
295 #define OWNER_PSK_LENGTH_256 256/8 //byte size of 256-bit key size
296
297 struct OicUuid
298 {
299     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
300     //TODO fill in unless this is defined elsewhere?
301     uint8_t             id[UUID_LENGTH];
302 };
303
304 /**
305  * /oic/sec/jwk (JSON Web Key) data type.
306  * See JSON Web Key (JWK)  draft-ietf-jose-json-web-key-41
307  */
308 #define JWK_LENGTH 256/8 // 256 bit key length
309 struct OicSecKey
310 {
311     uint8_t                *data;
312     size_t                  len;
313 };
314
315 /**
316  * /oic/sec/acl (Access Control List) data type.
317  * Derived from OIC Security Spec; see Spec for details.
318  */
319 struct OicSecAcl
320 {
321     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
322     OicUuid_t           subject;        // 0:R:S:Y:uuid TODO: this deviates
323                                         // from spec and needs to be updated
324                                         // in spec (where it's a String).
325     size_t              resourcesLen;   // the number of elts in Resources
326     char                **resources;    // 1:R:M:Y:String
327     uint16_t            permission;     // 2:R:S:Y:UINT16
328     size_t              prdRecrLen;     // the number of elts in Periods
329     char                **periods;       // 3:R:M*:N:String (<--M*; see Spec)
330     char                **recurrences;   // 5:R:M:N:String
331     OicUuid_t           rownerID;        // 8:R:S:Y:oic.uuid
332     OicSecAcl_t         *next;
333 };
334
335 /**
336  * /oic/sec/amacl (Access Manager Service Accesss Control List) data type.
337  * Derived from OIC Security Spec; see Spec for details.
338  */
339 struct OicSecAmacl
340 {
341     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
342     size_t              resourcesLen;   // the number of elts in Resources
343     char                **resources;    // 0:R:M:Y:String
344     size_t              amssLen;        // the number of elts in Amss
345     OicUuid_t           *amss;          // 1:R:M:Y:acl
346     OicUuid_t           rownerID;        // 2:R:S:Y:oic.uuid
347     OicSecAmacl_t         *next;
348 };
349
350 /**
351  * /oic/sec/cred (Credential) data type.
352  * Derived from OIC Security Spec; see Spec for details.
353  */
354 struct OicSecCred
355 {
356     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
357     uint16_t            credId;         // 0:R:S:Y:UINT16
358     OicUuid_t           subject;        // 1:R:S:Y:oic.uuid
359     //Note: Need further clarification on roleID data type
360     //NOTE: Need further clarification on roleId datatype.
361     //size_t              roleIdsLen;     // the number of elts in RoleIds
362     //OicSecRole_t        *roleIds;       // 2:R:M:N:oic.sec.role
363     OicSecCredType_t    credType;       // 3:R:S:Y:oic.sec.credtype
364 #ifdef __WITH_X509__
365     OicSecCert_t        publicData;     // chain of certificates
366 #endif /* __WITH_X509__ */
367     OicSecKey_t         privateData;    // 6:R:S:N:oic.sec.key
368     char                *period;        // 7:R:S:N:String
369     OicUuid_t           rownerID;        // 8:R:S:Y:oic.uuid
370     OicSecCred_t        *next;
371 };
372
373 /**
374  * /oic/sec/doxm (Device Owner Transfer Methods) data type
375  * Derived from OIC Security Spec; see Spec for details.
376  */
377 struct OicSecDoxm
378 {
379     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
380     OicUrn_t            *oxmType;       // 0:R:M:N:URN
381     size_t              oxmTypeLen;     // the number of elts in OxmType
382     OicSecOxm_t         *oxm;           // 1:R:M:N:UINT16
383     size_t              oxmLen;         // the number of elts in Oxm
384     OicSecOxm_t         oxmSel;         // 2:R/W:S:Y:UINT16
385     OicSecCredType_t    sct;            // 3:R:S:Y:oic.sec.credtype
386     bool                owned;          // 4:R:S:Y:Boolean
387     //TODO: Need more clarification on deviceIDFormat field type.
388     //OicSecDvcIdFrmt_t   deviceIDFormat; // 5:R:S:Y:UINT8
389     OicUuid_t           deviceID;       // 6:R:S:Y:oic.uuid
390     bool                dpc;            // 7:R:S:Y:Boolean
391     OicUuid_t           owner;          // 8:R:S:Y:oic.uuid
392     OicUuid_t           rownerID;       // 9:R:S:Y:oic.uuid
393 };
394
395 /**
396  * /oic/sec/pstat (Provisioning Status) data type.
397  * NOTE: this struct is ahead of Spec v0.95 in definition to include Sm.
398  * TODO: change comment when reconciled to Spec v0.96.
399  */
400 struct OicSecPstat
401 {
402     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
403     bool                isOp;           // 0:R:S:Y:Boolean
404     OicSecDpm_t         cm;             // 1:R:S:Y:oic.sec.dpm
405     OicSecDpm_t         tm;             // 2:RW:S:Y:oic.sec.dpm
406     OicUuid_t           deviceID;       // 3:R:S:Y:oic.uuid
407     OicSecDpom_t        om;             // 4:RW:M:Y:oic.sec.dpom
408     size_t              smLen;          // the number of elts in Sm
409     OicSecDpom_t        *sm;            // 5:R:M:Y:oic.sec.dpom
410     uint16_t            commitHash;     // 6:R:S:Y:oic.sec.sha256
411     OicUuid_t           rownerID;       // 7:R:S:Y:oic.uuid
412 };
413
414 /**
415  * /oic/sec/role (Role) data type.
416  * Derived from OIC Security Spec; see Spec for details.
417  */
418 struct OicSecRole
419 {
420     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
421     //TODO fill in with Role definition
422     uint8_t             id[ROLEID_LENGTH];
423 };
424
425 /**
426  * /oic/sec/sacl (Signed Access Control List) data type.
427  * Derived from OIC Security Spec; see Spec for details.
428  */
429 struct OicSecSacl
430 {
431     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
432     //TODO fill in from OIC Security Spec
433 #if defined(_MSC_VER)
434     uint8_t unused; // VS doesn't like empty structs
435 #endif
436 };
437
438 /**
439  * /oic/sec/svc (Service requiring a secure connection) data type.
440  * Derived from OIC Security Spec; see Spec for details.
441  */
442 struct OicSecSvc
443 {
444     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
445     OicUuid_t               svcdid;                 //0:R:S:Y:oic.uuid
446     OicSecSvcType_t         svct;                   //1:R:M:Y:OIC Service Type
447     size_t                  ownersLen;              //2:the number of elts in Owners
448     OicUuid_t               *owners;                //3:R:M:Y:oic.uuid
449     OicSecSvc_t             *next;
450 };
451
452 #ifdef __WITH_X509__
453 struct OicSecCrl
454 {
455     uint16_t CrlId;
456     ByteArray ThisUpdate;
457     ByteArray CrlData;
458 };
459 #endif /* __WITH_X509__ */
460
461 /**
462  * @brief   direct pairing data type
463  */
464 typedef struct OicPin OicDpPin_t;
465
466 typedef struct OicSecPdAcl OicSecPdAcl_t;
467
468 typedef struct OicSecPconf OicSecPconf_t;
469
470 typedef struct OicSecDpairing OicSecDpairing_t;
471
472 #define DP_PIN_LENGTH 8 // temporary length
473
474 /**
475  * @brief   /oic/sec/prmtype (Pairing Method Type) data type.
476  *              0:  not allowed
477  *              1:  pre-configured pin
478  *              2:  random pin
479  */
480 typedef enum PRMBitmask
481 {
482     PRM_NOT_ALLOWED             = 0x0,
483     PRM_PRE_CONFIGURED        = (0x1 << 0),
484     PRM_RANDOM_PIN               = (0x1 << 1),
485 } PRMBitmask_t;
486
487 typedef PRMBitmask_t OicSecPrm_t;
488
489
490 struct OicPin
491 {
492     uint8_t             val[DP_PIN_LENGTH];
493 };
494
495 /**
496  * @brief   oic.sec.dpacltype (Device Pairing Access Control List) data type.
497  */
498 struct OicSecPdAcl
499 {
500     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
501     char                  **resources;        // 0:R:M:Y:String
502     size_t                resourcesLen;      // the number of elts in Resources
503     uint16_t             permission;        // 1:R:S:Y:UINT16
504     char                  **periods;            // 2:R:M*:N:String (<--M*; see Spec)
505     char                  **recurrences;    // 3:R:M:N:String
506     size_t                prdRecrLen;         // the number of elts in Periods/Recurrences
507     OicSecPdAcl_t    *next;
508 };
509
510 /**
511  * @brief   /oic/sec/pconf (Pairing Configuration) data type
512  */
513 struct OicSecPconf
514 {
515     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
516     bool                  edp;                // 0:W:S:M:Boolean
517     OicSecPrm_t      *prm;              // 1:R:M:N:UINT16
518     size_t                prmLen;          // the number of elts in Prm
519     OicDpPin_t          pin;               // 2:R:S:Y:String
520     OicSecPdAcl_t    *pdacls;         // 3:R:M:Y:oic.sec.pdacltype
521     OicUuid_t           *pddevs;        // 4:R:M:Y:oic.uuid
522     size_t                 pddevLen;     // the number of elts in pddev
523     OicUuid_t           deviceID;       // 5:R:S:Y:oic.uuid
524     OicUuid_t           rownerID;          // 6:R:S:Y:oic.uuid
525 };
526
527 /**
528  * @brief   /oic/sec/dpairing (Device Pairing) data type
529  */
530 struct OicSecDpairing
531 {
532     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
533     OicSecPrm_t      spm;               // 0:R/W:S:Y:UINT16
534     OicUuid_t           pdeviceID;     // 1:R:S:Y:oic.uuid
535     OicUuid_t           rownerID;          // 2:R:S:Y:oic.uuid
536 };
537
538 #define MAX_VERSION_LEN 16 // Security Version length. i.e., 00.00.000 + reserved space
539
540 /**
541  * @brief   security version data type
542  */
543 typedef struct OicSecVer OicSecVer_t;
544
545 /**
546  * @brief   /oic/sec/ver (Security Version) data type
547  */
548 struct OicSecVer
549 {
550     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
551     char              secv[MAX_VERSION_LEN];          // 0:R:S:Y:String
552     OicUuid_t       deviceID;     // 1:R:S:Y:oic.uuid
553 };
554
555 #ifdef __cplusplus
556 }
557 #endif
558
559 #endif //OC_SECURITY_RESOURCE_TYPES_H