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