#### OpenSSL version for this note
3.0.13

## Key Generation
### RSA private key

openssl genrsa -out ca-privkey.pem  2048

- this command generates a 2048-bit RSA key , for minimum suggested key size , see [this wiki page](https://en.wikipedia.org/wiki/Key_size#Asymmetric_algorithm_key_lengths) .

### RSA public key
In OpenSSL, RSA private key contains factors which are also part of public key, you can extract the public RSA key from the factors.

openssl rsa  -in  ./ca-privkey.pem  -outform PEM -pubout -out /path/to/rsa_pubkey.pem

To extract modulus from the public key PEM file, and encoded it as Base64 string :

openssl rsa -pubin -inform PEM -text -noout -in   /path/to/rsa_pubkey.pem \
    |  awk "/Modulus/{flag=1; next} /Exponent/{flag=0} flag" \
    |  tr -d ': \n'  |  xxd -r -p | base64

Note
- `awk` narrows down the output from the `Modulus` section to the `Exponent` section
- optionally you can output extracted byte sequence to a file using `xxd`

## Certificate setup
### Generate CA cert

openssl req -new -x509 -days 261 -key ./ca-privkey.pem -keyform PEM -out ./ca-crt.pem -outform PEM -sha384

- use existing CA's private key file for signing the cert (regardless which cryptography algorithm to use)
- the option `-sha384` indicates OpenSSL should use SHA384 to hash the certificate data (excluding signature) to produce digest
- then encrypt (sign) that digest using CA's private key (e.g. RSA)
- the encrypted digest would be processed by other operations e.g. zero padding , then finally it becomes signature value placed at the end of certificate file .
- optionally you can add `-subj` collecting subject information, which is helpful in build automation.

### Check content of a cert

openssl x509 -text -noout -in ./ca-crt.pem -inform PEM

### Generate server cert, sign it using CA cert
#### Generate cert signing request (CSR)

openssl req -new  -key ./server-privkey.pem   -keyform PEM \
    -out ./server-csr.pem  -outform PEM  -sha384 \
    -extensions v3_req \
    -subj "/C=TW/ST=New Taipei/L=Neo Taibie/O=Your Org Name/CN=mq.your.org" \
    -addext "subjectAltName = DNS:broker.llama.deepdive, IP:192.168.79.245" \
    -addext "keyUsage = nonRepudiation, digitalSignature, keyEncipherment" \
    -addext "basicConstraints = CA:FALSE"

- key file `server-privkey.pem` depends on the crypto algorithm you used, for RSA there is command example shown above.
- signature size is determined by key kength (e.g. RSA 2048 bits in the command above)
- `-subj` collects subject information, which is optional but helpful in build automation.
- `-addext` adds extra extensions for specific host
- Edit `subjectAltName` and `keyUsage` for your requirement
- alternatively, the extensions can also be placed in `usr_cert` section of your target `openssl.cnf`.
- `usr_cert` will be referred to later in the command `openssl x509 -req`
- see default config file `/etc/ssl.openssl.cnf` for detail

##### IMPORTANT: Server Certificate should contain at least one valid way to identify the server maichine
- the valid way can be either **domain name** or **static (remote / local) IP address**
- [relevant discussion with GPT](https://chatgpt.com/s/t_6867a7e11704819195c160407c44a138) about fundametal certificate knowledge
- Some languages (e.g. Python >= 3.7) [do NOT support IP address in CN field when decoding x509 certificate](https://stackoverflow.com/questions/52855924/problems-using-paho-mqtt-client-with-python-3-7) , so it will be treated as error.
- To avoid the error above, add the extension `subjectAltName` instead to CSR , it consists of one or several domain names e.g. `DNS:my.whateverapp.org` and exactly one IP address e.g. `IP:98.7.156.43`.

##### Bug : `-extensions` and `-addext` cannot co-exist in the same command
OpenSSL v3.0.x complained duplicate extensions and reported following error :

808B53DCD5730000:error:0580008C:x509 certificate routines:X509at_add1_attr_by_NID:duplicate attribute:../crypto/x509/x509_att.c:184

- I didn't further investigate and delve into the code implementation, it seems that OpenSSL internally refers to the config file `/etc/ssl/openssl.cnf` **more than once without resolving the same extension**
- [relevant discussion with GPT](https://chatgpt.com/s/t_6867aedf9fc48191b8e6d00916920f7c)
- Current workaround is to avoid the options `-extensions` and `-addext` in the same command.

> for better deployment automation , adding all extensions by `-addext` may be appropriate approach.

#### Generate server (non-CA) cert

openssl x509 -req -in ./server-csr.pem \
    -extfile /path/to/your/openssl.cnf -extensions usr_cert \
    -copy_extensions copyall -CAcreateserial \
    -CA ./ca-crt.pem -CAform PEM \
    -CAkey ./ca-privkey.pem -CAkeyform PEM \
    -out ./server-crt.pem  -outform PEM \
    -days 182 -sha256

##### Bug : OpenSSL doesn't copy x509v3 extensions from CSR to user certificate
x509v3 extensions `v3_req` is still missing even it is added to parameter `req_extensions` in openssl config file `<OPENSSL_INSTALL_PATH>/openssl.cnf` specified by `-extfile`.
- Check out [this Stack Exchange thread](https://security.stackexchange.com/q/150078/214639) for detail.
- current workaround forces OpenSSL copy the extensions from CSR, using the option `-copy_extensions copyall` with the command `openssl x509`

### Verify the certicate signed by the CA

openssl verify -verbose -CAfile /PATH/TO/ca.crt  /PATH/TO/whatever_cert_to_test.crt 

You should see the result if it is verified successfully

> /PATH/TO/whatever_cert_to_test.crt: OK

---
## Cert misc. operations
### for extracting signature bit string

openssl x509 -text -noout -in ca_crt_test.pem -certopt ca_default -certopt no_serial -certopt no_subject -certopt no_validity -certopt no_extensions -certopt no_signame |  grep -v 'Signature Algorithm' | tr -d '[:space:]' | xxd -r -p > ca_crt_test_sig.bin

xxd ca_crt_test_sig.bin

### for extracting public key from x509 certificate

openssl x509 -in ca_crt_test.pem -noout -pubkey > ca_pubkey_test.pem

### for decrypted / unpadding signature

openssl rsautl -verify -inkey ca_pubkey_test.pem -in ca_crt_test_sig.bin  -pubin  > ca_crt_test_sig_decrypted.bin

xxd ca_crt_test_sig_decrypted.bin

## AES encryption
* encryption using AES 128-bit with CBC (cipher-block chaining)

openssl  aes-128-cbc  -e -K e572e12af942e78d9c2ab2bc8f137d86  -iv 152a1c871599356bd658617791d3d801 \
      -in  /path/to/origin_file  -out /path/to/processed_file

* to decrypt the encrypted file, replace `-e` with `-d`
* The raw key option `-K` indicates hex string of 16 octets (16 x 8 = 128 bits)
* `-iv` (initialization vector) is required if `-K` is specified

## TLS connection
OpenSSL provides a test utility `s_client` acting as frontend client initiating TLS handshake to any server. The examples in this section demonstrates how `s_client` works in TLS v1.3 protocol.

### The first handshake

openssl s_client -CAfile /PATH/TO/CERTS/CA.crt   -tls1_3 -state  -sess_out /PATH/TO/OUTPUT/SESSION-PARAM.pem \
    -keylogfile=/PATH/TO/key-log-file.txt  -connect localhost:1234

Note:
- Certificate specified by `-CAfile` is usuaully required if there's no pre-shared key specified, it can also specify path to self-signed CA.
- `-keylogfile` indicates path to a [key log](https://firefox-source-docs.mozilla.org/security/nss/legacy/key_log_format/index.html) file which records per-session secrets (pre-master secrets) for other analysis tools, for example, debug and decrypt TLS traffic in [wireshark](https://en.wikipedia.org/wiki/Wireshark).
- also note this option has been introduced since openssl 1.1.1, does not work in older version.
- if the handshake is done successfully, `-sess_out` can be used to save the session, in case the server responds with a post-handshake message named [`NewSessionTicket`](https://www.rfc-editor.org/rfc/rfc8446#section-4.6.1) (also encrypted).
- the content of the saved session file depends on your TLS version, for example in TLS 1.3, it includes pre-shared key / ticket data. See [View a saved session file](#view-a-saved-session-file) below.
- `-brief` option can also be added, to reduce logging message printed (e.g. certificate and ssl-session data, see below).

The possible logging message would be :

CONNECTED(00000005)
SSL_connect:before SSL initialization
SSL_connect:SSLv3/TLS write client hello
SSL_connect:SSLv3/TLS write client hello
SSL_connect:SSLv3/TLS read server hello
SSL_connect:TLSv1.3 read encrypted extensions
depth=1 C = TW, O = CA organization, CN = app_tester_ca
verify return:1
depth=0 C = SG, O = Service Provider, CN = app_tester
verify return:1
SSL_connect:SSLv3/TLS read server certificate
SSL_connect:TLSv1.3 read server certificate verify
SSL_connect:SSLv3/TLS read finished
SSL_connect:SSLv3/TLS write change cipher spec
SSL_connect:SSLv3/TLS write finished
---
Certificate chain
 0 s:C = SG, O = Service Provider, CN = app_tester
   i:C = TW, O = CA organization, CN = app_tester_ca
---
Server certificate
-----BEGIN CERTIFICATE-----
... omit unimportant detail ...
-----END CERTIFICATE-----
subject=C = SG, O = Service Provider, CN = app_tester
issuer=C = TW, O = CA organization, CN = app_tester_ca

---
No client certificate CA names sent
Peer signing digest: SHA256
Peer signature type: RSA-PSS
Server Temp Key: X25519, 253 bits
---
SSL handshake has read 1651 bytes and written 295 bytes
Verification: OK
---
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
Server public key is 2048 bit
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 0 (ok)
---
---
Post-Handshake New Session Ticket arrived:
SSL-Session:
    Protocol  : TLSv1.3
    Cipher    : TLS_AES_256_GCM_SHA384
    Session-ID: 2CE5D25B9744186717D1C052301F9BF847D8ACC58CBA6F9BC0C64C7298A57844
    Session-ID-ctx: 
    Resumption PSK: 4FA12AE6338ADAEE76961DF2007E842EB8887A2F88577D6FD41EDE491C99B53A834557EC37E83894ABA3BC6A894735B2
    PSK identity: None
    PSK identity hint: None
    SRP username: None
    TLS session ticket lifetime hint: 420 (seconds)
    TLS session ticket:
        0000 - 8d f5 bc 45 e2 43 f5 c8-65 8b 18 ca b6 b8 ae bf   ...E.C..e.......
        0010 - 0d c4 df c2 45 2a e6 a4-19 c7 04 d9 5f 79 1a 03   ....E*......_y..
        0020 - d7 16 b9 ce 3e f8 21 34-45 06 49 cf ec 54 80 7a   ....>.!4E.I..T.z
        0030 - ee e5 96 e7 80 9d f6 5f-14 56 ae cb f9 40 3f 54   ......._.V...@?T
        .... omit unimportant data ....
---
SSL_connect:SSLv3/TLS read server session ticket
read R BLOCK
SSL_connect:SSL negotiation finished successfully

Note:
- the first time is usually a full TLS handshake, as shown in the logging message above, server sends `ServerHello`, `Certificate`, `CertificateVerify`, and `Finish` at the end of the handshake, and client has to verify server's certificate (see [Figure 1 of section 2, RFC8446](https://www.rfc-editor.org/rfc/rfc8446#section-2))
- the line `Verification: OK` and `Verify return code: 0 (ok)` indicates the result of certificate verification
- the line `New, TLSv1.3, Cipher is XXX` indicates current handshake will create a new session
- **TODO**, figure out what new session means, does openssl internally maintain valid TLS sessions for later reuse ?
- the line `Post-Handshake xxx` means the server might send other messages after handshake is done successfully , in this example, it is `NewSessionTicket`

#### Optional client certificate verification (two-way authentication)
- server may send `CertificateRequest` to ask for client's ceritificate, in order to check identity.
- the client ceritificate in such case does NOT have to be CA cert, it can also be signed by another CA cert that is different from the one for server cert

### Subsequent handshakes
once the session file is saved, you can reuse it for subsequent TLS handshakes to the same host/port by the expiry time

openssl  s_client -noservername -sess_in /PATH/TO/OUTPUT/SESSION-PARAM.pem \
     -sess_out  /PATH/TO/OUTPUT/SESSION-PARAM.pem \
     -keylogfile=/PATH/TO/key-log-file.txt  -tls1_3  -state  -connect localhost:1234

Note
- `s_client` read saved session file from the path specified by `-sess_in`
- `-sess_out` and `-sess_in` can point to the same path, the saved session file will be overwritten if the handshake is done successfully.

The logging message would be :

CONNECTED(00000005)
SSL_connect:before SSL initialization
SSL_connect:SSLv3/TLS write client hello
SSL_connect:SSLv3/TLS write client hello
SSL_connect:SSLv3/TLS read server hello
SSL_connect:TLSv1.3 read encrypted extensions
SSL_connect:SSLv3/TLS read finished
SSL_connect:SSLv3/TLS write change cipher spec
SSL_connect:SSLv3/TLS write finished
..... omit because nothing changed .......  
---
SSL handshake has read 241 bytes and written 582 bytes
Verification: OK
---
Reused, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
Server public key is 2048 bit
Secure Renegotiation IS NOT supported
..... omit because nothing changed .......  

Note:
- it is as similar as the first handshake, except it doesn't have to go through a full handshake.
- if the server is able to recognize the pre-shared key in the session file `/PATH/TO/OUTPUT/SESSION-PARAM.pem`, it will skip certificate verification flow and go straight to `EncryptedExtensions` and final `Finished` message.
- the line `Reused, TLSv1.3, Cipher is XXX` indicates current handshake resumes previous TLS session.
- **TODO**, does openssl internally maintain valid TLS sessions for later reuse ?

### View a saved session file
To dump detail in a saved session file, use subcommand `sess_id`

openssl sess_id -in  /PATH/TO/OUTPUT/SESSION-PARAM.pem -text -noout

The format of the detail looks like following :

SSL-Session:
    Protocol  : TLSv1.3
    Cipher    : TLS_AES_256_GCM_SHA384
    Session-ID: 46A0F9AA7121168807CDBCDCE4CD49AADCBEC567D1DF2A5857E0B16F66649429
    Session-ID-ctx: 
    Resumption PSK: 82A5CFE907CFBAF40468901CC6F18AEA829DE3C6D1299FD011AEF9498A111546CA41CC1B4F36A473D3A5953884BF687D
    PSK identity: None
    PSK identity hint: None
    SRP username: None
    TLS session ticket lifetime hint: 420 (seconds)
    TLS session ticket:
    0000 - bc 3a 21 03 c3 13 c2 15-6f 08 a5 cb 2e f4 95 68   .:!.....o......h
    0010 - 53 b4 ef 5c 34 46 b4 f1-5c 1b f3 dc 3a ca 4b 81   S..\4F..\...:.K.
    0020 - 73 62 cb 34 86 97 33 28-f1 3f 5e 56 9b a8 e7 03   sb.4..3(.?^V....
    0030 - c3 3b 44 8e 21 a4 ce b3-70 21 47 b9 ac da 02 ff   .;D.!...p!G.....
    ......... << omit rest of bytes >> ........

    Start Time: 1676815357
    Timeout   : 7200 (sec)
    Verify return code: 0 (ok)
    Extended master secret: no
    Max Early Data: 0

Note:
- the concept of *session ID* and *session tickets(RFC5077)* is obsolete in TLS 1.3
- the field `Session-ID` is unlikely useful anymore
- TODO, figure out what exactly `Resumption PSK` field means in openssl, where is it used in the entire TLS handshake ?
- the field `TLS session ticket` contains octets which will be copied to `PskIdentity` field in the [pre-shared key extension](https://www.rfc-editor.org/rfc/rfc8446#section-4.2.11) of `ClientHello` message (for subsequent handshakes)
- the name of the field `TLS session ticket` is confusing, as the *session tickets(RFC5077)* is obsolete.
- the field `PSK identity` is just a label, it is optional and can be empty.
- the field `TLS session ticket lifetime hint` means expiry time in seconds since the session was generated last time, in this example it is 420 seconds.
- another utility `s_client` can also dump the TLS session detail, without the option `-brief`

## Reference
- [What role do hashes play in TLS/SSL certificate validation? -- Stack Exchange](https://security.stackexchange.com/a/67575/214639)
- [Missing X509 extensions with an openssl-generated certificate -- Stack Exchange](https://security.stackexchange.com/q/150078/214639)
- [Verify SSL/TLS Certificate Signature -- kulkarniamit](https://kulkarniamit.github.io/whatwhyhow/howto/verify-ssl-tls-certificate-signature.html?utm_source=chatgpt.com)
- [Tencent Cloud -- SSL One-Way Authentication and Mutual Authentication](https://www.tencentcloud.com/document/product/214/39990)