Skip to main content

Security

nRF Cloud device security involves the concepts of authentication and authorization:

  • Authentication means verifying a device's claimed identity.
  • Authorization defines what the device is allowed to do after it has been authenticated.

This article on the AWS IoT Security Model explains these concepts.

Authentication

Authentication requires the use of verifiable pieces of data, known as credentials, that only the bearer (person or device) should have. The password you use to log into nRFCloud.com is an example of a credential. A passport used to cross a national border is another example of a credential.

Devices authenticate differently depending upon which nRF Cloud API they are using:

APIAuthentication mechanismCredentials
MQTTMutual TLSRequires two X.509 certificates: the AWS Root CA (to allow the device to verify the identity of the AWS MQTT broker) and a device certificate (to allow AWS to verify the identity of the device).
RESTJSON Web Token (JWT) over TLSTokens signed by the private key of a device's EC prime256v1 (ES256) asymmetric key pair, whose signature is verified by the associated public key stored on nRF Cloud.

Unlike consumers of Location Services, devices using the Firmware Update Service must be provisioned on nRF Cloud, which requires an X.509 certificate. This certificate, however, is not used to authenticate REST calls. You must also use a device certificate with the initial REST call to the AWS IoT API if using Just-In-Time Provisioning (JITP) without an MQTT client.

Generating key pairs and credentials

There are multiple ways to generate the asymmetric key pairs needed in order to subsequently generate credentials (whether X.509 certificates or JWTs):

Key generationCredential provisioningSecurity level
On the deviceWrite certificates to the device using the CMNG AT command.More secure: private key is never exposed.
On a computerPrivate key and public certificate are written to the device using the CMNG AT command.Less-secure: private key is generated off-device. Security depends on other factors.
On nRF CloudCertificate and keys are obtained through the CreateDeviceCertificate endpoint. Private key and certificate (both the Nordic Semiconductor CA and device certificates) are written to the device using the CMNG AT command. Certificate signing requests are generated using Nordic Semiconductor's managed CA certificate.Less-secure, private key is exposed: certificate and keys are downloaded from nRF Cloud.

For more information on how to generate these assets and credentials, see the Getting started with your devices guide.

Authorization

This section covers authorization in the MQTT and REST APIs.

MQTT

MQTT-based authorization is handled by IoT permissions residing in AWS IoT Core policies that are attached to Thing Groups. Devices that are members of these groups inherit these policies.

In the policies that follow, iot:ClientId is the ID you set in the MQTT client used to connect to nRF Cloud. This must always be the same as your device ID.

For example, all devices that are provisioned on nRF Cloud become members of the Provisioned Devices Thing Group, which has this policy:

{
"Version": "2012-10-17",
"Statement": [
{
"Condition": {
"Bool": {
"iot:Connection.Thing.IsAttached": [
"true"
]
}
},
"Action": "iot:Connect",
"Resource": "arn:aws:iot:*:${AWSAccountId}:client/${iot:ClientId}",
"Effect": "Allow"
},
{
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:*:${AWSAccountId}:topicfilter/${iot:ClientId}/shadow/get/*",
"arn:aws:iot:*:${AWSAccountId}:topicfilter/${iot:ClientId}/shadow/update/*",
"arn:aws:iot:*:${AWSAccountId}:topicfilter/$aws/things/${iot:ClientId}/shadow/get/*",
"arn:aws:iot:*:${AWSAccountId}:topicfilter/$aws/things/${iot:ClientId}/shadow/update/*",
"arn:aws:iot:*:${AWSAccountId}:topicfilter/$aws/things/${iot:ClientId}/jobs/*"
],
"Effect": "Allow"
},
{
"Action": "iot:Publish",
"Resource": [
"arn:aws:iot:*:${AWSAccountId}:topic/$aws/things/${iot:ClientId}/shadow/get",
"arn:aws:iot:*:${AWSAccountId}:topic/$aws/things/${iot:ClientId}/shadow/update",
"arn:aws:iot:*:${AWSAccountId}:topic/$aws/things/${iot:ClientId}/jobs/*"
],
"Effect": "Allow"
},
{
"Action": [
"iot:Receive"
],
"Resource": "*",
"Effect": "Allow"
},
{
"Action": [
"iot:UpdateThingShadow",
"iot:GetThingShadow"
],
"Resource": "arn:aws:iot:*:${AWSAccountId}:thing/${iot:ClientId}",
"Effect": "Allow"
}
]
}

When the device is not only cloud provisioned but also added to a user's account, the device becomes a member of the Associated Devices Thing Group. This group adds more permissions for its member devices. In the following policy, tenantId is your Team ID.

{
"Version": "2012-10-17",
"Statement": [
{
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[tenantId]}/m/*",
"arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[tenantId]}/a/*",
"arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[tenantId]}/${iot:ClientId}/jobs/*",
"arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[tenantId]}/${iot:ClientId}/jobs/ble/*"
],
"Effect": "Allow"
},
{
"Action": "iot:Publish",
"Resource": [
"arn:aws:iot:*:${AWSAccountId}:topic/prod/${iot:Connection.Thing.Attributes[tenantId]}/m/*",
"arn:aws:iot:*:${AWSAccountId}:topic/prod/${iot:Connection.Thing.Attributes[tenantId]}/${iot:ClientId}/jobs/*",
"arn:aws:iot:*:${AWSAccountId}:topic/prod/${iot:Connection.Thing.Attributes[tenantId]}/${iot:ClientId}/jobs/ble/*"
],
"Effect": "Allow"
}
]
}

LTE gateways also receive additional permissions for MQTT topics used for gateway messages:

{
"Version": "2012-10-17",
"Statement": [
{
"Action": "iot:Subscribe",
"Resource": [
"arn:aws:iot:*:${AWSAccountId}:topicfilter/prod/${iot:Connection.Thing.Attributes[teamId]}(see s/${iot:ClientId}/c2g"
],
"Effect": "Allow"
},
{
"Action": "iot:Publish",
"Resource": [
"arn:aws:iot:*:${AWSAccountId}:topic/prod/${iot:Connection.Thing.Attributes[teamId]}(see s/${iot:ClientId}/g2c"
],
"Effect": "Allow"
}
]
}
note

This policy does not apply to phone gateways, which use an AWS Cognito user-based policy and the /c2g and /g2c topics.

Security violations

If your device attempts to do anything over MQTT that is not supported by the above policies, it is immediately disconnected from the IoT broker. Common problems are attempting to publish or subscribe to a topic not allowed by the policy. If you debug, you can see the device get a POLLHUP. When using the nRF Cloud library, the event generated is of type NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED with a status value of NRF_CLOUD_DISCONNECT_CLOSED_BY_REMOTE.

For more information see this section on disconnection from the cloud in the nRF Connect SDK documentation.

REST

While authorization for REST-based operations may also involve IoT security policies, what is permitted depends on whether the JWT signature can be verified and the request allowed to continue. Authorization is highly connected to endpoint access.