1 //******************************************************************
3 // Copyright 2015 Intel Mobile Communications GmbH All Rights Reserved.
5 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
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
11 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
22 * Data type definitions for all oic.sec.* types defined in the
23 * OIC Security Specification.
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.
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).
37 * TODO reconcile against latest OIC Security Spec to ensure all fields correct.
38 * (Last checked against v0.95)
41 #ifndef OC_SECURITY_RESOURCE_TYPES_H
42 #define OC_SECURITY_RESOURCE_TYPES_H
44 #include <stdint.h> // for uint8_t typedef
52 * @brief Values used to create bit-maskable enums for single-value
53 * response with embedded code.
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)
70 * Access policy in least significant bits (from Spec):
72 * 2nd lsb: R (Read, Observe, Discover)
73 * 3rd lsb: U (Write, Update)
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 | \
89 * @brief Response type for all Action requests from CA layer;
90 * may include a reason code.
92 * To extract codes use GetReasonCode function on SRMAccessResponse:
94 * SRMAccessResponse_t response = SRMRequestHandler(obj, info);
95 * if(SRM_TRUE == IsAccessGranted(response)) {
96 * SRMAccessResponseReasonCode_t reason = GetReasonCode(response);
98 * case INSUFFICIENT_PERMISSION:
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;
120 * Reason code for SRMAccessResponse.
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;
131 * Extract Reason Code from Access Response.
133 static inline SRMAccessResponseReasonCode_t GetReasonCode(
134 SRMAccessResponse_t response)
136 SRMAccessResponseReasonCode_t reason =
137 (SRMAccessResponseReasonCode_t)(response & REASON_MASK_DEF);
142 * Returns 'true' iff request should be passed on to RI layer.
144 static inline bool IsAccessGranted(SRMAccessResponse_t response)
146 if(ACCESS_GRANTED == (response & ACCESS_GRANTED))
156 typedef struct OicSecAcl OicSecAcl_t;
158 typedef struct OicSecAmacl OicSecAmacl_t;
160 typedef struct OicSecCred OicSecCred_t;
163 * @brief /oic/sec/credtype (Credential Type) data type.
164 * Derived from OIC Security Spec /oic/sec/cred; see Spec for details.
165 * 0: no security mode
166 * 1: symmetric pair-wise key
167 * 2: symmetric group key
169 * 8: signed asymmetric key (aka certificate)
172 typedef uint16_t OicSecCredType_t;
175 * Aid for assigning/testing vals with OicSecCredType_t.
177 * OicSecCredType_t ct = PIN_PASSWORD | ASYMMETRIC_KEY;
178 * if((ct & PIN_PASSWORD) == PIN_PASSWORD)
180 * // ct contains PIN_PASSWORD flag.
183 typedef enum OSCTBitmask
185 NO_SECURITY_MODE = 0x0,
186 SYMMETRIC_PAIR_WISE_KEY = (0x1 << 0),
187 SYMMETRIC_GROUP_KEY = (0x1 << 1),
188 ASYMMETRIC_KEY = (0x1 << 2),
189 SIGNED_ASYMMETRIC_KEY = (0x1 << 3),
190 PIN_PASSWORD = (0x1 << 4),
193 typedef struct OicSecDoxm OicSecDoxm_t;
195 typedef enum OicSecDpm
199 TAKE_OWNER = (0x1 << 1),
200 BOOTSTRAP_SERVICE = (0x1 << 2),
201 SECURITY_MANAGEMENT_SERVICES = (0x1 << 3),
202 PROVISION_CREDENTIALS = (0x1 << 4),
203 PROVISION_ACLS = (0x1 << 5),
204 // << 6 THROUGH 15 RESERVED
207 typedef enum OicSecDpom
209 MULTIPLE_SERVICE_SERVER_DRIVEN = 0x0,
210 SINGLE_SERVICE_SERVER_DRIVEN = 0x1,
211 MULTIPLE_SERVICE_CLIENT_DRIVEN = 0x2,
212 SINGLE_SERVICE_CLIENT_DRIVEN = 0x3,
215 typedef enum OicSecSvcType
217 SERVICE_UNKNOWN = 0x0,
218 ACCESS_MGMT_SERVICE = 0x1, //urn:oic.sec.ams
222 //TODO: Need more clarification on deviceIDFormat field type.
232 OIC_JUST_WORKS = 0x0,
233 OIC_MODE_SWITCH = 0x1,
234 OIC_RANDOM_DEVICE_PIN = 0x2,
235 OIC_PRE_PROVISIONED_DEVICE_PIN = 0x3,
236 OIC_PRE_PROVISION_STRONG_CREDENTIAL = 0x4,
240 typedef struct OicSecJwk OicSecJwk_t;
242 typedef struct OicSecPstat OicSecPstat_t;
244 typedef struct OicSecRole OicSecRole_t;
246 typedef struct OicSecSacl OicSecSacl_t;
248 typedef struct OicSecSvc OicSecSvc_t;
250 typedef char *OicUrn_t; //TODO is URN type defined elsewhere?
252 typedef struct OicUuid OicUuid_t; //TODO is UUID type defined elsewhere?
256 * @brief /oic/uuid (Universal Unique Identifier) data type.
258 #define UUID_LENGTH 128/8 // 128-bit GUID length
259 //TODO: Confirm the length and type of ROLEID.
260 #define ROLEID_LENGTH 128/8 // 128-bit ROLEID length
261 #define OWNER_PSK_LENGTH_128 128/8 //byte size of 128-bit key size
262 #define OWNER_PSK_LENGTH_256 256/8 //byte size of 256-bit key size
266 // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
267 //TODO fill in unless this is defined elsewhere?
268 uint8_t id[UUID_LENGTH];
272 * @brief /oic/sec/jwk (JSON Web Key) data type.
273 * See JSON Web Key (JWK) draft-ietf-jose-json-web-key-41
275 #define JWK_LENGTH 256/8 // 256 bit key length
282 * @brief /oic/sec/acl (Access Control List) data type.
283 * Derived from OIC Security Spec; see Spec for details.
287 // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
288 OicUuid_t subject; // 0:R:S:Y:uuid TODO: this deviates
289 // from spec and needs to be updated
290 // in spec (where it's a String).
291 size_t resourcesLen; // the number of elts in Resources
292 char **resources; // 1:R:M:Y:String
293 uint16_t permission; // 2:R:S:Y:UINT16
294 size_t prdRecrLen; // the number of elts in Periods
295 char **periods; // 3:R:M*:N:String (<--M*; see Spec)
296 char **recurrences; // 5:R:M:N:String
297 size_t ownersLen; // the number of elts in Owners
298 OicUuid_t *owners; // 8:R:M:Y:oic.uuid
299 // NOTE: we are using UUID for Owners instead of Svc type for mid-April
300 // SRM version only; this will change to Svc type for full implementation.
301 //TODO change Owners type to oic.sec.svc
302 //OicSecSvc_t *Owners; // 6:R:M:Y:oic.sec.svc
307 * @brief /oic/sec/amacl (Access Manager Service Accesss Control List)
309 * Derived from OIC Security Spec; see Spec for details.
313 // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
314 size_t resourcesLen; // the number of elts in Resources
315 char **resources; // 0:R:M:Y:String
316 size_t amssLen; // the number of elts in Amss
317 OicUuid_t *amss; // 1:R:M:Y:acl
318 size_t ownersLen; // the number of elts in Owners
319 OicUuid_t *owners; // 2:R:M:Y:oic.uuid
320 // NOTE: we are using UUID for Owners instead of Svc type for mid-April
321 // SRM version only; this will change to Svc type for full implementation.
322 //TODO change Owners type to oic.sec.svc
323 //OicSecSvc_t *Owners; // 2:R:M:Y:oic.sec.svc
328 * @brief /oic/sec/cred (Credential) data type.
329 * Derived from OIC Security Spec; see Spec for details.
333 // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
334 uint16_t credId; // 0:R:S:Y:UINT16
335 OicUuid_t subject; // 1:R:S:Y:oic.uuid
336 //Note: Need further clarification on roleID data type
337 //NOTE: Need further clarification on roleId datatype.
338 //size_t roleIdsLen; // the number of elts in RoleIds
339 //OicSecRole_t *roleIds; // 2:R:M:N:oic.sec.role
340 OicSecCredType_t credType; // 3:R:S:Y:oic.sec.credtype
341 OicSecJwk_t publicData; // 5:R:S:N:oic.sec.jwk
342 OicSecJwk_t privateData; // 6:R:S:N:oic.sec.jwk
343 char *period; // 7:R:S:N:String
344 size_t ownersLen; // the number of elts in Owners
345 OicUuid_t *owners; // 8:R:M:Y:oic.uuid
346 // NOTE: we are using UUID for Owners instead of Svc type for mid-April
347 // SRM version only; this will change to Svc type for full implementation.
348 //OicSecSvc_t *Owners; // 8:R:M:Y:oic.sec.svc
349 //TODO change Owners type to oic.sec.svc
354 * @brief /oic/sec/doxm (Device Owner Transfer Methods) data type
355 * Derived from OIC Security Spec; see Spec for details.
359 // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
360 OicUrn_t *oxmType; // 0:R:M:N:URN
361 size_t oxmTypeLen; // the number of elts in OxmType
362 OicSecOxm_t *oxm; // 1:R:M:N:UINT16
363 size_t oxmLen; // the number of elts in Oxm
364 OicSecOxm_t oxmSel; // 2:R/W:S:Y:UINT16
365 bool owned; // 3:R:S:Y:Boolean
366 //TODO: Need more clarification on deviceIDFormat field type.
367 //OicSecDvcIdFrmt_t deviceIDFormat; // 4:R:S:Y:UINT8
368 OicUuid_t deviceID; // 5:R:S:Y:oic.uuid
369 OicUuid_t owner; // 6:R:S:Y:oic.uuid
370 // NOTE: we are using UUID for Owner instead of Svc type for mid-April
371 // SRM version only; this will change to Svc type for full implementation.
372 //OicSecSvc_t Owner; // 5:R:S:Y:oic.sec.svc
373 //TODO change Owner type to oic.sec.svc
377 * @brief /oic/sec/pstat (Provisioning Status) data type.
378 * NOTE: this struct is ahead of Spec v0.95 in definition to include Sm.
379 * TODO: change comment when reconciled to Spec v0.96.
383 // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
384 bool isOp; // 0:R:S:Y:Boolean
385 OicSecDpm_t cm; // 1:R:S:Y:oic.sec.dpm
386 OicSecDpm_t tm; // 2:RW:S:Y:oic.sec.dpm
387 OicUuid_t deviceID; // 3:R:S:Y:oic.uuid
388 OicSecDpom_t om; // 4:RW:M:Y:oic.sec.dpom
389 size_t smLen; // the number of elts in Sm
390 OicSecDpom_t *sm; // 5:R:M:Y:oic.sec.dpom
391 uint16_t commitHash; // 6:R:S:Y:oic.sec.sha256
392 //TODO: this is supposed to be a 256-bit uint; temporarily use uint16_t
393 //TODO: need to decide which 256 bit and 128 bit types to use... boost?
397 * @brief /oic/sec/role (Role) data type.
398 * Derived from OIC Security Spec; see Spec for details.
402 // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
403 //TODO fill in with Role definition
404 uint8_t id[ROLEID_LENGTH];
408 * @brief /oic/sec/sacl (Signed Access Control List) data type.
409 * Derived from OIC Security Spec; see Spec for details.
413 // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
414 //TODO fill in from OIC Security Spec
418 * @brief /oic/sec/svc (Service requiring a secure connection) data type.
419 * Derived from OIC Security Spec; see Spec for details.
423 // <Attribute ID>:<Read/Write>:<Multiple/Single>:<Mandatory?>:<Type>
424 OicUuid_t svcdid; //0:R:S:Y:oic.uuid
425 OicSecSvcType_t svct; //1:R:M:Y:OIC Service Type
426 size_t ownersLen; //2:the number of elts in Owners
427 OicUuid_t *owners; //3:R:M:Y:oic.uuid
435 #endif //OC_SECURITY_RESOURCE_TYPES_H