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 //TODO: Need more clarification on deviceIDFormat field type.
 212 #if 0
 213 typedef enum
 214 {
 215     URN = 0x0
 216 }OicSecDvcIdFrmt_t;
 217 #endif
 218
 219 typedef enum
 220 {
 221     OIC_JUST_WORKS                          = 0x0,
 222     OIC_MODE_SWITCH                         = 0x1,
 223     OIC_RANDOM_DEVICE_PIN                   = 0x2,
 224     OIC_PRE_PROVISIONED_DEVICE_PIN          = 0x3,
 225     OIC_PRE_PROVISION_STRONG_CREDENTIAL     = 0x4
 226 }OicSecOxm_t;
 227
 228 typedef struct OicSecJwk OicSecJwk_t;
 229
 230 typedef struct OicSecPstat OicSecPstat_t;
 231
 232 typedef struct OicSecRole OicSecRole_t;
 233
 234 typedef struct OicSecSacl OicSecSacl_t;
 235
 236 typedef struct OicSecSvc OicSecSvc_t;
 237
 238 typedef char *OicUrn_t; //TODO is URN type defined elsewhere?
 239
 240 typedef struct OicUuid OicUuid_t; //TODO is UUID type defined elsewhere?
 241
 242
 243 /**
 244  * @brief   /oic/uuid (Universal Unique Identifier) data type.
 245  */
 246 #define UUID_LENGTH 128/8 // 128-bit GUID length
 247 //TODO: Confirm the length and type of ROLEID.
 248 #define ROLEID_LENGTH 128/8 // 128-bit ROLEID length
 249 #define OWNER_PSK_LENGTH_128 128/8 //byte size of 128-bit key size
 250 #define OWNER_PSK_LENGTH_256 256/8 //byte size of 256-bit key size
 251
 252 struct OicUuid
 253 {
 254     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 255     //TODO fill in unless this is defined elsewhere?
 256     uint8_t             id[UUID_LENGTH];
 257 };
 258
 259 /**
 260  * @brief   /oic/sec/jwk (JSON Web Key) data type.
 261  *          See JSON Web Key (JWK)  draft-ietf-jose-json-web-key-41
 262  */
 263 #define JWK_LENGTH 256/8 // 256 bit key length
 264 struct OicSecJwk
 265 {
 266     char                *data;
 267 };
 268
 269 /**
 270  * @brief   /oic/sec/acl (Access Control List) data type.
 271  *          Derived from OIC Security Spec; see Spec for details.
 272  */
 273 struct OicSecAcl
 274 {
 275     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 276     OicUuid_t           subject;        // 0:R:S:Y:uuid TODO: this deviates
 277                                         // from spec and needs to be updated
 278                                         // in spec (where it's a String).
 279     size_t              resourcesLen;   // the number of elts in Resources
 280     char                **resources;    // 1:R:M:Y:String
 281     uint16_t            permission;     // 2:R:S:Y:UINT16
 282     size_t              periodsLen;     // the number of elts in Periods
 283     char                **periods;      // 3:R:M*:N:String (<--M*; see Spec)
 284     char                *recurrences;   // 5:R:M:N:String
 285     size_t              ownersLen;      // the number of elts in Owners
 286     OicUuid_t           *owners;        // 8:R:M:Y:oic.uuid
 287     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
 288     // SRM version only; this will change to Svc type for full implementation.
 289     //TODO change Owners type to oic.sec.svc
 290     //OicSecSvc_t         *Owners;        // 6:R:M:Y:oic.sec.svc
 291     OicSecAcl_t         *next;
 292 };
 293
 294 /**
 295  * @brief   /oic/sec/amacl (Access Manager Service Accesss Control List)
 296  *          data type.
 297  *          Derived from OIC Security Spec; see Spec for details.
 298  */
 299 struct OicSecAmacl
 300 {
 301     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 302     size_t              resourcesLen;   // the number of elts in Resources
 303     char                **resources;    // 0:R:M:Y:String
 304     size_t              amssLen;        // the number of elts in Amss
 305     OicSecSvc_t         *amss;          // 1:R:M:Y:acl
 306     size_t              ownersLen;      // the number of elts in Owners
 307     OicUuid_t           *owners;        // 2:R:M:Y:oic.uuid
 308     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
 309     // SRM version only; this will change to Svc type for full implementation.
 310     //TODO change Owners type to oic.sec.svc
 311     //OicSecSvc_t         *Owners;        // 2:R:M:Y:oic.sec.svc
 312 };
 313
 314 /**
 315  * @brief   /oic/sec/cred (Credential) data type.
 316  *          Derived from OIC Security Spec; see Spec for details.
 317  */
 318 struct OicSecCred
 319 {
 320     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 321     uint16_t            credId;         // 0:R:S:Y:UINT16
 322     OicUuid_t           subject;        // 1:R:S:Y:oic.uuid
 323     //Note: Need further clarification on roleID data type
 324     //NOTE: Need further clarification on roleId datatype.
 325     //size_t              roleIdsLen;     // the number of elts in RoleIds
 326     //OicSecRole_t        *roleIds;       // 2:R:M:N:oic.sec.role
 327     OicSecCredType_t    credType;       // 3:R:S:Y:oic.sec.credtype
 328     OicSecJwk_t         publicData;     // 5:R:S:N:oic.sec.jwk
 329     OicSecJwk_t         privateData;    // 6:R:S:N:oic.sec.jwk
 330     char                *period;        // 7:R:S:N:String
 331     size_t              ownersLen;      // the number of elts in Owners
 332     OicUuid_t           *owners;        // 8:R:M:Y:oic.uuid
 333     // NOTE: we are using UUID for Owners instead of Svc type for mid-April
 334     // SRM version only; this will change to Svc type for full implementation.
 335     //OicSecSvc_t         *Owners;        // 8:R:M:Y:oic.sec.svc
 336     //TODO change Owners type to oic.sec.svc
 337     OicSecCred_t        *next;
 338 };
 339
 340 /**
 341  * @brief   /oic/sec/doxm (Device Owner Transfer Methods) data type
 342  *          Derived from OIC Security Spec; see Spec for details.
 343  */
 344 struct OicSecDoxm
 345 {
 346     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 347     OicUrn_t            *oxmType;       // 0:R:M:N:URN
 348     size_t              oxmTypeLen;     // the number of elts in OxmType
 349     OicSecOxm_t         *oxm;           // 1:R:M:N:UINT16
 350     size_t              oxmLen;         // the number of elts in Oxm
 351     OicSecOxm_t         oxmSel;         // 2:R/W:S:Y:UINT16
 352     bool                owned;          // 3:R:S:Y:Boolean
 353     //TODO: Need more clarification on deviceIDFormat field type.
 354     //OicSecDvcIdFrmt_t   deviceIDFormat; // 4:R:S:Y:UINT8
 355     OicUuid_t           deviceID;       // 5:R:S:Y:oic.uuid
 356     OicUuid_t           owner;         // 6:R:S:Y:oic.uuid
 357     // NOTE: we are using UUID for Owner instead of Svc type for mid-April
 358     // SRM version only; this will change to Svc type for full implementation.
 359     //OicSecSvc_t       Owner;        // 5:R:S:Y:oic.sec.svc
 360     //TODO change Owner type to oic.sec.svc
 361 };
 362
 363 /**
 364  * @brief   /oic/sec/pstat (Provisioning Status) data type.
 365  * NOTE: this struct is ahead of Spec v0.95 in definition to include Sm.
 366  * TODO: change comment when reconciled to Spec v0.96.
 367  */
 368 struct OicSecPstat
 369 {
 370     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 371     bool                isOp;           // 0:R:S:Y:Boolean
 372     OicSecDpm_t         cm;             // 1:R:S:Y:oic.sec.dpm
 373     OicSecDpm_t         tm;             // 2:RW:S:Y:oic.sec.dpm
 374     OicUuid_t           deviceID;       // 3:R:S:Y:oic.uuid
 375     OicSecDpom_t        om;             // 4:RW:M:Y:oic.sec.dpom
 376     size_t              smLen;          // the number of elts in Sm
 377     OicSecDpom_t        *sm;            // 5:R:M:Y:oic.sec.dpom
 378     uint16_t            commitHash;     // 6:R:S:Y:oic.sec.sha256
 379     //TODO: this is supposed to be a 256-bit uint; temporarily use uint16_t
 380     //TODO: need to decide which 256 bit and 128 bit types to use... boost?
 381 };
 382
 383 /**
 384  * @brief   /oic/sec/role (Role) data type.
 385  *          Derived from OIC Security Spec; see Spec for details.
 386  */
 387 struct OicSecRole
 388 {
 389     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 390     //TODO fill in with Role definition
 391     uint8_t             id[ROLEID_LENGTH];
 392 };
 393
 394 /**
 395  * @brief   /oic/sec/sacl (Signed Access Control List) data type.
 396  *          Derived from OIC Security Spec; see Spec for details.
 397  */
 398 struct OicSecSacl
 399 {
 400     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 401     //TODO fill in from OIC Security Spec
 402 };
 403
 404 /**
 405  * @brief   /oic/sec/svc (Service requiring a secure connection) data type.
 406  *          Derived from OIC Security Spec; see Spec for details.
 407  */
 408 struct OicSecSvc
 409 {
 410     // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
 411     //TODO fill in from OIC Security Spec
 412 };
 413
 414 #ifdef __cplusplus
 415 }
 416 #endif
 417
 418 #endif //OC_SECURITY_RESOURCE_TYPES_H