STIR-SHAKEN: Additional config params and more certificate info

Author: gtjoseph

docs/Deployment/STIR-SHAKEN/index.md

@@ -65,13 +65,13 @@ Although [RFC-8226 section 9](https://www.rfc-editor.org/rfc/rfc8226#section-9)
 shall contain a single SPC value.".  Asterisk therefore will fail to verify a certificate whose TNAuthList extension contains something other than an SPC code.
 
 It was apparently envisioned that a facility would be made available to verify that a particular SPC has the authority over a particular telephone number.  To our knowledge, that facility doesn't yet exist.  This means that there is currently no way for Asterisk to verify that the SPC in the certificate has the authority over the TN in the Identity header.
-
 ///
+
 ## Asterisk Implementation
 
 ### Configuration
 
-All configuration is done via the stir_shaken.conf file.  The sample [stir_shaken.conf](stir_shaken.conf) is heavily commented.
+All configuration is done via the stir_shaken.conf file.  The sample [stir_shaken.conf](https://github.com/asterisk/asterisk/raw/master/configs/samples/stir_shaken.conf.sample) is heavily commented.
 
 There are 4 object types used by the STIR/SHAKEN process...
 
@@ -279,38 +279,84 @@ CA certififcate to you separately.
 Default: no
 
 ##### ca_file 
-Path to a single file containing a CA certificate or certificate chain
-to be used to validate the certificates in incoming requests.
+Path to a file containing one or more CA certs in PEM format.
+These certs are used to verify the chain of trust for the
+certificate retrieved from the X5U Identity header parameter.  This
+file must have the root CA certificate, the certificate of the
+issuer of the X5U certificate, and any intermediate certificates
+between them.
 
 Default: none
+See Also: [Certificate and CRL Notes](#certificate-and-crl-notes) below
 
 ##### ca_path 
-Path to a directory containing one or more CA certificates to be used
-to validate the certificates in incoming requests.  The files in that
-directory must contain only one certificate each and the directory
-must be hashed using the OpenSSL 'c_rehash' utility.
+Path to a directory containing one or more hashed CA certs.
+See ca_file above.
+For this option, each certificate must be placed in its own
+PEM file in the directory specified and hashed with the
+following command:
+`openssl rehash <ca_path>`
 
-Default: none
+Default: none  
+See Also: [Certificate and CRL Notes](#certificate-and-crl-notes) below
 
 NOTE:  Both ca_file and ca_path can be specified but at least one
 MUST be.
 
 ##### crl_file 
-Path to a single file containing a CA certificate revocation list
-to be used to validate the certificates in incoming requests.
+Path to a file containing one or more CRLs in PEM format.
+If you with to check if the certificate in the X5U Identity header
+parameter has been revoked, you'll need the certificate revocation
+list generated by the issuer.  NOTE: CRLs are sometimes distributed
+in DER format instead of PEM format.  You can covert a DER file to
+PEM with the folowing command:  
+`openssl crl -inform DER -in crl.der -outform PEM -out crl.pem`
 
-Default: none
+Default: none  
+See Also: [Certificate and CRL Notes](#certificate-and-crl-notes) below
 
 ##### crl_path 
-Path to a directory containing one or more CA certificate revocation
-lists to be used to validate the certificates in incoming requests.
-The files in that directory must contain only one certificate each and
-the directory must be hashed using the OpenSSL 'c_rehash' utility.
+Path to a directory containing one or more hashed CRLs.
+See crl_file above.
+For this option, each CRL must be placed in its own
+PEM file in the directory specified and hashed with the
+following command:  
+`openssl rehash <crl_path>`
 
-Default: none
+Default: none  
+See Also: [Certificate and CRL Notes](#certificate-and-crl-notes) below
 
 NOTE:  Neither crl_file nor crl_path are required.
 
+##### untrusted_cert_file
+Path to a file containing one or more untrusted certs in PEM format.
+Unfortunately, sometimes the CRLs are signed by a different CA
+than the certificate being verified.  In this case, you'll need to
+provide the certificate belonging to the issuer of the CRL.  That
+certificate is considered "untrusted" by OpenSSL and can't be placed
+in the ca_file or ca_path.  It has to be specified here.
+
+Default: none  
+See Also: [Certificate and CRL Notes](#certificate-and-crl-notes) below.  
+Added in Asterisk releases 18.25.0, 20.10.0, 21.5.0, certified-20.7-cert2
+
+##### untrusted_cert_path
+Path to a directory containing one or more hashed untrusted certs used
+to verify CRLs.
+See untrusted_cert_file above.
+For this option, each certificates must be placed in its own
+PEM file in the directory specified and hashed with the
+following command:  
+`openssl rehash <ca_path>`
+
+Default: none  
+See Also: [Certificate and CRL Notes](#certificate-and-crl-notes) below.  
+Added in Asterisk releases 18.25.0, 20.10.0, 21.5.0, certified-20.7-cert2
+
+NOTE:  Neither untrusted_cert_file nor untrusted_cert_path are required
+unless you're verifying CRLs that aren't signed by the same CA as the
+X5U certificate.
+
 ##### cert_cache_dir 
 Incoming Identity headers will have a URL pointing to the certificate
 used to sign the header.  To prevent us from having to retrieve the
@@ -575,6 +621,140 @@ Compared to verification, attestation is simple.
 1. If there's no "tn" object matching the caller-id, skip attestation and continue the call. With the 18.23.0, 20.8.0 and 21.3.0 releases of Asterisk, the caller-id is canonicalized (everything except 0-9, # and * are removed) before a "tn" object is searched for.  Previously, the caller-id had to match the "tn" id exactly so a caller-id of "+1234567890" would NOT match a "tn" id of "1234567890".
 1. Finally create and sign the Identity header using the `private_key_file`, `public_cert_url`, `attest_level` and `send_mky` parameters from [tn](#tn-object), [profile](#profile-object) or [attestation](#attestation-object).  If this fails, the call will be terminated.
 
+## Certificate and CRL Notes
+
+Verifying the certificate retrieved by following the link in the received
+X5U Identity header parameter can be a tricky business.  At a mimimum, you'll
+need the certificate of the X5U certificate's issuer.  If the X5U certificate
+was signed by an intermediate certificate authority, you'll need that certificate
+plus any others up the chain to the issuer's root certificate authority.
+If you plan on verifying whether the X5U certificate has been revoked or not,
+you'll need the issuer's certificate revokation list and if the CRL was not
+signed by the same CA chain as the X5U certificate, you'll need the chain
+for the CRL as well.
+
+If the X5U certificate was produced by an entity that knows how to 
+properly set up and operate a PKI infrastructure, there are some easy
+steps you can take to find those certificates yourself.  If not, you
+are unfortunately at their mercy to provide you with the proper files.
+anyway...
+
+A properly constructed X5U certificate will have two X509 extensions
+that can help you get the issuer's certificate and, optionally, a CRL.
+If you have the URI in the X5U Identity header parameter, you can use
+`curl` to retrieve it manually...
+
+```
+curl -o somecompany-x5u.pem https://somecompany.com/somecert.pem
+```
+
+You can now dump the contents of the certificate with `openssl`...
+
+```
+openssl x509 -in somecompany-x5u.pem -noout -text
+Certificate:
+    <snipped>
+    Issuer: CN=STO CA1 - SHAKEN Intermediate, O=Some Telecom Operator, OU=Certificate Authority, C=US
+    <snipped>
+    X509v3 extensions:
+      Authority Information Access: 
+        CA Issuers - URI:https://somecomnany.com/ca/certs/intermediate-ca.cer
+      X509v3 CRL Distribution Points: 
+        Full Name:
+          URI:https://somecompany.com/crl                CRL Issuer:
+          DirName:CN = STO PA1, O = Some Telecom Operator, OU = Policy Authority, C = US
+```
+You'll notice a few things...
+* The issuer is an intermediate certificate authority.
+* The `Authority Information Access` extension has a URI to the intermediate CA's certificate.
+* There's a `CRL Distribution Points` extension with a URI to the CRL.  This may or may not be present.
+* The CRL issuer isn't the same as this certificate's issuer.  This is known as an "Indirect CRL".  It's rare but it can happen.
+
+So, now it's a matter of following those URIs, dumping the objects,
+and repeating until you reach the top.
+
+```
+curl -o intermediate1-ca.pem https://somecomnany.com/ca/certs/intermediate1-ca.cer
+openssl x509 -in intermediate1-ca.pem -noout -text
+```
+Look for intermediate-ca.cer's `Authority Information Access` extension,
+download it, dump it, and repeat until you find the root CA certificate.
+You'll know it because its Issuer and Subject will be the same and there
+won't be a `Authority Information Access` extension.  All of these certificates
+will need to be supplied in either [verification - ca_file](#ca_file) or
+[verification - ca_path](#ca_path).
+
+If there was a CRL specified and you wish to check whether the X5U
+certificate was revoked or not, download and dump the CRL.
+
+```
+curl -o somecompany.crl https://somecompany.com/crl
+openssl crl -in somecompany.crl -noout -text
+```
+
+The CRL should also have an `Authority Information Access` extension that has
+the URI to the CRL issuer's certificate.  If it's not the same as any of
+the certificates already retrieved by the above process, perform the same
+download and dump process as above until you get to the root CA certificate.
+Any of these certificates that weren't already retrieved above will need to be
+supplied in either [verification - untrusted_cert_file](#untrusted_cert_file) or
+[verification - untrusted_cert_path](#untrusted_cert_path).
+
+The CRL itself will need to be supplied in either [verification - crl_file](#crl_file) or [verification - crl_path](#crl_path).  Be aware though, some CRLs are
+distributed in DER format instead of PEM format.  You can check which format
+was retrieved by running `file <crl_file>`.  If the result is `ASCII text`, it's 
+already PEM format.  If the result is `data`, it's DER format.  Since asterisk can only
+accept PEM format files, you'll need to convert the DER CRL into PEM format
+with the following command:
+
+```
+openssl crl -inform DER -in somecompany.crl -outform PEM -out somecompany-crl.pem
+```
+
+You can test that you have all the files needed for a successful verification
+by performing the following...
+
+Concatenate all the CA certificates downloaded into a single file.
+
+```
+cat intermediate1-ca.pem intermediate2-ca.pem root-ca.pem > somecompany-fullchain.pem
+```
+
+Concatenate all the untrusted certificates downloaded into a single file.
+Don't include any CA certificates already downloaded previously.
+
+```
+cat untrusted1-ca.pem untrusted2-ca.pem untrusted-ca.pem > somecompany-untrusted.pem
+```
+
+Run the `openssl verify` command.
+
+```
+openssl verify -CAfile somecompany-fullchain.pem -CRLfile somecompany-crl.pem \
+  -untrusted somecompany-untrusted.pem -crl_check -extended_crl somecert-x5u.pem
+somecert-x5u.pem: OK
+```
+
+If you're not checking against a CRL, you can leave those bits out...
+
+```
+openssl verify -CAfile somecompany-fullchain.pem somecert-x5u.pem
+somecert-x5u.pem: OK
+```
+
+You can use the same somecompany-fullchain.pem, somecompany-crl.pem,
+and somecompany-untrusted.pem file as the values for the 
+[verification - ca_file](#ca_file), [verification - crl_file](#crl_file)
+and [verification - untrusted_cert_file](#untrusted_cert_file)
+stir_shaken.conf values.
+
+Starting in Asterisk versions, 18.25.0, 20.10.0, 21.5.0 and certified-20.7-cert2,
+a new CLI command `stir_shaken verify certificate_file` is available.  If you've properly
+configured the ca, crl and untrusted_cert parameters in stir_shaken.conf, you can
+check if Asterisk can verify a certificate with the following command:  
+`CLI> stir_shaken verify certificate_file <path_to_cert_file>`.  
+You'll get the same results you'd get with the `openssl verify` command.
+
 ## References
 
 The best places to become familiar with STIR/SHAKEN itself are: