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