[tcat_ble_client] Added TCAT Commissioner and Device certs compatible…

… with Thread cert test; added scripts for example certificate generation; README files updated.

tools/tcat_ble_client/GENERATING_CERTIFICATES.md

@@ -1,4 +1,4 @@
-# BBTC X.509 certificates generation
+# TCAT X.509 certificates generation
 
 ---
 
@@ -8,7 +8,16 @@ TCAT uses X.509 Certificate Extensions to provide permissions with certificates.
 
 Extensions were introduced in version 3 of the X.509 standard for certificates. They allow certificates to be customised to applications by supporting the addition of arbitrary fields in the certificate. Each extension, identified by its OID (Object Identifier), is marked as "Critical" or "Non-Critical", and includes the extension-specific data.
 
-## Certificates generation
+## Certificates generation (Script)
+
+The directory `auth-generate` contains example scripts and a Makefile to generate TCAT Commissioner certificates and 
+a TCAT Device certificate. The scripts provide the most detailed view on how to generate these certificates.
+
+NOTE: the directory `auth-generate/ca` contains an example CA certificate and private key (for signing). Other CAs can be added 
+in here. This CA is not the same used for the TCAT Commissioner and Device identities in the `auth` directory! The CA for the 
+latter is privately maintained by Thread Group.
+
+## Certificates generation (Manual)
 
 Thread uses Elliptic Curve Cryptography (ECC), so we use the `ecparam` `openssl` argument to generate the keys.
 
@@ -20,19 +29,19 @@ Thread uses Elliptic Curve Cryptography (ECC), so we use the `ecparam` `openssl`
 openssl ecparam -genkey -name prime256v1 -out ca_key.pem
 ```
 
-1. We can then generate the **.csr** (certificate signing request) file, which will contain all the parameters of our final certificate:
+2. We can then generate the **.csr** (certificate signing request) file, which will contain all the parameters of our final certificate:
 
 ```
 openssl req -new -sha256 -key ca_key.pem -out ca.csr
 ```
 
-1. Finally, we can generate the certificate itself:
+3. Finally, we can generate the certificate itself:
 
 ```
 openssl req -x509 -sha256 -days 365 -key ca_key.pem -in ca.csr -out ca_cert.pem
 ```
 
-1. See the generated certificate using
+4. See the generated certificate using
 
 ```
 openssl x509 -in ca_cert.pem -text -noout
@@ -46,25 +55,25 @@ openssl x509 -in ca_cert.pem -text -noout
 openssl ecparam -genkey -name prime256v1 -out commissioner_key.pem
 ```
 
-1. Specify additional extensions when generating the .csr (see [sample configuration](#Configurations)):
+2. Specify additional extensions when generating the .csr (see [sample configuration](#Configurations)):
 
 ```
 openssl req -new -sha256 -key commissioner_key.pem -out commissioner.csr -config commissioner.cnf
 ```
 
-1. Generate the certificate:
+3. Generate the certificate:
 
 ```
 openssl x509 -req -in commissioner.csr -CA ca_cert.pem -CAkey ca_key.pem -out commissioner_cert.pem -days 365 -sha256 -copy_extensions copy
 ```
 
-1. View the generated certificate using:
+4. View the generated certificate using:
 
 ```
 openssl x509 -in commissioner_cert.pem -text -noout
 ```
 
-1. View parsed certificate extensions using:
+5. View parsed certificate extensions using:
 
 ```
 openssl asn1parse -inform PEM -in commissioner_cert.pem

tools/tcat_ble_client/README.md

@@ -12,8 +12,6 @@ If you don't have the poetry module installed (check with `poetry --version`), i
 python3 -m pip install poetry
 ```
 
-Thread uses Elliptic Curve Cryptography (ECC), so we use the `ecparam` `openssl` argument to generate the keys.
-
 ```
 poetry install
 ```
@@ -43,7 +41,25 @@ poetry run python3 bbtc.py --name 'Thread BLE'
 
 The application will connect to the first matching device discovered and set up a secure TLS channel. The user is then presented with the CLI.
 
-## Commands
+## Usage with a specific TCAT Commissioner identity
+
+The TCAT Commissioner's certificate specifies what authorization it has obtained for specific features of managing a TCAT Device.
+In order to use a different TCAT Commissioner certificate (identity), use the `--cert_path` argument, as follows:
+
+```bash
+poetry run python3 bbtc.py --cert_path <certs-path> {<device specifier> | --scan}
+```
+
+where `<certs-path>` is the directory where the private key, certificate, and CA certificate of the TCAT Commissioner 
+are stored.
+
+For example to use a pre-configured identity `CommCert2` use:
+
+```
+poetry run python3 bbtc.py --cert_path ./auth/CommCert2 --name 'Thread BLE'
+```
+
+## TCAT Commissioner CLI Commands
 
 The application supports the following interactive CLI commands:
 
@@ -53,4 +69,4 @@ The application supports the following interactive CLI commands:
 - `thread stop` - Disable Thread interface.
 - `hello` - Send "hello world" application data and read the response.
 - `exit` - Close the connection and exit.
-- `dataset` - View and manipulate current dataset. See `dataset help` for more information.
+- `dataset` - View and manipulate current dataset. Use `dataset help` for more information.

tools/tcat_ble_client/auth-generate/Makefile

@@ -0,0 +1,43 @@
+#
+#  Copyright (c) 2024, The OpenThread Authors.
+#  All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are met:
+#  1. Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#  3. Neither the name of the copyright holder nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+#  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+#  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+#  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+#  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+#  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+#  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+#  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+#
+
+# Makefile for creating TCAT example certificates (except CA).
+
+all: DeviceCert1 CommCert1 CommCert2
+
+DeviceCert1: ext/DeviceCert1.ext
+	./create-cert-tcat-device.sh DeviceCert1 ca
+
+CommCert1: ext/CommCert1.ext
+	./create-cert-tcat-commissioner.sh CommCert1 ca
+
+CommCert2: ext/CommCert2.ext
+	./create-cert-tcat-commissioner.sh CommCert2 ca
+
+clean:
+	rm -rf ./output

tools/tcat_ble_client/auth-generate/ca/ca_cert.pem

@@ -0,0 +1,14 @@
+-----BEGIN CERTIFICATE-----
+MIICHjCCAcSgAwIBAgIBATAKBggqhkjOPQQDAjBmMR0wGwYDVQQDDBRUQ0FUIEV4
+YW1wbGUgQ0EgJ2NhJzEUMBIGA1UECgwLRXhhbXBsZSBJbmMxFTATBgNVBAcMDEV4
+YW1wbGUgQ2l0eTELMAkGA1UECAwCQ0ExCzAJBgNVBAYTAlVTMB4XDTI0MDUwNTE5
+MTAyMloXDTQ0MDQzMDE5MTAyMlowZjEdMBsGA1UEAwwUVENBVCBFeGFtcGxlIENB
+ICdjYScxFDASBgNVBAoMC0V4YW1wbGUgSW5jMRUwEwYDVQQHDAxFeGFtcGxlIENp
+dHkxCzAJBgNVBAgMAkNBMQswCQYDVQQGEwJVUzBZMBMGByqGSM49AgEGCCqGSM49
+AwEHA0IABFncszwFxinmWPeDoRwFlx8yX0CIxksmjs5YC/ThBcNkqFA53CyjxsHz
+wFEn7jMhJM7MzQzNBx5AbAy6ruJ9uf+jYzBhMB8GA1UdEQQYMBaBFGNhLWFkbWlu
+QGV4YW1wbGUub3JnMA4GA1UdDwEB/wQEAwIBhjAPBgNVHRMBAf8EBTADAQH/MB0G
+A1UdDgQWBBTgTKehLD14MpkRU+S6azYhYsAkKjAKBggqhkjOPQQDAgNIADBFAiA2
+Wp9JGbwiqbW0l0fTS+AKdp6xFXkmuePftuUTsnMKcgIhAPdC1zdx8fHPoTnRLpiH
+Pt2/QkcSashR9zOp9MrBnRPb
+-----END CERTIFICATE-----

tools/tcat_ble_client/auth-generate/create-cert-ca.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+#
+#  Copyright (c) 2024, The OpenThread Authors.
+#  All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are met:
+#  1. Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#  3. Neither the name of the copyright holder nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+#  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+#  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+#  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+#  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+#  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+#  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+#  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+#
+
+# Create the certificate of an example CA for TCAT. This single CA creates both the
+# TCAT Device certificates, as well as the TCAT Commissioner certificates that
+# work for those TCAT Devices.
+
+if [ $# -ne 1 ]; then
+  echo "Usage: ./create-cert-ca.sh <NameOfCA>"
+  exit 1
+fi
+set -eu
+
+# days certificate is valid
+(( VALIDITY=20*365 ))
+
+NAME=${1}
+
+# create csr
+openssl req -new -key "ca/${NAME}_key.pem" -out "${NAME}.csr" \
+            -subj "/CN=TCAT Example CA '${NAME}'/O=Example Inc/L=Example City/ST=CA/C=US"
+
+# self-sign csr
+mkdir -p output >& /dev/null
+openssl x509 -set_serial 0x01 -extfile "ext/${NAME}.ext" \
+ -extensions "${NAME}" -req -in "${NAME}.csr" \
+ -signkey "ca/${NAME}_key.pem" -out "ca/${NAME}_cert.pem" \
+ -days "${VALIDITY}" -sha256
+
+# delete temp files
+rm -f "${NAME}.csr"
+
+# show result
+openssl x509 -text -in "ca/${NAME}_cert.pem"

tools/tcat_ble_client/auth-generate/create-cert-tcat-commissioner.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+#
+#  Copyright (c) 2024, The OpenThread Authors.
+#  All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are met:
+#  1. Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#  3. Neither the name of the copyright holder nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+#  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+#  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+#  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+#  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+#  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+#  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+#  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+#
+
+# Script to generate a TCAT Commissioner X509v3 certificate.
+
+if [ $# -ne 2 ]; then
+  echo "Usage: ./create-cert-tcat-commissioner.sh <NameOfCommissioner> <NameOfCA>"
+  exit 1
+fi
+set -eu
+
+# number of days certificate is valid
+(( VALIDITY="14" ))
+echo "create-cert-tcat-commissioner.sh - Using validity param -days ${VALIDITY}"
+
+NAME=${1}
+CANAME=${2}
+(( ID=${NAME:0-1} ))
+
+echo "  TCAT commissioner name   : ${NAME}"
+echo "  TCAT commissioner CA name: ${CANAME}"
+echo "  Numeric serial ID        : ${ID}"
+
+# create csr for TCAT Commissioner
+openssl req -new -key "keys/${NAME}_key.pem" -out "${NAME}.csr" -subj \
+             "/CN=TCAT Example ${NAME}/serialNumber=3523-1543-000${ID}"
+
+# sign csr by CA
+mkdir -p output >& /dev/null
+openssl x509 -set_serial "92429${ID}" -CAform PEM -CA "ca/${CANAME}_cert.pem" \
+  -CAkey "ca/${CANAME}_key.pem" -extfile "ext/${NAME}.ext" -extensions \
+  "${NAME}" -req -in "${NAME}.csr" -out "output/${NAME}_cert.pem" \
+  -days "${VALIDITY}" -sha256
+
+# delete temp files
+rm -f "${NAME}.csr"

tools/tcat_ble_client/auth-generate/create-cert-tcat-device.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+#
+#  Copyright (c) 2024, The OpenThread Authors.
+#  All rights reserved.
+#
+#  Redistribution and use in source and binary forms, with or without
+#  modification, are permitted provided that the following conditions are met:
+#  1. Redistributions of source code must retain the above copyright
+#     notice, this list of conditions and the following disclaimer.
+#  2. Redistributions in binary form must reproduce the above copyright
+#     notice, this list of conditions and the following disclaimer in the
+#     documentation and/or other materials provided with the distribution.
+#  3. Neither the name of the copyright holder nor the
+#     names of its contributors may be used to endorse or promote products
+#     derived from this software without specific prior written permission.
+#
+#  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+#  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+#  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+#  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+#  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+#  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+#  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+#  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+#  POSSIBILITY OF SUCH DAMAGE.
+#
+
+# Script to generate a TCAT Device X509v3 certificate.
+
+if [ $# -ne 2 ]; then
+  echo "Usage: ./create-cert-tcat-device.sh <NameOfDevice> <NameOfCA>"
+  exit 1
+fi
+set -eu
+
+# days certificate is valid
+SECONDS1=$(date +%s) # time now
+SECONDS2=$(date --date="2999-12-31 23:59:59Z" +%s) # target end time
+(( VALIDITY="(${SECONDS2}-${SECONDS1})/(24*3600)" ))
+echo "create-cert-tcat-device.sh - Using validity param -days ${VALIDITY}"
+
+NAME="${1}"
+CANAME="${2}"
+(( ID=${NAME:0-1} ))
+(( SERIAL=13800+ID ))
+
+echo "  TCAT device name   : ${NAME}"
+echo "  TCAT device CA name: ${CANAME}"
+echo "  Numeric serial ID  : ${ID}"
+
+# create csr for device.
+# conform to 802.1AR guidelines, using only CN + serialNumber when 
+# manufacturer is already present as CA. CN is not even mandatory, but just good practice.
+openssl req -new -key "keys/${NAME}_key.pem" -out "${NAME}.csr" -subj \
+             "/CN=TCAT Example ${NAME}/serialNumber=4723-9833-000${ID}"
+
+# sign csr by CA
+mkdir -p output >& /dev/null
+openssl x509 -set_serial "${SERIAL}" -CAform PEM -CA "ca/${CANAME}_cert.pem" \
+  -CAkey "ca/${CANAME}_key.pem" -extfile "ext/${NAME}.ext" -extensions \
+  "${NAME}" -req -in "${NAME}.csr" -out "output/${NAME}_cert.pem" \
+  -days "${VALIDITY}" -sha256
+
+# delete temp files
+rm -f "${NAME}.csr"

tools/tcat_ble_client/auth-generate/ext/CommCert1.ext

@@ -0,0 +1,12 @@
+# This file contains X509v3 extension definitions for OpenSSL
+# certificate generation. 
+
+[ CommCert1 ]
+keyUsage = critical,digitalSignature, nonRepudiation, \
+           keyEncipherment, dataEncipherment
+basicConstraints = CA:FALSE
+subjectKeyIdentifier = none
+authorityKeyIdentifier=keyid
+
+# Include TCAT specified fields
+1.3.6.1.4.1.44970.3 = ASN1:OCTETSTRING:2101010101

tools/tcat_ble_client/auth-generate/ext/CommCert2.ext

@@ -0,0 +1,15 @@
+# This file contains X509v3 extension definitions for OpenSSL
+# certificate generation. 
+
+[ CommCert2 ]
+keyUsage = critical,digitalSignature, nonRepudiation, \
+           keyEncipherment, dataEncipherment
+basicConstraints = CA:FALSE
+subjectKeyIdentifier = none
+authorityKeyIdentifier=keyid
+
+# Include TCAT specified fields
+1.3.6.1.4.1.44970.1 = ASN1:IA5STRING:DefaultDomain
+1.3.6.1.4.1.44970.3 = ASN1:OCTETSTRING:211F3F3F3F
+1.3.6.1.4.1.44970.4 = ASN1:UTF8STRING:OpenThread-c64e
+1.3.6.1.4.1.44970.5 = ASN1:OCTETSTRING:ef1398c2fd504b67