The set command creates keys for different purposes.
The purposes are the following:
- Client private key and certificate signing request (CSR)
(<key_type> 2, <response_content>
0)
- The CSR can be passed to a Certificate Authority (CA) for requesting a client
certificate for the device. The modem stores the generated private key to a
<sec_tag>. The client certificate must be stored to the device
in the same <sec_tag> as the client private key. The client
device certificate and the corresponding private key can be used as TLS client
credentials.
The %KEYGEN response contains a Certificate Signing
Request (CSR) and COSE signature for the CSR separated by a dot "." with both sides
Base64Url-encoded:
"Base64Url(CSR_DER).Base64Url(cose_sign)"
.
- Client private key and public key (<key_type> 2,
<response_content> 1)
- The %KEYGEN response contains a public key in CBOR device pubkey
message and COSE signature separated by dot "." with both sides Base64Url-encoded:
"Base64Url(public_key_DER).Base64Url(cose_sign)"
.
- Device Endorsement key pair (<key_type> 8)
- Endorsement keys can be used to pass encrypted data to a device. The endorsement
private key is stored to the device in a <sec_tag>, and the
public key is returned in a %KEYGEN response. If the private key
already exists in <sec_tag>, the response is created based on
the existing key instead of creating a new key.
The %KEYGEN
response contains an Endorsement Public key in CBOR device pubkey message and COSE
signature separated by dot "." with both sides Base64Url-encoded:
"Base64Url(public_key_DER).Base64Url(cose_sign)"
.
Note:
- The %KEYGEN command is allowed only when the modem is
deactivated.
- The %CMNG list operation can be
used to check the availability of generated keys.
Syntax:
%KEYGEN=<sec_tag>,<key_type>[,<response_content>][,<attributes>][,<key_usage>]
- +CME ERROR codes
- 514 – Not allowed
- 515 – Memory full
- 518 – Not allowed in active state
- 519 – Already exists
- 523 – Key generation failed
- 528 – Not allowed during active power off
warning.v1.3.x≥2
The set command parameters and their defined values are the following:
- <sec_tag>
- Integer, 1–2147483647.
- <key_type>
- Integer
- Type of the decryption key. Values corresponding to <type> in
%CMNG.
- Supported values:
- 2 – Client private key
- 8 – Endorsement key
- <response_content>
- Integer
- Mandatory for <key_type> 2. Optional for
<key_type> 8.
- Content of the response:
- 0 – Certificate signing request returned in response
(<key_type> 2 only)
- 1 – Public key returned in response (<key_type> 2 or 8)
- <attributes>
- String
- Optional. Valid only for CSR (<response_content> 0), otherwise
ignored. The content of the string is a comma-separated list of attribute ID and value
pairs, for example, "ID1=value1,ID2=value2", where the ID can be one of the supported
attributes listed below, and the values provide the corresponding information (see
RFC 5280).
- Supported attributes:
- commonName (CN)
- locality (L)
- stateOrProvinceName (ST)
- organizationName (O)
- organizationalUnitName (OU)
- countryName (C)
- domainComponent (DC)
- surName (SN)
- givenName (GN)
- emailAddress (R)
- serialNumber
- postalAddress
- postalCode
- dnQualifier
- title
- initials
- pseudonym
- generationQualifier
- If the <attributes> parameter is omitted, the default is
"CN=<device-uuid>".
- <key_usage>
- String
- Optional. Valid only for CSR (response_content 0), otherwise ignored. The string
contains 9 binary characters (0/1) corresponding to the KeyUsage bit string defined in
RFC 5280. The digits or bits in the string are numbered 0–8 from left to
right, and they have the following meaning (see RFC 5280 for more
details).
- 0 – digitalSignature (the first digit)
- 1 – nonRepudiation
- 2 – keyEncipherment
- 3 – dataEncipherment
- 4 – keyAgreement
- 5 – keyCertSign
- 6 – cRLSign
- 7 – encipherOnly
- 8 – decipherOnly (the last digit)
Note: Setting decipherOnly bit to 1 is not
supported.
- If the <key_usage> parameter is omitted, default is
"111010000", which means that the digitalSignature, nonRepudiation, keyEncipherment, and
keyAgreement bits are set as "1".
The following command example generates a key for TLS. The key is stored to
<sec_tag> 11. The <key_type> is client
private key, and it includes the optional <key_usage> parameter:
AT%KEYGEN=11,2,0,,"101010000"
%KEYGEN: "ckijfiok.jdiqhdn"
OK
The following command example generates a key for TLS. The key is stored to
<sec_tag> 11. The <key_type> is client
private key, and it includes the optional parameters <attributes>
and <key_usage>:
AT%KEYGEN=11,2,0,"O=Nordic Semiconductor,L=Trondheim,C=no","101010000"
%KEYGEN: "MIIBHDCBwAIBADBAMR0wGwYDVQQKDBROb3JkaWMgU2VtaWNvbmR1Y3RvcjESMBAGA1UEB
wwJVHJvbmRoZWltMQswCQYDVQQGEwJubzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAP6p4ZjYNG0
FFdz5axZkbcQzfO8Fkzws4o2unhS5qqgON5BA6jj0TbHJ5imPbVXWNiDVCNc0us41NtL3TygDdqgHjA
cBgkqhkiG9w0BCQ4xDzANMAsGA1UdDwQEAwIDqDAMBggqhkjOPQQDAgUAA0kAMEYCIQDnFWQl-x25qj
EPBtLrvH5wwecrA5KmjUcK_b3eok5nmQIhALsSKRmuqDM3H09-q4R0MSpYprWZZp5iPjRMtZbjataH.
0oRDoQEmoQRBIVhL2dn3hQlQUFAwQTYzQ7CAwwEaNJbawEELWCD7er2zKHc8yAMi8x-1jAuCEqaLmJ3
PMZTHIYSrmIR0tlD7CDRaW--s0c7XA4pI3r9wWEAQOGVg5VejmHx9o_sF1RcGBMClw-MkN_wMrS2ryM
8CdA427j96z_4wjLgBvejVnYGAl7qqL77qlEbBEzXOkLx4"
OK
The following command example generates an endorsement key. The key is stored to
<sec_tag> 33. The <key_type> is
endorsement private key:
AT%KEYGEN=33,8
%KEYGEN: "vdofjihew.cnjeiwhfok"
OK