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  * Aid for assigning/testing vals with OicSecCredType_t.
 167  * Example:
 168  *  OicSecCredType_t ct = PIN_PASSWORD | ASYMMETRIC_KEY;
 169  *  if((ct & PIN_PASSWORD) == PIN_PASSWORD)
 170  *  {
 171  *      // ct contains PIN_PASSWORD flag.
 172  *  }
 173  */
 174 typedef enum OSCTBitmask
 175 {
 176     NO_SECURITY_MODE                = 0x0,
 177     SYMMETRIC_PAIR_WISE_KEY         = (0x1 << 0),
 178     SYMMETRIC_GROUP_KEY             = (0x1 << 1),
 179     ASYMMETRIC_KEY                  = (0x1 << 2),
 180     SIGNED_ASYMMETRIC_KEY           = (0x1 << 3),
 181     PIN_PASSWORD                    = (0x1 << 4),
 182     ASYMMETRIC_ENCRYPTION_KEY       = (0x1 << 5),
 183 } OSCTBitmask_t;
 184
 185 /**
 186  * @brief   /oic/sec/credtype (Credential Type) data type.
 187  *          Derived from OIC Security Spec /oic/sec/cred; see Spec for details.
 188  *              0:  no security mode
 189  *              1:  symmetric pair-wise key
 190  *              2:  symmetric group key
 191  *              4:  asymmetric key
 192  *              8:  signed asymmetric key (aka certificate)
 193  *              16: PIN /password
 194  */
 195 typedef OSCTBitmask_t OicSecCredType_t;
 196
 197 typedef struct OicSecDoxm OicSecDoxm_t;
 198
 199 typedef enum OicSecDpm
 200 {
 201     NORMAL                          = 0x0,
 202     RESET                           = (0x1 << 0),
 203     TAKE_OWNER                      = (0x1 << 1),
 204     BOOTSTRAP_SERVICE               = (0x1 << 2),
 205     SECURITY_MANAGEMENT_SERVICES    = (0x1 << 3),
 206     PROVISION_CREDENTIALS           = (0x1 << 4),
 207     PROVISION_ACLS                  = (0x1 << 5),
 208     // << 6 THROUGH 15 RESERVED
 209 } OicSecDpm_t;
 210
 211 typedef enum OicSecDpom
 212 {
 213     MULTIPLE_SERVICE_SERVER_DRIVEN  = 0x0,
 214     SINGLE_SERVICE_SERVER_DRIVEN    = 0x1,
 215     MULTIPLE_SERVICE_CLIENT_DRIVEN  = 0x2,
 216     SINGLE_SERVICE_CLIENT_DRIVEN    = 0x3,
 217 } OicSecDpom_t;
 218
 219 typedef enum OicSecSvcType
 220 {
 221     SERVICE_UNKNOWN                 = 0x0,
 222     ACCESS_MGMT_SERVICE             = 0x1,  //urn:oic.sec.ams
 223 } OicSecSvcType_t;
 224
 225
 226 //TODO: Need more clarification on deviceIDFormat field type.
 227 #if 0
 228 typedef enum
 229 {
 230     URN = 0x0
 231 }OicSecDvcIdFrmt_t;
 232 #endif
 233
 234 typedef enum
 235 {
 236     OIC_JUST_WORKS                          = 0x0,
 237     OIC_MODE_SWITCH                         = 0x1,
 238     OIC_RANDOM_DEVICE_PIN                   = 0x2,
 239     OIC_PRE_PROVISIONED_DEVICE_PIN          = 0x3,
 240     OIC_PRE_PROVISION_STRONG_CREDENTIAL     = 0x4,
 241     OIC_OXM_COUNT
 242 }OicSecOxm_t;
 243
 244 typedef struct OicSecJwk OicSecJwk_t;
 245
 246 typedef struct OicSecPstat OicSecPstat_t;
 247
 248 typedef struct OicSecRole OicSecRole_t;
 249
 250 typedef struct OicSecSacl OicSecSacl_t;
 251
 252 typedef struct OicSecSvc OicSecSvc_t;
 253
 254 typedef char *OicUrn_t; //TODO is URN type defined elsewhere?
 255
 256 typedef struct OicUuid OicUuid_t; //TODO is UUID type defined elsewhere?
 257
 258
 259 #ifdef __WITH_X509__
 260 typedef struct OicSecCrl OicSecCrl_t;
 261 #endif /* __WITH_X509__ */
 262
 263 /**
 264  * @brief   /oic/uuid (Universal Unique Identifier) data type.
 265  */
 266 #define UUID_LENGTH 128/8 // 128-bit GUID length
 267 //TODO: Confirm the length and type of ROLEID.
 268 #define ROLEID_LENGTH 128/8 // 128-bit ROLEID length
 269 #define OWNER_PSK_LENGTH_128 128/8 //byte size of 128-bit key size
 270 #define OWNER_PSK_LENGTH_256 256/8 //byte size of 256-bit key size
 271
 272 struct OicUuid
 273 {
 274     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 275     //TODO fill in unless this is defined elsewhere?
 276     uint8_t             id[UUID_LENGTH];
 277 };
 278
 279 /**
 280  * @brief   /oic/sec/jwk (JSON Web Key) data type.
 281  *          See JSON Web Key (JWK)  draft-ietf-jose-json-web-key-41
 282  */
 283 #define JWK_LENGTH 256/8 // 256 bit key length
 284 struct OicSecJwk
 285 {
 286     char                *data;
 287 };
 288
 289 /**
 290  * @brief   /oic/sec/acl (Access Control List) data type.
 291  *          Derived from OIC Security Spec; see Spec for details.
 292  */
 293 struct OicSecAcl
 294 {
 295     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 296     OicUuid_t           subject;        // 0:R:S:Y:uuid TODO: this deviates
 297                                         // from spec and needs to be updated
 298                                         // in spec (where it's a String).
 299     size_t              resourcesLen;   // the number of elts in Resources
 300     char                **resources;    // 1:R:M:Y:String
 301     uint16_t            permission;     // 2:R:S:Y:UINT16
 302     size_t              prdRecrLen;     // the number of elts in Periods
 303     char                **periods;       // 3:R:M*:N:String (<--M*; see Spec)
 304     char                **recurrences;   // 5:R:M:N:String
 305     size_t              ownersLen;      // the number of elts in Owners
 306     OicUuid_t           *owners;        // 8:R:M:Y:oic.uuid
 307     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
 308     // SRM version only; this will change to Svc type for full implementation.
 309     //TODO change Owners type to oic.sec.svc
 310     //OicSecSvc_t         *Owners;        // 6:R:M:Y:oic.sec.svc
 311     OicSecAcl_t         *next;
 312 };
 313
 314 /**
 315  * @brief   /oic/sec/amacl (Access Manager Service Accesss Control List)
 316  *          data type.
 317  *          Derived from OIC Security Spec; see Spec for details.
 318  */
 319 struct OicSecAmacl
 320 {
 321     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 322     size_t              resourcesLen;   // the number of elts in Resources
 323     char                **resources;    // 0:R:M:Y:String
 324     size_t              amssLen;        // the number of elts in Amss
 325     OicUuid_t           *amss;          // 1:R:M:Y:acl
 326     size_t              ownersLen;      // the number of elts in Owners
 327     OicUuid_t           *owners;        // 2:R:M:Y:oic.uuid
 328     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
 329     // SRM version only; this will change to Svc type for full implementation.
 330     //TODO change Owners type to oic.sec.svc
 331     //OicSecSvc_t         *Owners;        // 2:R:M:Y:oic.sec.svc
 332     OicSecAmacl_t         *next;
 333 };
 334
 335 /**
 336  * @brief   /oic/sec/cred (Credential) data type.
 337  *          Derived from OIC Security Spec; see Spec for details.
 338  */
 339 struct OicSecCred
 340 {
 341     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 342     uint16_t            credId;         // 0:R:S:Y:UINT16
 343     OicUuid_t           subject;        // 1:R:S:Y:oic.uuid
 344     //Note: Need further clarification on roleID data type
 345     //NOTE: Need further clarification on roleId datatype.
 346     //size_t              roleIdsLen;     // the number of elts in RoleIds
 347     //OicSecRole_t        *roleIds;       // 2:R:M:N:oic.sec.role
 348     OicSecCredType_t    credType;       // 3:R:S:Y:oic.sec.credtype
 349     OicSecJwk_t         publicData;     // 5:R:S:N:oic.sec.jwk
 350     OicSecJwk_t         privateData;    // 6:R:S:N:oic.sec.jwk
 351     char                *period;        // 7:R:S:N:String
 352     size_t              ownersLen;      // the number of elts in Owners
 353     OicUuid_t           *owners;        // 8:R:M:Y:oic.uuid
 354     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
 355     // SRM version only; this will change to Svc type for full implementation.
 356     //OicSecSvc_t         *Owners;        // 8:R:M:Y:oic.sec.svc
 357     //TODO change Owners type to oic.sec.svc
 358     OicSecCred_t        *next;
 359 };
 360
 361 /**
 362  * @brief   /oic/sec/doxm (Device Owner Transfer Methods) data type
 363  *          Derived from OIC Security Spec; see Spec for details.
 364  */
 365 struct OicSecDoxm
 366 {
 367     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 368     OicUrn_t            *oxmType;       // 0:R:M:N:URN
 369     size_t              oxmTypeLen;     // the number of elts in OxmType
 370     OicSecOxm_t         *oxm;           // 1:R:M:N:UINT16
 371     size_t              oxmLen;         // the number of elts in Oxm
 372     OicSecOxm_t         oxmSel;         // 2:R/W:S:Y:UINT16
 373     OicSecCredType_t    sct;            // 3:R:S:Y:oic.sec.credtype
 374     bool                owned;          // 4:R:S:Y:Boolean
 375     //TODO: Need more clarification on deviceIDFormat field type.
 376     //OicSecDvcIdFrmt_t   deviceIDFormat; // 5:R:S:Y:UINT8
 377     OicUuid_t           deviceID;       // 6:R:S:Y:oic.uuid
 378     OicUuid_t           owner;         // 7:R:S:Y:oic.uuid
 379     // NOTE: we are using UUID for Owner instead of Svc type for mid-April
 380     // SRM version only; this will change to Svc type for full implementation.
 381     //OicSecSvc_t       devOwner;        // 7:R:S:Y:oic.sec.svc
 382     //OicSecSvc_t       rOwner;        // 8:R:S:Y:oic.sec.svc
 383     //TODO change Owner type to oic.sec.svc
 384 };
 385
 386 /**
 387  * @brief   /oic/sec/pstat (Provisioning Status) data type.
 388  * NOTE: this struct is ahead of Spec v0.95 in definition to include Sm.
 389  * TODO: change comment when reconciled to Spec v0.96.
 390  */
 391 struct OicSecPstat
 392 {
 393     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 394     bool                isOp;           // 0:R:S:Y:Boolean
 395     OicSecDpm_t         cm;             // 1:R:S:Y:oic.sec.dpm
 396     OicSecDpm_t         tm;             // 2:RW:S:Y:oic.sec.dpm
 397     OicUuid_t           deviceID;       // 3:R:S:Y:oic.uuid
 398     OicSecDpom_t        om;             // 4:RW:M:Y:oic.sec.dpom
 399     size_t              smLen;          // the number of elts in Sm
 400     OicSecDpom_t        *sm;            // 5:R:M:Y:oic.sec.dpom
 401     uint16_t            commitHash;     // 6:R:S:Y:oic.sec.sha256
 402     //TODO: this is supposed to be a 256-bit uint; temporarily use uint16_t
 403     //TODO: need to decide which 256 bit and 128 bit types to use... boost?
 404 };
 405
 406 /**
 407  * @brief   /oic/sec/role (Role) data type.
 408  *          Derived from OIC Security Spec; see Spec for details.
 409  */
 410 struct OicSecRole
 411 {
 412     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 413     //TODO fill in with Role definition
 414     uint8_t             id[ROLEID_LENGTH];
 415 };
 416
 417 /**
 418  * @brief   /oic/sec/sacl (Signed Access Control List) data type.
 419  *          Derived from OIC Security Spec; see Spec for details.
 420  */
 421 struct OicSecSacl
 422 {
 423     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 424     //TODO fill in from OIC Security Spec
 425 };
 426
 427 /**
 428  * @brief   /oic/sec/svc (Service requiring a secure connection) data type.
 429  *          Derived from OIC Security Spec; see Spec for details.
 430  */
 431 struct OicSecSvc
 432 {
 433     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 434     OicUuid_t               svcdid;                 //0:R:S:Y:oic.uuid
 435     OicSecSvcType_t         svct;                   //1:R:M:Y:OIC Service Type
 436     size_t                  ownersLen;              //2:the number of elts in Owners
 437     OicUuid_t               *owners;                //3:R:M:Y:oic.uuid
 438     OicSecSvc_t             *next;
 439 };
 440
 441 #ifdef __WITH_X509__
 442 struct OicSecCrl
 443 {
 444     uint16_t CrlId;
 445     ByteArray ThisUpdate;
 446     ByteArray CrlData;
 447 };
 448 #endif /* __WITH_X509__ */
 449
 450 #ifdef __cplusplus
 451 }
 452 #endif
 453
 454 #endif //OC_SECURITY_RESOURCE_TYPES_H