Set command

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)".

Syntax:

%KEYGEN=<sec_tag>,<key_type>[,<response_content>][,<attributes>][,<key_usage>]

+CME ERROR code

514 – Not allowed.

515 – Memory full.

518 – Not allowed in active state.

519 – Already exists.

523 – Key generation failed.

528 – Not allowed when power off warning is active.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)

2 – Self-signed certificate (<key_type> 14 only)

<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