7.6 Secure Connection Establishment
7.6.1 <secureConnection> resource
Secure Environments shall provide a service to AEs or CSEs to establish a secure connection to a dedicated communication partner. The <secureConnection > resource shall represent the services offered by the Secure Environment to enable the establishment of a secure connection to a communication partner. The services include the following:
- generation of key material within the secure environment that can be used for the establishment of a secure connection by the requesting entity (creator) outside of the secure environment;
- acting as secure connection endpoint and sending the data provided by the requesting entity (creator) from within the secure environment with the key material generated and kept inside the secure environment.
The <secureConnection> resource shall contain the child resources specified in table 7.6.1-1.
Table 7.6.1-1: Child resources of <_secureConnection> resource
| Child Resources of <secureConnection> | Child Resource Type | Multiplicity | Description |
|---|---|---|---|
| connectionInstance | <connectionInstance> | 0..n | See clause 7.6.3 |
| generateKey | <generateKey> | 0..1 | See clause 7.6.7 |
Attributes in <secureConnection> are shown in table 7.6.1-2.
Table 7.6.1-2: Attributes of <secureConnection> resource
| Attributes of <secureConnection> | Multiplicity | RW/ RO/ WO |
Description |
|---|---|---|---|
| resourceType | 1 | RO | Defines the resource type. |
| resourceID | 1 | RO | Defines an identifier for the resource. This attribute shall be provided by the creator. The creator shall assign a resourceID which is unique within its context. |
| resourceName | 1 | WO | This attribute is the name for the resource that is used for 'hierarchical addressing method' to represent the parent-child relationships of resources. |
| parentID | 1 | RO | This attribute is the resourceID of the parent of this resource. |
| expirationTime | 1 | RW | Time/date after which the resource will be deleted by the Hosting CSE. |
| accessControlPolicyIDs | 0..1 (L) | RW | Is used to control access to the resource. If no accessControlPolicyIDs are provided at the time of creation, the accessControlPolicyIDs of the parent resource is linked to this attribute. |
| creationTime | 1 | RO | Time/date of creation of the resource. The creationTime is set by the CSE hosting the SE when the resource is created. |
| lastModifiedTime | 1 | RO | Last modification time/date of the resource. This attribute is mandatory. The lastModifiedTime value is set by the Hosting CSE when the resource is created, and the lastModifiedTime value is updated when the resource is updated. |
| maxNrOfInstances | 0..1 | RO | Maximum number of direct child <connectionInstance> resources in the <secureConnection> resource. |
| currentNrOfInstances | 0..1 | RW | Current number of direct child <connectionInstance > resource in the <secureConnection> resource. It is limited by the maxNrOfInstances . |
| connectionType | 1 | RW | Contains the type of connection that has to be supported. Supported types are: TLS; DTLS; SMS; E2EKey. |
| keyData | 0..1 | WO | Contains the key material. |
| keyInformation | 0..1 | RW | Specifies the additional information required for the key and the ciphersuite, e.g. Certificates, rootkeys, the public part of keyData. |
| cipherSuite | 0..1 | RW | Specifies the ciphersuites that are supported. Supported cipher suites are given in oneM2M TS-0003 [1]. |
Table 7.6.1-3: Data types of <secureConnection> resource specific attributes
| Name. |
Request Optionality | Data type. |
|
|---|---|---|---|
| Create | Update | ||
| maxNrOfInstances | M | NP | xs:nonNegativeInteger |
| currentNrOfInstances | O | O | xs:nonNegativeInteger |
| connectionType | M | NP | senv:connectionTypeID |
| keyData | O | NP | xs:byte |
| keyInformation | O | O | xs:anyType |
| cipherSuite | O | O | dcfg:TLSCiphersuites |
7.6.2 <secureConnection> Resource Procedures
7.6.2.1 CREATE <secureConnection>
This procedure shall be used for creating a <secureConnection> resource.
Table 7.6.2.1-1: <secureConnection> CREATE
| <secure Connection> CREATE request message parameters | |
|---|---|
| Associated Reference Point | Mcs |
| Information in Request message |
All parameters defined in table 8.1.2-3 of oneM2M TS-0001 [2] apply with the specific details for: To: contains M2M-SE-ID or SE hosted AE-ID or CSE-ID Content: The resource content shall provide the information as defined in clause 7.6.1 |
| Processing at Originator before sending Request | According to clause 10.1.1.1 of oneM2M TS-0001 [2] |
| Processing at Receiver | According to clause 10.1.1.1 of oneM2M TS-0001 [2] |
| Information in Response message |
All parameters defined in table 8.1.3-1 of oneM2M TS-0001 [2] apply with the specific details for: Content: Address of the created <cipher> resource, according to clause 10.1.1.1.of oneM2M TS-0001 [2] |
| Processing at Originator after receiving Response | According to clause 10.1.1.1 of oneM2M TS-0001 [2] |
| Exceptions | According to clause 10.1.1.1 of oneM2M TS-0001 [2] |
If <generateKey > is created, the key to be used shall be generated and stored in keyData , in such a case keyInformation shall be filled with the public part of the generated key.
7.6.2.2 RETRIEVE <secureConnection>
This procedure shall be used for retrieving information about the <secureConnection> resource.
Table 7.6.2.2-1: <secureConnection> RETRIEVE
| <secureConnection> RETRIEVE request message parameters | |
|---|---|
| Associated Reference Point | Mcs |
| Information in Request message |
According to clause 10.1.2 of oneM2M TS-0001 [2] with the specific details for: To: contains M2M-SE-ID or SE hosted AE-ID or CSE-ID |
| Processing at Originator before sending Request | According to clause 10.1.2 of oneM2M TS-0001 [2] |
| Processing at Receiver | According to clause 10.1.2 of oneM2M TS-0001 [2] |
| Information in Response message |
All parameters defined in table 8.1.3-1 of oneM2M TS-0001 [2] apply with specific details for: Content: Attributes of the <secureConnection> resources as defined in clause 7.6.1 |
| Processing at Originator after receiving Response | According to clause 10.1.2 of oneM2M TS-0001 [2] |
| Exceptions | According to clause 10.1.2 of oneM2M TS-0001 [2] |
7.6.2.3 UPDATE <secureConnection>
This procedure shall be used for sending payload data via an established secure connection.
Table 7.6.2.3-1: <secureConnection> UPDATE
| <secureConnection> UPDATE request message parameters | |
|---|---|
| Associated Reference Point | Mcs |
| Information in Request message |
All parameters defined in table 8.1.2-3 of oneM2M TS-0001 [2] apply with the specific details for: To: contains M2M-SE-ID or SE hosted AE-ID or CSE-ID Content: attributes of the <cipher> resource which is to be updated as defined in clause 7.5.1 |
| Processing at Originator before sending Request | According to clause 10.1.3 of oneM2M TS-0001 [2] |
| Processing at Receiver | According to clause 10.1.3 of oneM2M TS-0001 [2] |
| Information in Response message | According to clause 10.1.3 of oneM2M TS-0001 [2] |
| Processing at Originator after receiving Response | According to clause 10.1.3 of oneM2M TS-0001 [2] |
| Exceptions | According to clause 10.1.3 of oneM2M TS-0001 [2] |
7.6.2.4 DELETE <secureConnection>
This procedure shall be used for deleting a <secureConnection > resource. Deleting a <secureConnection > resource shall close an established secure connection between the originator (creator) and the destination.
Table 7.6.2.4-1: <secureConnection > DELETE
| <secureConnection> DELETE request message parameters | |
|---|---|
| Associated Reference Point | Mcs |
| Information in Request message |
All parameters defined in table 8.1.2-3 of oneM2M TS-0001 [2] apply with the specific details for: To: contains M2M-SE-ID or SE hosted AE-ID or CSE-ID |
| Processing at Originator before sending Request | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
| Processing at Receiver | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
| Information in Response message | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
| Processing at Originator after receiving Response | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
| Exceptions | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
7.6.3 <connectionInstance> resource
The <connectionInstance> resource represents a data instance in the <secureConnection > resource.
The <connectionInstance> resource inherits the same access control policies of the parent <secureConnection> resource, and does not have its own accessControlPolicyIDs attribute.
The services shall include the following:
- generation of key material within the secure environment that can be used for the establishment of a secure connection by the requesting entity (creator) outside of the secure environment;
- acting as secure connection endpoint and sending the data provided by the requesting entity (creator) from within the secure environment with the key material generated and kept inside the secure environment.
The <connectionInstance> resource shall contain the child resources specified in table 7.6.3-1.
Table 7.6.3-1: Child resources of <connectionInstance> resource
| Child Resources of <connectionInstance> | Child Resource Type | Multiplicity | Description |
|---|---|---|---|
| algorithmSpecificParameter | <algorithmSpecificParameter> | 0..1 | See clause 7.5.1.5 |
| connect | <connect> | 1 | See clause 7.6.5 |
| send | <send> | 1 | See clause 7.6.6 |
Attributes in <connectionInstance> are shown in table 7.6.3-2.
Table 7.6.3-2: Attributes of <connectionInstance> resource
| Attributes of <connectionInstance> | Multiplicity | RW/ RO/ WO |
Description |
|---|---|---|---|
| resourceType | 1 | RO | Defines the resource type. |
| resourceID | 1 | RO | Defines an identifier for the resource. This attribute shall be provided by the creator. The creator shall assign a resourceID which is unique within its context. |
| resourceName | 1 | WO | This attribute is the name for the resource that is used for 'hierarchical addressing method' to represent the parent-child relationships of resources. |
| parentID | 1 | RO | This attribute is the resourceID of the parent of this resource. |
| expirationTime | 1 | RW | Time/date after which the resource will be deleted by the Hosting CSE. |
| accessControlPolicyIDs | 0..1 (L) | RW | Is used to control access to the resource. If no accessControlPolicyIDs are provided at the time of creation, the accessControlPolicyIDs of the parent resource is linked to this attribute. |
| creationTime | 1 | RO | Time/date of creation of the resource. The creationTime is set by the CSE hosting the SE when the resource is created. |
| lastModifiedTime | 1 | RO | Last modification time/date of the resource. This attribute is mandatory. The lastModifiedTime value is set by the Hosting CSE when the resource is created, and the lastModifiedTime value is updated when the resource is updated. |
| destinationURI | 1 | RW | Specifies the end point to which the secure connection shall be established. |
| outgoingPayloadData | 0..1 | RW | Contains the data that has to be sent via the established secure connection. |
| incomingPayloadData | 0..1 | RO | Contains the data received via the established secure connection. |
| negotiatedKey | 0..1 | RO | Contains the negotiated key e.g. the pairwiseE2EKey using TLS Exporter specification (IETF RFC 5705 [6]). |
| negotiatedCipherSuite | 0..1 | RO | Is the cipher suite negotiated between the Secure Environment and the remote entity. |
Table 7.6.3-3: Data types of <connectionInstance> resource specific attributes
| Name |
Request Optionality | Data type |
|
|---|---|---|---|
| Create | Update | ||
| destinationURI | M | O | xs:anyURI |
| outgoingPayloadData | O | O | xs:byte |
| incomingPayloadData | NP | NP | xs:byte |
| negotiatedKey | O | NP | xs:byte |
| negotiatedCipherSuite | O | NP | dcfg:TLSCiphersuites |
7.6.4 <connectionInstance> Resource Procedures
7.6.4.1 CREATE <connectionInstance>
This procedure shall be used for creating a <connectionInstance> resource.
Table 7.6.4.1-1: <connectionInstance> CREATE
| <connectionInstance> CREATE request message parameters | |
|---|---|
| Associated Reference Point | Mcs |
| Information in Request message |
All parameters defined in table 8.1.2-3 of oneM2M TS-0001 [2] apply with the specific details for: To: contains M2M-SE-ID or SE hosted AE-ID or CSE-ID Content: The resource content shall provide the information as defined in clause 7.6.3 |
| Processing at Originator before sending Request | According to clause 10.1.1.1 of oneM2M TS-0001 [2] |
| Processing at Receiver | According to clause 10.1.1.1 of oneM2M TS-0001 [2] |
| Information in Response message |
All parameters defined in table 8.1.3-1 of oneM2M TS-0001 [2] apply with the specific details for: Content: Address of the created <connectionInstance> resource, according to clause 10.1.1.1.of oneM2M TS-0001 [2] |
| Processing at Originator after receiving Response | According to clause 10.1.1.1 of oneM2M TS-0001 [2] |
| Exceptions | According to clause 10.1.1.1 of oneM2M TS-0001 [2] |
7.6.4.2 RETRIEVE <connectionInstance>
This procedure shall be used for retrieving payload data from a communication partner or to retrieve the negotiated key.
Table 7.6.4.2-1: <connectionInstance> RETRIEVE
| <connectionInstance> RETRIEVE request message parameters | |
|---|---|
| Associated Reference Point | Mcs |
| Information in Request message |
According to clause 10.1.2 of oneM2M TS-0001 [2] with the specific details for: To: contains M2M-SE-ID or SE hosted AE-ID or CSE-ID |
| Processing at Originator before sending Request | According to clause 10.1.2 of oneM2M TS-0001 [2] |
| Processing at Receiver | According to clause 10.1.2 of oneM2M TS-0001 [2] |
| Information in Response message |
All parameters defined in table 8.1.3-1 of oneM2M TS-0001 [2] apply with specific details for: Content: Attributes of the <connectionInstance> resources as defined in clause 7.6.3 |
| Processing at Originator after receiving Response | According to clause 10.1.2 of oneM2M TS-0001 [2] |
| Exceptions | According to clause 10.1.2 of oneM2M TS-0001 [2] |
7.6.4.3 UPDATE <connectionInstance>
This procedure shall be used for sending payload data via an established secure connection.
Table 7.6.4.3-1: <connectionInstance> UPDATE
| <connectionInstance> UPDATE request message parameters | |
|---|---|
| Associated Reference Point | Mcs |
| Information in Request message |
All parameters defined in table 8.1.2-3 of oneM2M TS-0001 [2] apply with the specific details for: To: contains M2M-SE-ID or SE hosted M2M-AE-ID or CSE-ID Content: attributes of the <connectionInstance> resource which is to be updated as defined in clause 7.6.3 |
| Processing at Originator before sending Request | According to clause 10.1.3 of oneM2M TS-0001 [2] |
| Processing at Receiver | According to clause 10.1.3 of oneM2M TS-0001 [2] |
| Information in Response message | According to clause 10.1.3 of oneM2M TS-0001 [2] |
| Processing at Originator after receiving Response | According to clause 10.1.3 of oneM2M TS-0001 [2] |
| Exceptions | According to clause 10.1.3 of oneM2M TS-0001 [2] |
7.6.4.4 DELETE <connectionInstance>
This procedure shall be used for deleting a <connectionInstance> resource. Deleting a <connectionInstance> resource closes an established secure connection between the originator (creator) and the destination.
Table 7.6.4.4-1: <connectionInstance> DELETE
| <connectionInstance> DELETE request message parameters | |
|---|---|
| Associated Reference Point | Mcs |
| Information in Request message |
All parameters defined in table 8.1.2-3 of oneM2M TS-0001 [2] apply with the specific details for: To: contains M2M-SE-ID or SE hosted AE-ID or CSE-ID |
| Processing at Originator before sending Request | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
| Processing at Receiver | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
| Information in Response message | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
| Processing at Originator after receiving Response | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
| Exceptions | According to clause 10.1.4.1 of oneM2M TS-0001 [2] |
7.6.5 <connect> Resource
The <connect> resource is a virtual resource because it does not have a representation. When a RETRIEVE request addresses the <connect> resource, a connection shall be established to the destination URI. If <negotiatedKey> exists the negotiated key shall be stored in this attribute.
The <connect> resource inherits access control policies that apply to the parent resource.
7.6.6 <send> Resource
The <send> resource is a virtual resource because it does not have a representation. When a RETRIEVE request addresses the <send> resource, the value of outgoingPayloadData shall be sent to the destination URI.
The <send> resource inherits access control policies that apply to the parent resource.
7.6.7 <generateKey> Resource
The <generateKey> resource is a virtual resource because it does not have a representation. When a RETRIEVE request addresses the <generateKey> resource, the keyData attribute shall be filled with a key generated according the algorithm attribute.
The <generateKey> resource inherits access control policies that apply to the parent resource.