User Tools

Site Tools


acl_guideline

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

acl_guideline [2017/02/16 09:33]
saurabh sharma created
acl_guideline [2017/12/04 18:37] (current)
Phil Coval
Line 1: Line 1:
 ===== IoTivity ACL Guideline ===== ===== IoTivity ACL Guideline =====
 +
 ==== ACL & ACE ==== ==== ACL & ACE ====
-  ​* Each resource instance is required to have an associated access control policy. This means, each device acting as resource server, needs to have an ACL(Access Control List) for each resource it is protecting. If access control is under subject-based,​ then there needs to be an ACE(Acess Control Element) for each subject (identity of an client) that needs to access a subject-based controlled resource. However, ACLs for unknown or anonymous (unauthenticated) subject may be possible and subject to default permissions defined for the resource.(in detail, for the next slides of ACE settings) + 
-  * Details of the format for ACL is defined in OCF security spec. Each ACL is composed of one or more ACEs. It is assumed that each OIC device has at least one access control ​resource. Absence of an ACL on an device is an indication that ACL provisioning(need to be configured) may be required and access to the corresponding resource may be denied until the appropriate ACL is provisioned+  ​* Each [[resource]] instance is required to have an associated access control policy. This means, each device acting as resource server, needs to have an [[ACL]] (Access Control List) for each resource it is protecting. If access control is under subject-based,​ then there need  ​to be an ACE (Acess Control Element) for each subject (identity of an client) that needs to access a subject-based controlled resource. However, ACLs for unknown or anonymous (unauthenticated) subject may be possible and subject to default permissions defined for the resource (in detail, for the next slides of ACE settings). 
 +  * Details of the format for ACL is defined in OCF [[security]] spec. Each ACL is composed of one or more ACEs. It is assumed that each OIC device has at least one [[AccessControl]] ​resource. Absence of an ACL on an device is an indication that ACL [[provisioning]] (need to be configured) may be required and access to the corresponding resource may be denied until the appropriate ACL is provisioned
  
 ==== ACL structure ==== ==== ACL structure ====
 +
   * ACL resource (/​oic/​sec/​acl) has the following structure   * ACL resource (/​oic/​sec/​acl) has the following structure
   {{::​acl_structure.png?​direct}}   {{::​acl_structure.png?​direct}}
 +
  
 ==== Creating an ACE ==== ==== Creating an ACE ====
 +
 {{::​acl_create.png?​direct}} {{::​acl_create.png?​direct}}
-  ​* To create an ACE, one must create and fill in OicSecAcl_t. The following information are needed+ 
 +  ​* To create an ACE, one must create and fill in OicSecAcl_t. The following information are needed:
     * “subjectuuid”:​ UUID of the device to which the ACE applies     * “subjectuuid”:​ UUID of the device to which the ACE applies
-    * Number ​of resources +    * Array of resources: 
-    * For each resource, “href” +       ​* For each resource, “href” 
-    * For each resource, “rt”: resource type +       ​* For each resource, “rt”: resource type 
-    * For each resource, “if”: interface +       ​* For each resource, “if”: interface 
-    * “permission”:​ CRUDN bitmask +    * “permission”: ​[[CRUDN]] bitmask 
-  * See createAcl() and provisionAcl() methods in csdk/​security/​provisioning/​sample/​provisioningclient.c ​for reference+  * For reference see createAcl() and provisionAcl() methods in
 +    * csdk/​security/​provisioning/​sample/​provisioningclient.c 
  
 ==== Adding ACEs ==== ==== Adding ACEs ====
-  ​* An authenticated client with UPDATE permission may send POST request to ‘/​oic/​sec/​acl’ resource with a list of ACEs+ 
 +  ​* An authenticated client with UPDATE ​[[permission]] may send POST request to ‘/​oic/​sec/​acl’ resource with a list of ACEs
   * POST requests are interpreted as APPEND   * POST requests are interpreted as APPEND
   * After receiving a valid POST request, the server performs the following steps for each of the ACE:   * After receiving a valid POST request, the server performs the following steps for each of the ACE:
     * Check whether a same ACE already exists     * Check whether a same ACE already exists
-    * If not, add the new ACE to ACL+    * If not, add the new ACE to [[ACL]]
   Example:   Example:
-    * Server has the following ACL: { A, B, C }. Client sends POST request with payload { A, B’, C’, D }, where B’ has the same resources as B but with a different ‘subjectuuid’,​ and C’ has the same resources as C but with a different ‘permission’. Then the resulting ACL looks like this: { A, B, C, B’, C’, D }+    * Server has the following ACL: { A, B, C }. 
 +    * Client sends POST request with payload { A, B’, C’, D }, where B’ has the same resources as B but with a different ‘subjectuuid’,​ and C’ has the same resources as C but with a different ‘permission’. ​ 
 +    * Then the resulting ACL looks like this: { A, B, C, B’, C’, D }
  
  
 ==== Deleting ACEs ==== ==== Deleting ACEs ====
-  ​* An authenticated client with DELETE permission may send DELETE request to ‘/​oic/​sec/​acl’ resource + 
-  * If there is no query parameter, all ACEs are deleted. The ‘rowneruuid’ information remains the same +  ​* An authenticated client with DELETE ​[[permission]] may send DELETE request to ‘/​oic/​sec/​acl’ resource 
-  * The DELETE request may include ‘subjectuuid’ as a query paramter. Subsequently,​ all ACEs with the matching subjectuuid will be deleted+  * If there is no query parameter, all ACEs are deleted. The ‘rowneruuid’ information remains the same. 
 +  * The DELETE request may include ‘subjectuuid’ as a query paramrter. Subsequently,​ all ACEs with the matching subjectuuid will be deleted.
   Example:   Example:
-    * Server has the following ACL: { A, B, C }. Client sends DELETE request with no query paramter. Then the resulting ACL looks like this: { } +    * Server has the following ACL: { A, B, C }. 
-    * Server has the following ACL: { A, B, C }, where A and C have “subjectuuid”=“uid”. Client sends DELETE request with subjectuuid=uid. Then the resulting ACL looks like this: { B }+      * Client sends DELETE request with no query paramter. 
 +      * Then the resulting ACL looks like this: { } 
 +    * Server has the following ACL: { A, B, C }, where A and C have “subjectuuid”=“uid”. 
 +      * Client sends DELETE request with subjectuuid=uid. 
 +      * Then the resulting ACL looks like this: { B }
  
  
 ==== Modifying ACL ==== ==== Modifying ACL ====
 +
   * The resource owner of the ACL may modify ACL by the following mechanism   * The resource owner of the ACL may modify ACL by the following mechanism
     * Send a GET request to ACL to retrieve the list of all ACEs     * Send a GET request to ACL to retrieve the list of all ACEs
Line 55: Line 73:
  
 ==== Secure vs Non-secure Resources ==== ==== Secure vs Non-secure Resources ====
 +
   * A resource can either be secure or non-secure. This is determined when a resource is created:   * A resource can either be secure or non-secure. This is determined when a resource is created:
-  <code text> OCStackResult OCCreateResource(OCResourceHandle *handle,+  <code text> 
 +  ​OCStackResult OCCreateResource(OCResourceHandle *handle,
  const char *resourceTypeName,​  const char *resourceTypeName,​
  const char *resourceInterfaceName,​  const char *resourceInterfaceName,​
Line 65: Line 85:
   </​code>​   </​code>​
   * If OC_SECURE is included in resourceProperties,​ the created resource will be a secure resource   * If OC_SECURE is included in resourceProperties,​ the created resource will be a secure resource
-  * A secure resource can only be accessed via CoAPS and CoAP requests will be denied +  * A secure resource can only be accessed via CoAPS (and CoAP requests will be denied) 
-  * A non-secure resource can be accessed via either CoAPS or CoAP+  * A non-secure resource can be accessed via either CoAPS or [[CoAP]]
   * Because CoAP access means the requester is unauthenticated,​ there is no subjectuuid identifying the requester. Therefore, in order to allow CoAP access to a certain non-secure resource, there must be an ACE with “subjectuuid”:​ “*” to allow anonymous access   * Because CoAP access means the requester is unauthenticated,​ there is no subjectuuid identifying the requester. Therefore, in order to allow CoAP access to a certain non-secure resource, there must be an ACE with “subjectuuid”:​ “*” to allow anonymous access
   * Having an ACE with “subjectuuid”:​ “*” for a secure resource means any authenticated client can access the resource via CoAPS connection   * Having an ACE with “subjectuuid”:​ “*” for a secure resource means any authenticated client can access the resource via CoAPS connection
Line 76: Line 96:
  
 ==== Default ACE ==== ==== Default ACE ====
-  ​* There are currently two default ACEs that are pre-installed prior to Ownership Transfer+ 
 +  ​* There are currently two default ACEs that are pre-installed prior to [[OwnershipTransfer]]
   {{::​acl_default.png?​direct}}   {{::​acl_default.png?​direct}}
   * After a successful ownership transfer, the default SVR ACE is internally replaced by a Read-only ACE. DO NOT add additional resources to Default ACEs   * After a successful ownership transfer, the default SVR ACE is internally replaced by a Read-only ACE. DO NOT add additional resources to Default ACEs
Line 85: Line 106:
  
 ==== Multiple Owner ACE ==== ==== Multiple Owner ACE ====
 +
   * A subowner may POST ACEs to the owned device after a successful multiple ownership transfer. The resulting ACE looks similar to the typical ACE but has an additional property of “eowneruuid” (UUID of the entry owner), which is set to the UUID of the subowner   * A subowner may POST ACEs to the owned device after a successful multiple ownership transfer. The resulting ACE looks similar to the typical ACE but has an additional property of “eowneruuid” (UUID of the entry owner), which is set to the UUID of the subowner
 +
   {{::​acl_multiple_owner.png?​direct}}   {{::​acl_multiple_owner.png?​direct}}
  
  
 ==== Policy Engine Flow Chart ==== ==== Policy Engine Flow Chart ====
 +
 {{::​acl_policy_eng.png?​direct}} {{::​acl_policy_eng.png?​direct}}
 +
 +
 +=== Related ===
 +
 +  * [[security]],​ [[acl]]
 +
  
acl_guideline.txt · Last modified: 2017/12/04 18:37 by Phil Coval