Merge pull request #1 from wllm-rbnt/improvements

Env var support + multi root unwrap merge

Author: wllm-rbnt

EXAMPLES.md

@@ -4,24 +4,24 @@
 
 Take an arbitrary DER encoded certificate:
 
-```bash
+```console
 $ wget -o /dev/null https://pki.goog/repo/certs/gtsr1.der
 ```
 
 Convert it to an ASN1_generate_nconf(3) compatible textual description:
 
-```bash
+```console
 $ ./asn1template.pl gtsr1.der > gtsr1.tpl
 ```
 
 Convert it back to DER encoded ASN.1 with ASN1_generate_nconf(3):
 
-```bash
+```console
 $ openssl asn1parse -genconf gtsr1.tpl -noout -out gtsr1_new.der
 ```
 
 Original and recreated DER files are identical:
-```bash
+```console
 $ diff gtsr1.der gtsr1_new.der 
 $ echo $?
 0
@@ -34,17 +34,17 @@ https://github.com/drago-96/CVE-2022-0778 and this particular PR
 https://github.com/drago-96/CVE-2022-0778/pull/4 .
 
 Following the details presented in https://github.com/drago-96/CVE-2022-0778/pull/4 , first, generate a new EC private key:
-```bash
+```console
 $ openssl ecparam -out ec.key -name prime256v1 -genkey -noout -param_enc explicit -conv_form compressed
 ```
 
 Then use it to generate a self signed certificate:
-```bash
+```console
 $ openssl req -new -x509 -key ec.key -out cert.der -outform DER -days 360 -subj "/CN=TEST/"
 ```
 
 We can then generate a template from this certificate:
-```bash
+```console
 $ ./asn1template.pl cert.der > cert.tpl
 $ cat cert.tpl
 asn1 = SEQUENCE:seq1@0-4-583
@@ -123,7 +123,7 @@ field51@503-2-8 = OBJECT:ecdsa-with-SHA256
 ```
 
 Change some of the values in the template according to https://github.com/drago-96/CVE-2022-0778 and https://github.com/drago-96/CVE-2022-0778/pull/4 :
-```bash
+```console
 $ diff -u cert.tpl cert_new.tpl
 --- cert.tpl	2022-08-18 15:42:00.593000000 +0200
 +++ cert_new.tpl	2022-08-18 15:44:01.220000000 +0200
@@ -146,13 +146,13 @@ $ diff -u cert.tpl cert_new.tpl
 ```
 
 Then convert the template back to DER encoded ASN.1:
-```bash
+```console
 $ openssl asn1parse -genconf cert_new.tpl -noout -out cert_new.der
 
 ```
 
 Finally, try to display this certificate with a CVE-2022-0778 vulnerable OpenSSL installation:
-```bash
+```console
 $ openssl x509 -inform DER -in cert_new.der -noout -text
 ```
 
@@ -161,7 +161,7 @@ $ openssl x509 -inform DER -in cert_new.der -noout -text
 It works on certificates, but, more generally, on arbitrary DER encoded ASN.1
 blobs. Here is the same as example #1 but with a CRL file:
 
-```bash
+```console
 $ wget -o /dev/null https://crl.pki.goog/gtsr1/gtsr1.crl
 $ ./asn1template.pl gtsr1.crl > gtsr1.tpl
 $ openssl asn1parse -genconf gtsr1.tpl -noout -out gtsr1_new.crl
@@ -172,7 +172,7 @@ $ echo $?
 
 Or with an smime.p7s email signature taken from https://datatracker.ietf.org/doc/html/rfc4134 (page 87):
 
-```bash
+```console
 $ cat <<EOF > smime.p7s.base64
 MIIDdwYJKoZIhvcNAQcCoIIDaDCCA2QCAQExCTAHBgUrDgMCGjALBgkqhkiG9w0BBwGgggL
 gMIIC3DCCApugAwIBAgICAMgwCQYHKoZIzjgEAzASMRAwDgYDVQQDEwdDYXJsRFNTMB4XDT
@@ -204,29 +204,29 @@ $ echo $?
 
 It also works with PEM files:
 
-```bash
+```console
 $ wget -o /dev/null https://pki.goog/repo/certs/gtsr1.pem
 ```
 
 Convert it to an ASN1_generate_nconf(3) compatible textual description:
 
-```bash
+```console
 $ ./asn1template.pl --pem gtsr1.pem > gtsr1.tpl
 ```
 
 Convert it back to DER encoded ASN.1 with ASN1_generate_nconf(3):
 
-```bash
+```console
 $ openssl asn1parse -genconf gtsr1.tpl -noout -out gtsr1_new.der
 ```
 
 Then back to PEM:
-```bash
+```console
 $ openssl x509 -inform DER -in gtsr1_new.der -outform PEM -out gtsr1_new.pem
 ```
 
 Original and recreated PEM files are identical:
-```bash
+```console
 $ diff gtsr1.pem gtsr1_new.pem
 $ echo $?
 0
@@ -236,23 +236,23 @@ $ echo $?
 Let's consider the following configuration template that contains an explicit
 tag definition:
 
-```bash
+```console
 $ cat test.tpl
 asn1 = SEQUENCE:seq1
 [seq1]
 field1 = EXPLICIT:0A,IA5STRING:Hello World
 ```
 
 We can generate the corresponding DER encoded file:
-```bash
+```console
 $ openssl asn1parse -genconf test.tpl -out test.der
     0:d=0  hl=2 l=  15 cons: SEQUENCE          
     2:d=1  hl=2 l=  13 cons: appl [ 0 ]        
     4:d=2  hl=2 l=  11 prim: IA5STRING         :Hello World
 ```
 
 The DER encoded file can be read with the asn1parse OpenSSL app:
-```bash
+```console
 $ openssl asn1parse -in test.der -i -inform D
     0:d=0  hl=2 l=  15 cons: SEQUENCE          
     2:d=1  hl=2 l=  13 cons:  appl [ 0 ]        
@@ -263,7 +263,7 @@ We can see the entry point sequence (seq1) followed by a tagged sequence (appl
 [ 0 ]) containing the IA5STRING.
 
 The template can then be extracted from the DER encoded file:
-```bash
+```console
 $ ./asn1template.pl test.der | tee test2.tpl
 asn1 = SEQUENCE:seq1@0-2-15
 [seq1@0-2-15]
@@ -274,7 +274,7 @@ field3@4-2-11 = IA5STRING:"Hello\ World"
 We can see that the explicit tag has been replaced by an implicitly tagged sequence (seq2).
 
 This template can finally be used to generate the associated DER encode file:
-```bash
+```console
 $ openssl asn1parse -genconf test2.tpl -out test2.der 
     0:d=0  hl=2 l=  15 cons: SEQUENCE          
     2:d=1  hl=2 l=  13 cons: appl [ 0 ]        
@@ -284,7 +284,7 @@ $ openssl asn1parse -genconf test2.tpl -out test2.der
 Both DER encoded files are identical. ```test.der``` originates from a
 configuration template with an explicit tag, ```test2.der``` originates from an
 equivalent configuration template containing an implicit tag:
-```bash
+```console
 $ diff test.der test2.der
 $ echo $?
 0

README.md

@@ -8,7 +8,7 @@ textual description that can be edited and later be fed to OpenSSL's
 encoded ASN.1 structure.
 The code is written in Perl with minimal dependencies. No compilation required.
 
-```
+```console
 $ git clone https://github.com/wllm-rbnt/asn1template.git
 $ cd asn1template
 $ ./asn1template.pl -h
@@ -19,14 +19,17 @@ Default input file format is DER, use --pem (or -p) option to switch to PEM
 Use --multi-root (or -m) option to process multiple concatenated structures from a single input file
 Use --simple-labels (or -s) option to use simple numeric labels
 Use --help (or -h) to print this help message
+
+Remove/Unwrap top-level SEQUENCE, use --pem (or -p) option to switch to PEM
+	./asn1template.pl [--pem|-p] [--unwrap|-u] <encoded_file>
 ```
 
 Here is an example of usage. First, let's convert a PEM encoded certificate to
 a textual representation supported by ```ASN1_generate_nconf(3)```. The
 certificate we use in this example is a root CA certificate from Amazon. On
 Debian, it belongs to the ```ca-certificates``` package.
 
-```
+```console
 $ ./asn1template.pl --pem /etc/ssl/certs/Amazon_Root_CA_3.pem | tee Amazon_Root_CA_3.tpl
 asn1 = SEQUENCE:seq1@0-4-438
 [seq1@0-4-438]
@@ -125,13 +128,13 @@ convert this template back to its original form using
 ```ASN1_generate_nconf(3)```.  This is done in 2 steps, first convert it to a
 DER encoded file, then convert this DER file to PEM format:
 
-```
+```console
 $ openssl asn1parse -genconf Amazon_Root_CA_3.tpl -out Amazon_Root_CA_3_new.der
 $ openssl x509 -in Amazon_Root_CA_3_new.der -out Amazon_Root_CA_3_new.pem -outform PEM
 ```
 
 We can see that the original file and the one we regenerated are identical:
-```
+```console
 $ diff -u /etc/ssl/certs/Amazon_Root_CA_3.pem Amazon_Root_CA_3_new.pem
 $ echo $?
 0
@@ -148,7 +151,7 @@ an internal structure that is then dumped to the equivalent
 The syntax of this textual representation is documented in the man page of
 ```ASN1_generate_nconf(3)```:
 
-```bash
+```console
 $ man 3 ASN1_generate_nconf
 ```
 
@@ -215,6 +218,32 @@ Return codes:
 - ```1```: Command line arguments error.
 - ```2```: Unparseable line encountered.
 - ```3```: Indefinite length encoding detected.
+- ```4```: Unable to unwrap top-level SEQUENCE.
+
+### Environment variables
+
+You can instruct ```asn1template.pl``` to use an alternate ```openssl``` binary
+by setting the OPENSSL environment variable.
+Note that, depending on your setup, you might want to reference or preload
+matching dynamic libraries such as ```libcrypto.so``` and ```libssl.so``` by
+setting LD_LIBRARY_PATH or LD_PRELOAD.
+
+```console
+$ export OPENSSL=/home/user/openssl-3.4.0/apps/openssl
+$ ${OPENSSL} version
+/home/user/openssl-3.4.0/apps/openssl: /lib/x86_64-linux-gnu/libssl.so.3: version `OPENSSL_3.4.0' not found (required by /home/user/openssl-3.4.0/apps/openssl)
+/home/user/openssl-3.4.0/apps/openssl: /lib/x86_64-linux-gnu/libssl.so.3: version `OPENSSL_3.2.0' not found (required by /home/user/openssl-3.4.0/apps/openssl)
+/home/user/openssl-3.4.0/apps/openssl: /lib/x86_64-linux-gnu/libcrypto.so.3: version `OPENSSL_3.3.0' not found (required by /home/user/openssl-3.4.0/apps/openssl)
+/home/user/openssl-3.4.0/apps/openssl: /lib/x86_64-linux-gnu/libcrypto.so.3: version `OPENSSL_3.4.0' not found (required by /home/user/openssl-3.4.0/apps/openssl)
+/home/user/openssl-3.4.0/apps/openssl: /lib/x86_64-linux-gnu/libcrypto.so.3: version `OPENSSL_3.2.0' not found (required by /home/user/openssl-3.4.0/apps/openssl)
+$ export LD_LIBRARY_PATH=/home/user/openssl-3.4.0
+$ ${OPENSSL} version
+OpenSSL 3.4.0 22 Oct 2024 (Library: OpenSSL 3.4.0 22 Oct 2024)
+$ ./asn1template.pl --pem /etc/ssl/certs/Amazon_Root_CA_3.pem | tee Amazon_Root_CA_3.tpl
+asn1 = SEQUENCE:seq1@0-4-438
+[seq1@0-4-438]
+[...]
+```
 
 ### Multi-root data structures
 
@@ -224,8 +253,8 @@ depth 0.
 
 Here is an example of such structure:
 
-```
-$ openssl asn1parse -in TS48\ V5.0\ eSIM_GTP_SAIP2.3_BERTLV_SUCI.der -inform D -i
+```console
+$ openssl asn1parse -in 'TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der' -inform D -i
     0:d=0  hl=3 l= 159 cons: cont [ 0 ]
 [...]
   162:d=0  hl=4 l= 775 cons: cont [ 16 ]
@@ -241,19 +270,19 @@ $ openssl asn1parse -in TS48\ V5.0\ eSIM_GTP_SAIP2.3_BERTLV_SUCI.der -inform D -
 The ```-genconf``` option of the ```asn1parse``` OpenSSL app is not able to
 generate such multi-root structures. In order to deal with this issue, the
 ```asn1template.pl``` command, with its ```--multi-root``` option, produces a
-template that wraps the concatenated structures into a top level SEQUENCE.
-This wrapping sequence can then be stripped using the ```unwrap_multiroot.pl```
-command after template edition.
+template that wraps the concatenated structures into a top-level SEQUENCE.
+This wrapping sequence can then be stripped using the ```--unwrap``` option
+after template edition.
 
 Here is a full example, based on an eSIM test file
 (coming from https://github.com/GSMATerminals/Generic-eUICC-Test-Profile-for-Device-Testing-Public/):
 
-```
-$ ./asn1template.pl --multi-root TS48\ V5.0\ eSIM_GTP_SAIP2.3_BERTLV_SUCI.der > TS48\ V5.0\ eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl
-$ openssl asn1parse -genconf TS48\ V5.0\ eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl -out TS48\ V5.0\ eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl.der
-$ ./unwrap_multiroot.pl TS48\ V5.0\ eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl.der
-Output written to file "TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl.der.unwrapped".
-$ diff TS48\ V5.0\ eSIM_GTP_SAIP2.3_BERTLV_SUCI.der TS48\ V5.0\ eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl.der.unwrapped
+```console
+$ ./asn1template.pl --multi-root 'TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der' > 'TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl'
+$ openssl asn1parse -genconf 'TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl' -out 'TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl.der'
+$ ./asn1template.pl --unwrap 'TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl.der'
+Output written to file "TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl.der.unwrapped" in DER format.
+$ diff 'TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der' 'TS48 V5.0 eSIM_GTP_SAIP2.3_BERTLV_SUCI.der.tpl.der.unwrapped'
 $ echo $?
 0
 ```
@@ -262,7 +291,7 @@ $ echo $?
 
 A mostly complete test script can be executed from project root:
 
-```
+```console
 $ ./tests/run_tests.sh
 ```