Skip to main content

Security

Overview#

nRF Cloud device security involves the concepts of authentication—verifying a device's claimed identity—and authorization—i.e., what the device is allowed to do after its identity is verified.

This article on the AWS IoT Security Model provides good background information.

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). Two-way identity verification = "mutual".
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. A device certificate must also used with the initial REST call to the AWS IoT API if using Just-In-Time Provisioning (JITP) without an MQTT client. Devices are authenticated to nRF Cloud using the following credentials:

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 deviceCertificates are written 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 Cloud*Certificate and keys are obtained via the CreateDeviceCertificate endpoint. Private key and certificate (both the Nordic CA and device certificates) are written to the device using the CMNG AT command.Less-secure, private key is exposed: certificate and keys are downloaded from nRF Cloud.

* CSR's are generated using Nordic Semiconductor's managed CA certificate.

For more information on how to generate these assets and credentials, see the Getting Started With Your Devices guide.

Authorization#

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"    }  ]}

Additionally, when the device is not merely 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. Due to its architecture and the use of Websockets, this gateway uses a different, AWS Cognito user-based policy. It does, however, use the /c2g and /g2c topics.

Security Violations#

If your device attempts to do anything over MQTT that is not supported by the above policies—common problems are attempting to publish or subscribe to a topic not allowed by the policy—your device will be immediately disconnected from the IoT broker. If debugging you will see the device get a POLLHUP, which results in CLOUD_DISCONNECT_CLOSED_BY_REMOTE. This is followed by NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED (if using the nRF Cloud library), or CLOUD_EVT_DISCONNECTED (if using the Cloud API library).

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 the IoT security policies listed above, what is permitted is essentially tied to whether the JWT signature can be verified, and thus the request be allowed to continue. In other words, authorization is tightly correlated with endpoint access.