1# TCAT X.509 certificates generation
2
3---
4
5TCAT uses X.509 Certificate Extensions to provide permissions with certificates.
6
7## Extensions
8
9Extensions 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.
10
11## Certificates generation (by script)
12
13The directory `auth-generate` contains example scripts and a Makefile to generate TCAT Commissioner certificates and TCAT Device certificates. The scripts can also handle multiple CAs, and provide the most detailed view on how to generate these certificates.
14
15To generate all certificates:
16
17```
18cd auth-generate
19make
20```
21
22This will create an `output` directory with subdirectories for each of the created identities. Each subdirectory can be used as a value for the BBTC Commissioner `--cert_path` argument, if needed.
23
24NOTE: 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 CA used for the TCAT Commissioner and Device identities in the `auth` and `auth-cert` directories! The CA for the latter is privately maintained by Thread Group.
25
26## Certificates generation (manually)
27
28Thread TCAT uses Elliptic Curve Cryptography (ECC), so we use the `ecparam` `openssl` argument to generate the keys.
29
30### Root certificate
31
321. Generate the private key:
33
34```
35openssl ecparam -genkey -name prime256v1 -out ca_key.pem
36```
37
382. We can then generate the **.csr** (certificate signing request) file, which will contain all the parameters of our final certificate:
39
40```
41openssl req -new -sha256 -key ca_key.pem -out ca.csr
42```
43
443. Finally, we can generate the certificate itself:
45
46```
47openssl req -x509 -sha256 -days 365 -key ca_key.pem -in ca.csr -out ca_cert.pem
48```
49
504. See the generated certificate using
51
52```
53openssl x509 -in ca_cert.pem -text -noout
54```
55
56### Commissioner (client) certificate
57
581. Generate the key:
59
60```
61openssl ecparam -genkey -name prime256v1 -out commissioner_key.pem
62```
63
642. Specify additional extensions when generating the .csr (see [sample configuration](#Configurations)):
65
66```
67openssl req -new -sha256 -key commissioner_key.pem -out commissioner.csr -config commissioner.cnf
68```
69
703. Generate the certificate:
71
72```
73openssl x509 -req -in commissioner.csr -CA ca_cert.pem -CAkey ca_key.pem -out commissioner_cert.pem -days 365 -sha256 -copy_extensions copy
74```
75
764. View the generated certificate using:
77
78```
79openssl x509 -in commissioner_cert.pem -text -noout
80```
81
825. View parsed certificate extensions using:
83
84```
85openssl asn1parse -inform PEM -in commissioner_cert.pem
86```
87
88## Configurations
89
90file: `commissioner.cnf` (line `1.3.6.1.4.1.44970.3 = DER:21:01:01:01:01` specifies permissions (all)) See scripts in `auth-generate` directory for more details.
91
92```
93[ req ]
94default_bits           = 2048
95distinguished_name     = req_distinguished_name
96prompt                 = no
97req_extensions         = v3_req
98
99[ req_distinguished_name ]
100CN                     = Commissioner
101
102[v3_req]
1031.3.6.1.4.1.44970.3 = DER:04:05:21:01:01:01:01
104authorityKeyIdentifier = none
105subjectKeyIdentifier = none
106```
107