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
  47 #ifdef __cplusplus
  48 extern "C" {
  49 #endif
  50
  51 /**
  52  * @brief   Values used to create bit-maskable enums for single-value
  53  *          response with embedded code.
  54  */
  55 #define ACCESS_GRANTED_DEF            (1 << 0)
  56 #define ACCESS_DENIED_DEF             (1 << 1)
  57 #define INSUFFICIENT_PERMISSION_DEF   (1 << 2)
  58 #define SUBJECT_NOT_FOUND_DEF         (1 << 3)
  59 #define RESOURCE_NOT_FOUND_DEF        (1 << 4)
  60 #define POLICY_ENGINE_ERROR_DEF       (1 << 5)
  61 #define REASON_MASK_DEF               (INSUFFICIENT_PERMISSION_DEF | \
  62                                        SUBJECT_NOT_FOUND_DEF | \
  63                                        RESOURCE_NOT_FOUND_DEF | \
  64                                        POLICY_ENGINE_ERROR_DEF)
  65
  66
  67 /**
  68  * Access policy in least significant bits (from Spec):
  69  * 1st lsb:  C (Create)
  70  * 2nd lsb:  R (Read, Observe, Discover)
  71  * 3rd lsb:  U (Write, Update)
  72  * 4th lsb:  D (Delete)
  73  * 5th lsb:  N (Notify)
  74  */
  75 #define PERMISSION_CREATE       (1 << 0)
  76 #define PERMISSION_READ         (1 << 1)
  77 #define PERMISSION_WRITE        (1 << 2)
  78 #define PERMISSION_DELETE       (1 << 3)
  79 #define PERMISSION_NOTIFY       (1 << 4)
  80 #define PERMISSION_FULL_CONTROL (PERMISSION_CREATE | \
  81                                  PERMISSION_READ | \
  82                                  PERMISSION_WRITE | \
  83                                  PERMISSION_DELETE | \
  84                                  PERMISSION_NOTIFY)
  85
  86 /**
  87  * @brief   Response type for all Action requests from CA layer;
  88  *          may include a reason code.
  89  *
  90  * To extract codes use GetReasonCode function on SRMAccessResponse:
  91  *
  92  * SRMAccessResponse_t response = SRMRequestHandler(obj, info);
  93  * if(SRM_TRUE == IsAccessGranted(response)) {
  94  *     SRMAccessResponseReasonCode_t reason = GetReasonCode(response);
  95  *     switch(reason) {
  96  *         case INSUFFICIENT_PERMISSION:
  97  *         ...etc.
  98  *     }
  99  * }
 100  */
 101 typedef enum
 102 {
 103     ACCESS_GRANTED = ACCESS_GRANTED_DEF,
 104     ACCESS_DENIED = ACCESS_DENIED_DEF,
 105     ACCESS_DENIED_INSUFFICIENT_PERMISSION = ACCESS_DENIED_DEF
 106         | INSUFFICIENT_PERMISSION_DEF,
 107     ACCESS_DENIED_SUBJECT_NOT_FOUND = ACCESS_DENIED_DEF
 108         | SUBJECT_NOT_FOUND_DEF,
 109     ACCESS_DENIED_RESOURCE_NOT_FOUND = ACCESS_DENIED_DEF
 110         | RESOURCE_NOT_FOUND_DEF,
 111     ACCESS_DENIED_POLICY_ENGINE_ERROR = ACCESS_DENIED_DEF
 112         | POLICY_ENGINE_ERROR_DEF,
 113 } SRMAccessResponse_t;
 114
 115 /**
 116  * Reason code for SRMAccessResponse.
 117  */
 118 typedef enum
 119 {
 120     NO_REASON_GIVEN = 0,
 121     INSUFFICIENT_PERMISSION = INSUFFICIENT_PERMISSION_DEF,
 122     SUBJECT_NOT_FOUND = SUBJECT_NOT_FOUND_DEF,
 123     RESOURCE_NOT_FOUND = RESOURCE_NOT_FOUND_DEF,
 124 } SRMAccessResponseReasonCode_t;
 125
 126 /**
 127  * Extract Reason Code from Access Response.
 128  */
 129 static inline SRMAccessResponseReasonCode_t GetReasonCode(
 130     SRMAccessResponse_t response)
 131 {
 132     SRMAccessResponseReasonCode_t reason =
 133         (SRMAccessResponseReasonCode_t)(response & REASON_MASK_DEF);
 134     return reason;
 135 }
 136
 137 /**
 138  * Returns 'true' iff request should be passed on to RI layer.
 139  */
 140 static inline bool IsAccessGranted(SRMAccessResponse_t response)
 141 {
 142     if(ACCESS_GRANTED == (response & ACCESS_GRANTED))
 143     {
 144         return true;
 145     }
 146     else
 147     {
 148         return false;
 149     }
 150 }
 151
 152 typedef struct OicSecAcl OicSecAcl_t;
 153
 154 typedef struct OicSecAmacl OicSecAmacl_t;
 155
 156 typedef struct OicSecCred OicSecCred_t;
 157
 158 /**
 159  * @brief   /oic/sec/credtype (Credential Type) data type.
 160  *          Derived from OIC Security Spec /oic/sec/cred; see Spec for details.
 161  *              0:  no security mode
 162  *              1:  symmetric pair-wise key
 163  *              2:  symmetric group key
 164  *              4:  asymmetric key
 165  *              8:  signed asymmetric key (aka certificate)
 166  *              16: PIN /password
 167  */
 168 typedef uint16_t OicSecCredType_t;
 169
 170 /**
 171  * Aid for assigning/testing vals with OicSecCredType_t.
 172  * Example:
 173  *  OicSecCredType_t ct = PIN_PASSWORD | ASYMMETRIC_KEY;
 174  *  if((ct & PIN_PASSWORD) == PIN_PASSWORD)
 175  *  {
 176  *      // ct contains PIN_PASSWORD flag.
 177  *  }
 178  */
 179 typedef enum OSCTBitmask
 180 {
 181     NO_SECURITY_MODE                = 0x0,
 182     SYMMETRIC_PAIR_WISE_KEY         = (0x1 << 0),
 183     SYMMETRIC_GROUP_KEY             = (0x1 << 1),
 184     ASYMMETRIC_KEY                  = (0x1 << 2),
 185     SIGNED_ASYMMETRIC_KEY           = (0x1 << 3),
 186     PIN_PASSWORD                    = (0x1 << 4),
 187 } OSCTBitmask_t;
 188
 189 typedef struct OicSecDoxm OicSecDoxm_t;
 190
 191 typedef enum OicSecDpm
 192 {
 193     NORMAL                          = 0x0,
 194     RESET                           = (0x1 << 0),
 195     TAKE_OWNER                      = (0x1 << 1),
 196     BOOTSTRAP_SERVICE               = (0x1 << 2),
 197     SECURITY_MANAGEMENT_SERVICES    = (0x1 << 3),
 198     PROVISION_CREDENTIALS           = (0x1 << 4),
 199     PROVISION_ACLS                  = (0x1 << 5),
 200     // << 6 THROUGH 15 RESERVED
 201 } OicSecDpm_t;
 202
 203 typedef enum OicSecDpom
 204 {
 205     MULTIPLE_SERVICE_SERVER_DRIVEN  = 0x0,
 206     SINGLE_SERVICE_SERVER_DRIVEN    = 0x1,
 207     MULTIPLE_SERVICE_CLIENT_DRIVEN  = 0x2,
 208     SINGLE_SERVICE_CLIENT_DRIVEN    = 0x3,
 209 } OicSecDpom_t;
 210
 211 typedef enum OicSecSvcType
 212 {
 213     SERVICE_UNKNOWN                 = 0x0,
 214     ACCESS_MGMT_SERVICE             = 0x1,  //urn:oic.sec.ams
 215 } OicSecSvcType_t;
 216
 217
 218 //TODO: Need more clarification on deviceIDFormat field type.
 219 #if 0
 220 typedef enum
 221 {
 222     URN = 0x0
 223 }OicSecDvcIdFrmt_t;
 224 #endif
 225
 226 typedef enum
 227 {
 228     OIC_JUST_WORKS                          = 0x0,
 229     OIC_MODE_SWITCH                         = 0x1,
 230     OIC_RANDOM_DEVICE_PIN                   = 0x2,
 231     OIC_PRE_PROVISIONED_DEVICE_PIN          = 0x3,
 232     OIC_PRE_PROVISION_STRONG_CREDENTIAL     = 0x4
 233 }OicSecOxm_t;
 234
 235 typedef struct OicSecJwk OicSecJwk_t;
 236
 237 typedef struct OicSecPstat OicSecPstat_t;
 238
 239 typedef struct OicSecRole OicSecRole_t;
 240
 241 typedef struct OicSecSacl OicSecSacl_t;
 242
 243 typedef struct OicSecSvc OicSecSvc_t;
 244
 245 typedef char *OicUrn_t; //TODO is URN type defined elsewhere?
 246
 247 typedef struct OicUuid OicUuid_t; //TODO is UUID type defined elsewhere?
 248
 249
 250 /**
 251  * @brief   /oic/uuid (Universal Unique Identifier) data type.
 252  */
 253 #define UUID_LENGTH 128/8 // 128-bit GUID length
 254 //TODO: Confirm the length and type of ROLEID.
 255 #define ROLEID_LENGTH 128/8 // 128-bit ROLEID length
 256 #define OWNER_PSK_LENGTH_128 128/8 //byte size of 128-bit key size
 257 #define OWNER_PSK_LENGTH_256 256/8 //byte size of 256-bit key size
 258
 259 struct OicUuid
 260 {
 261     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 262     //TODO fill in unless this is defined elsewhere?
 263     uint8_t             id[UUID_LENGTH];
 264 };
 265
 266 /**
 267  * @brief   /oic/sec/jwk (JSON Web Key) data type.
 268  *          See JSON Web Key (JWK)  draft-ietf-jose-json-web-key-41
 269  */
 270 #define JWK_LENGTH 256/8 // 256 bit key length
 271 struct OicSecJwk
 272 {
 273     char                *data;
 274 };
 275
 276 /**
 277  * @brief   /oic/sec/acl (Access Control List) data type.
 278  *          Derived from OIC Security Spec; see Spec for details.
 279  */
 280 struct OicSecAcl
 281 {
 282     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 283     OicUuid_t           subject;        // 0:R:S:Y:uuid TODO: this deviates
 284                                         // from spec and needs to be updated
 285                                         // in spec (where it's a String).
 286     size_t              resourcesLen;   // the number of elts in Resources
 287     char                **resources;    // 1:R:M:Y:String
 288     uint16_t            permission;     // 2:R:S:Y:UINT16
 289     size_t              periodsLen;     // the number of elts in Periods
 290     char                **periods;      // 3:R:M*:N:String (<--M*; see Spec)
 291     char                *recurrences;   // 5:R:M:N:String
 292     size_t              ownersLen;      // the number of elts in Owners
 293     OicUuid_t           *owners;        // 8:R:M:Y:oic.uuid
 294     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
 295     // SRM version only; this will change to Svc type for full implementation.
 296     //TODO change Owners type to oic.sec.svc
 297     //OicSecSvc_t         *Owners;        // 6:R:M:Y:oic.sec.svc
 298     OicSecAcl_t         *next;
 299 };
 300
 301 /**
 302  * @brief   /oic/sec/amacl (Access Manager Service Accesss Control List)
 303  *          data type.
 304  *          Derived from OIC Security Spec; see Spec for details.
 305  */
 306 struct OicSecAmacl
 307 {
 308     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 309     size_t              resourcesLen;   // the number of elts in Resources
 310     char                **resources;    // 0:R:M:Y:String
 311     size_t              amssLen;        // the number of elts in Amss
 312     OicUuid_t           *amss;          // 1:R:M:Y:acl
 313     size_t              ownersLen;      // the number of elts in Owners
 314     OicUuid_t           *owners;        // 2:R:M:Y:oic.uuid
 315     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
 316     // SRM version only; this will change to Svc type for full implementation.
 317     //TODO change Owners type to oic.sec.svc
 318     //OicSecSvc_t         *Owners;        // 2:R:M:Y:oic.sec.svc
 319     OicSecAmacl_t         *next;
 320 };
 321
 322 /**
 323  * @brief   /oic/sec/cred (Credential) data type.
 324  *          Derived from OIC Security Spec; see Spec for details.
 325  */
 326 struct OicSecCred
 327 {
 328     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 329     uint16_t            credId;         // 0:R:S:Y:UINT16
 330     OicUuid_t           subject;        // 1:R:S:Y:oic.uuid
 331     //Note: Need further clarification on roleID data type
 332     //NOTE: Need further clarification on roleId datatype.
 333     //size_t              roleIdsLen;     // the number of elts in RoleIds
 334     //OicSecRole_t        *roleIds;       // 2:R:M:N:oic.sec.role
 335     OicSecCredType_t    credType;       // 3:R:S:Y:oic.sec.credtype
 336     OicSecJwk_t         publicData;     // 5:R:S:N:oic.sec.jwk
 337     OicSecJwk_t         privateData;    // 6:R:S:N:oic.sec.jwk
 338     char                *period;        // 7:R:S:N:String
 339     size_t              ownersLen;      // the number of elts in Owners
 340     OicUuid_t           *owners;        // 8:R:M:Y:oic.uuid
 341     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
 342     // SRM version only; this will change to Svc type for full implementation.
 343     //OicSecSvc_t         *Owners;        // 8:R:M:Y:oic.sec.svc
 344     //TODO change Owners type to oic.sec.svc
 345     OicSecCred_t        *next;
 346 };
 347
 348 /**
 349  * @brief   /oic/sec/doxm (Device Owner Transfer Methods) data type
 350  *          Derived from OIC Security Spec; see Spec for details.
 351  */
 352 struct OicSecDoxm
 353 {
 354     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 355     OicUrn_t            *oxmType;       // 0:R:M:N:URN
 356     size_t              oxmTypeLen;     // the number of elts in OxmType
 357     OicSecOxm_t         *oxm;           // 1:R:M:N:UINT16
 358     size_t              oxmLen;         // the number of elts in Oxm
 359     OicSecOxm_t         oxmSel;         // 2:R/W:S:Y:UINT16
 360     bool                owned;          // 3:R:S:Y:Boolean
 361     //TODO: Need more clarification on deviceIDFormat field type.
 362     //OicSecDvcIdFrmt_t   deviceIDFormat; // 4:R:S:Y:UINT8
 363     OicUuid_t           deviceID;       // 5:R:S:Y:oic.uuid
 364     OicUuid_t           owner;         // 6:R:S:Y:oic.uuid
 365     // NOTE: we are using UUID for Owner instead of Svc type for mid-April
 366     // SRM version only; this will change to Svc type for full implementation.
 367     //OicSecSvc_t       Owner;        // 5:R:S:Y:oic.sec.svc
 368     //TODO change Owner type to oic.sec.svc
 369 };
 370
 371 /**
 372  * @brief   /oic/sec/pstat (Provisioning Status) data type.
 373  * NOTE: this struct is ahead of Spec v0.95 in definition to include Sm.
 374  * TODO: change comment when reconciled to Spec v0.96.
 375  */
 376 struct OicSecPstat
 377 {
 378     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 379     bool                isOp;           // 0:R:S:Y:Boolean
 380     OicSecDpm_t         cm;             // 1:R:S:Y:oic.sec.dpm
 381     OicSecDpm_t         tm;             // 2:RW:S:Y:oic.sec.dpm
 382     OicUuid_t           deviceID;       // 3:R:S:Y:oic.uuid
 383     OicSecDpom_t        om;             // 4:RW:M:Y:oic.sec.dpom
 384     size_t              smLen;          // the number of elts in Sm
 385     OicSecDpom_t        *sm;            // 5:R:M:Y:oic.sec.dpom
 386     uint16_t            commitHash;     // 6:R:S:Y:oic.sec.sha256
 387     //TODO: this is supposed to be a 256-bit uint; temporarily use uint16_t
 388     //TODO: need to decide which 256 bit and 128 bit types to use... boost?
 389 };
 390
 391 /**
 392  * @brief   /oic/sec/role (Role) data type.
 393  *          Derived from OIC Security Spec; see Spec for details.
 394  */
 395 struct OicSecRole
 396 {
 397     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 398     //TODO fill in with Role definition
 399     uint8_t             id[ROLEID_LENGTH];
 400 };
 401
 402 /**
 403  * @brief   /oic/sec/sacl (Signed Access Control List) data type.
 404  *          Derived from OIC Security Spec; see Spec for details.
 405  */
 406 struct OicSecSacl
 407 {
 408     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 409     //TODO fill in from OIC Security Spec
 410 };
 411
 412 /**
 413  * @brief   /oic/sec/svc (Service requiring a secure connection) data type.
 414  *          Derived from OIC Security Spec; see Spec for details.
 415  */
 416 struct OicSecSvc
 417 {
 418     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 419     OicUuid_t               svcdid;                 //0:R:S:Y:oic.uuid
 420     OicSecSvcType_t         svct;                   //1:R:M:Y:OIC Service Type
 421     size_t                  ownersLen;              //2:the number of elts in Owners
 422     OicUuid_t               *owners;                //3:R:M:Y:oic.uuid
 423     OicSecSvc_t             *next;
 424 };
 425
 426 #ifdef __cplusplus
 427 }
 428 #endif
 429
 430 #endif //OC_SECURITY_RESOURCE_TYPES_H