User Tools

Site Tools


acl_guideline

IoTivity ACL Guideline

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 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 resource (/oic/sec/acl) has the following structure

Creating an ACE

  • 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
    • Array of resources:
      • For each resource, “href”
      • For each resource, “rt”: resource type
      • For each resource, “if”: interface
    • “permission”: CRUDN bitmask
  • For reference see createAcl() and provisionAcl() methods in:
    • csdk/security/provisioning/sample/provisioningclient.c

Adding 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
  • After receiving a valid POST request, the server performs the following steps for each of the ACE:
    • Check whether a same ACE already exists
    • If not, add the new ACE to ACL

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 }

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.
  • The DELETE request may include ‘subjectuuid’ as a query paramrter. Subsequently, all ACEs with the matching subjectuuid will be deleted.

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 }, where A and C have “subjectuuid”=“uid”.
    • Client sends DELETE request with subjectuuid=uid.
    • Then the resulting ACL looks like this: { B }

Modifying ACL

  • 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
    • Modify the list internally by removing unwanted ACEs and adding new ACEs
    • Send a DELETE request to ACL to remove all ACEs
    • Send a POST request to ACL with the list of ACEs modified in Step 2
  • After Step 3, because there is no ACE, the only device that can modify ACL is the resource owner

Example:

  • Server has the following ACL: { A, B, C }. Client (resource owner) wants the list to be { B, D, E }
  • Client first retrieves ACL via a GET request
  • Client internally prepares the list { B, D, E }
  • Client deletes all ACEs via a DELETE request
  • Client updates ACL via a POST request with { B, D, E }
  • Server has the following ACL: { B, D, E }

Secure vs Non-secure Resources

  • A resource can either be secure or non-secure. This is determined when a resource is created:
  OCStackResult OCCreateResource(OCResourceHandle *handle,
		const char *resourceTypeName,
		const char *resourceInterfaceName,
		const char *uri,
		OCEntityHandler entityHandler,
		void* callbackParam,
		uint8_t resourceProperties)
 
  • 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 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
  • Having an ACE with “subjectuuid”: “*” for a secure resource means any authenticated client can access the resource via CoAPS connection
  • ACE subjectuuid: Secure resource

  • ACE subjectuuid: Non-secure resource

Default ACE

  • There are currently two default ACEs that are pre-installed prior to OwnershipTransfer

  • 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

  • During a successful ownership transfer, the device owner adds an ACE that allows it full access to all resources of the owned device

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
{{::acl_multiple_owner.png?direct}}

Policy Engine Flow Chart

acl_guideline.txt · Last modified: 2017/12/04 18:37 by Phil Coval