0
# CLI Usage
1

2
Command-line tool for dumping and analyzing ASN.1 structures from files or data URIs with colored output and RFC definition matching.
3

4
## Capabilities
5

6
### Command Line Interface
7

8
The `dumpASN1` command provides a powerful CLI tool for analyzing ASN.1 structures with colored terminal output and automatic definition matching.
9

10
```bash { .api }
11
# Install and use via npx (recommended)
12
npx @lapo/asn1js <filename|data-uri>
13

14
# If installed globally
15
dumpASN1 <filename|data-uri>
16

17
# Local execution (if you have the source)
18
./dumpASN1.js <filename|data-uri>
19
```
20

21
**Usage Examples:**
22

23
```bash
24
# Analyze a certificate file
25
npx @lapo/asn1js certificate.crt
26

27
# Analyze a private key
28
npx @lapo/asn1js private-key.der
29

30
# Analyze from data URI
31
npx @lapo/asn1js "data:base64,MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA..."
32

33
# Analyze PEM file
34
npx @lapo/asn1js server.pem
35

36
# Analyze any binary ASN.1 file
37
npx @lapo/asn1js structure.asn1
38
```
39

40
### Input Format Support
41

42
The CLI tool automatically detects and handles multiple input formats:
43

44
- **Binary files**: Raw ASN.1 DER/BER encoded files
45
- **PEM files**: Files with `-----BEGIN ... -----END` armoring
46
- **Data URIs**: `data:base64,<base64-data>` format for inline data
47
- **Base64 files**: Files containing raw base64 encoded ASN.1 data
48

49
```bash
50
# Examples of different file types it can handle
51
npx @lapo/asn1js certificate.crt     # X.509 certificate
52
npx @lapo/asn1js private.key         # Private key file
53
npx @lapo/asn1js public.pem          # PEM-encoded public key
54
npx @lapo/asn1js csr.der             # Certificate signing request
55
npx @lapo/asn1js ca-bundle.pem       # Certificate bundle
56
npx @lapo/asn1js timestamp.tsr       # Timestamp response
57
npx @lapo/asn1js signed.p7s          # PKCS#7 signed data
58
```
59

60
### Output Features
61

62
The CLI tool provides rich formatted output with the following features:
63

64
#### Colored Terminal Output
65

66
- **Type names**: Highlighted in yellow for easy identification
67
- **Element names**: Definition names in blue when matched against RFC definitions
68
- **Position markers**: Shows byte positions for debugging
69
- **Content preview**: Formatted content display with proper encoding
70

71
#### Structure Analysis
72

73
- **Hierarchical display**: Indented tree structure showing ASN.1 nesting
74
- **Position information**: Byte offsets for each element (`@position+length`)
75
- **Construction indicators**: Shows whether elements are constructed or primitive
76
- **Encapsulation detection**: Identifies when OCTET_STRING or BIT_STRING contain nested ASN.1
77

78
#### RFC Definition Matching
79

80
- **Automatic matching**: Attempts to match structures against known RFC definitions
81
- **Common structure recognition**: Identifies certificates, keys, signatures, etc.
82
- **Definition names**: Shows standardized names for recognized structures
83
- **Confidence scoring**: Indicates how well the structure matches known patterns
84

85
### Example Output
86

87
```bash
88
$ npx @lapo/asn1js certificate.crt
89

90
SEQUENCE @0+1234 (constructed)
91
  SEQUENCE @4+954 (constructed): tbsCertificate
92
    [0] @8+3 (constructed): version
93
      INTEGER @10+1: 2
94
    INTEGER @13+20: serialNumber
95
      01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67
96
    SEQUENCE @35+13 (constructed): signature
97
      OBJECT_IDENTIFIER @37+9: 1.2.840.113549.1.1.11 | sha256WithRSAEncryption
98
      NULL @48+0
99
    SEQUENCE @50+156 (constructed): issuer
100
      SET @52+31 (constructed)
101
        SEQUENCE @54+29 (constructed)
102
          OBJECT_IDENTIFIER @56+3: 2.5.4.6 | countryName
103
          PrintableString @61+2: US
104
      SET @85+45 (constructed)
105
        SEQUENCE @87+43 (constructed)
106
          OBJECT_IDENTIFIER @89+3: 2.5.4.10 | organizationName
107
          UTF8String @94+36: Example Organization
108
    ...
109
  SEQUENCE @960+13 (constructed): signatureAlgorithm  
110
    OBJECT_IDENTIFIER @962+9: 1.2.840.113549.1.1.11 | sha256WithRSAEncryption
111
    NULL @973+0
112
  BIT_STRING @975+257 (encapsulates): signatureValue
113
    00:A1:B2:C3:D4:E5:F6:07:18:29:3A:4B:5C:6D:7E:8F:90:...
114
```
115

116
### Advanced Usage Patterns
117

118
#### Processing Multiple Files
119

120
```bash
121
# Process multiple certificates
122
find /etc/ssl/certs -name "*.pem" -exec npx @lapo/asn1js {} \;
123

124
# Compare two certificates
125
npx @lapo/asn1js cert1.pem > cert1.dump
126
npx @lapo/asn1js cert2.pem > cert2.dump
127
diff cert1.dump cert2.dump
128
```
129

130
#### Integration with Other Tools
131

132
```bash
133
# Extract certificate from TLS connection and analyze
134
echo | openssl s_client -connect example.com:443 2>/dev/null | \
135
  openssl x509 -outform DER | \
136
  base64 | \
137
  xargs -I {} npx @lapo/asn1js "data:base64,{}"
138

139
# Analyze certificate chain
140
openssl s_client -connect example.com:443 -showcerts 2>/dev/null | \
141
  awk '/BEGIN CERT/,/END CERT/' | \
142
  npx @lapo/asn1js
143

144
# Create and analyze a CSR
145
openssl req -new -key private.key -out request.csr -subj "/CN=example.com"
146
npx @lapo/asn1js request.csr
147
```
148

149
#### Error Handling and Debugging
150

151
The CLI tool provides detailed error messages for common issues:
152

153
```bash
154
# File not found
155
$ npx @lapo/asn1js nonexistent.crt
156
Error: Cannot read file 'nonexistent.crt'
157

158
# Invalid ASN.1 structure
159
$ npx @lapo/asn1js invalid.txt
160
Error: Invalid ASN.1 structure at position 0
161

162
# Corrupted data
163
$ npx @lapo/asn1js corrupted.der
164
Error: Container at offset 45 has a length of 1000, which is past the end of the stream
165
```
166

167
### Output Redirection and Processing
168

169
```bash
170
# Save analysis to file
171
npx @lapo/asn1js certificate.crt > analysis.txt
172

173
# Extract specific information using grep
174
npx @lapo/asn1js certificate.crt | grep "OBJECT_IDENTIFIER"
175

176
# Count different ASN.1 types
177
npx @lapo/asn1js certificate.crt | grep -o '\w\+String\|INTEGER\|SEQUENCE\|SET' | sort | uniq -c
178

179
# Find all OIDs in a structure
180
npx @lapo/asn1js certificate.crt | grep "OBJECT_IDENTIFIER" | cut -d: -f2 | cut -d'|' -f1
181
```
182

183
### Performance Considerations
184

185
The CLI tool is optimized for:
186

187
- **Large files**: Efficiently handles large ASN.1 structures (multi-MB certificate bundles)
188
- **Memory usage**: Uses streaming approach to minimize memory footprint
189
- **Speed**: Fast parsing and analysis even for complex nested structures
190

191
```bash
192
# Analyze large certificate bundle
193
npx @lapo/asn1js ca-bundle.pem  # Works efficiently even with 100+ certificates
194

195
# Process very large ASN.1 file
196
npx @lapo/asn1js large-structure.der  # Handles files up to several MB
197
```
198

199
### Integration Examples
200

201
#### Shell Scripts
202

203
```bash
204
#!/bin/bash
205
# Certificate validation script
206
CERT_FILE="$1"
207

208
if [ ! -f "$CERT_FILE" ]; then
209
  echo "Certificate file not found: $CERT_FILE"
210
  exit 1
211
fi
212

213
echo "Analyzing certificate: $CERT_FILE"
214
npx @lapo/asn1js "$CERT_FILE"
215

216
# Extract subject name
217
SUBJECT=$(npx @lapo/asn1js "$CERT_FILE" | grep -A5 "subject" | grep "UTF8String\|PrintableString" | head -1)
218
echo "Subject: $SUBJECT"
219
```
220

221
#### Python Integration
222

223
```python
224
import subprocess
225
import sys
226

227
def analyze_asn1(file_path):
228
    """Analyze ASN.1 file using @lapo/asn1js CLI tool"""
229
    try:
230
        result = subprocess.run(
231
            ['npx', '@lapo/asn1js', file_path],
232
            capture_output=True,
233
            text=True,
234
            check=True
235
        )
236
        return result.stdout
237
    except subprocess.CalledProcessError as e:
238
        return f"Error: {e.stderr}"
239

240
# Usage
241
analysis = analyze_asn1('certificate.crt')
242
print(analysis)
243
```