Digi XBee 3 User Manual

Transport Layer Security (TLS) Specifying TLS keys and certificates
Digi XBee® 3 Cellular LTE Cat 1 AT&T Smart Modem User Guide
180
Specifying TLS keys and certificates
These AT commands, when used together, let you interact with TLSfeatures: ATFS (File System), TL
(TLS Protocol Version), IP (IP Protocol), $0 (TLS Profile 0), $1 (TLS Profile 1), and $2 (TLS Profile 2). The
format of the $ commands is:
AT$<num>[<ca_cert>];[<client_cert>];[<client_key>]
Where:
n num: Profile index. Index zero is used for Transparent mode connections and TLS connections
using Transmit (TX) Request: IPv4 - 0x20.
n ca_cert: (optional) Filename of a file in the certs/ directory. Indicates the certificate identifying
a trusted root certificate authority (CA) to use in validating servers. If ca_cert is empty the
server certificate will not be authenticated. This must be a single root CA certificate. The
modules do not allow a non-self signed certificate to work, so intermediate CAs are not
enough.
n client_cert: (optional) Filename of a file in the certs/ directory. Indicates the certificate
presented to servers when requested for client authentication. If client_cert is empty no
certificate is presented to the server should it request one. This may result in mutual
authentication failure.
n client_key: (optional) Filename of a file in the certs/ directory. Indicates the private key
matching the public key contained in client_cert. This should be a secure file uploaded with
ATFS XPUTfilename. This should always be provided if client_cert is provided and match the
certificate or client authentication will fail.
The default value is ";;". This default value preserves the legacy behavior by allowing the creation of
encrypted connections that are confidential but not authenticated.
To specify a key stored outside of certs/, you can either use a relative path, for example ../server.pem
or an absolute path starting with /flash, for example /flash/server.pem. Both examples refer to the
same file.
It is not an error at configuration time to name a file that does not yet exist. An error is generated if
an attempt to create a TLS connection is made with improper settings.
n Files specified should all be in PEM format, not DER.
n Upload private keys securely with ATFS XPUTfilename.
n Certificates can be uploaded with ATFS PUTfilename as they are not sensitive. It is not
possible to use ATFS GETfilename to GETthem if they have been securely uploaded.
To authenticate a server not participating in a public key infrastructure (PKI) using CAs, the server
must present a self-signed certificate. That certificate can be used in the ca_cert field to authenticate
that single server.
There are effectively three levels of authentication provided depending on the parameters provided
1. No authentication: None of the parameters are provided, this is the default value. With this
configuration identity is not validated and a man in the middle (MITM) attack is possible.
2. Server authentication: Only ca_cert is provided. Only the servers identity is checked
3. Mutual authentication: All items are provided and both sides are assured of the identity of their
peer
It is not possible to only have client authentication.

Digi XBee 3 Specifications

General

Brand	Digi
Model	XBee 3
Category	Modem
Language	English