0
# Core ASN.1 Parsing
1

2
Comprehensive ASN.1 parsing capabilities that can decode any valid ASN.1 DER or BER structure with complete type support and detailed content extraction.
3

4
## Capabilities
5

6
### ASN.1 Decoder
7

8
Main decoder function that creates ASN.1 structure representations from binary data.
9

10
```javascript { .api }
11
/**
12
 * Main ASN.1 decoder function
13
 * @param stream - Stream, binary array, or string to decode
14
 * @param offset - Starting position in the data (optional, defaults to 0)
15
 * @param type - ASN1 class or subclass to use for parsing (optional, defaults to ASN1)
16
 * @returns ASN1 instance representing the parsed structure
17
 */
18
function ASN1.decode(stream: Stream | ArrayLike<number> | string, offset?: number, type?: typeof ASN1): ASN1;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
import { ASN1 } from '@lapo/asn1js';
25
import { Hex } from '@lapo/asn1js/hex.js';
26

27
// Parse from binary array
28
const binaryData = [0x30, 0x0C, 0x06, 0x03, 0x2B, 0x65, 0x70, 0x05, 0x00];
29
const asn1 = ASN1.decode(binaryData);
30

31
// Parse from hex string
32
const hexData = Hex.decode('300C06032B6570050000');
33
const parsed = ASN1.decode(hexData);
34
console.log(parsed.typeName()); // "SEQUENCE"
35

36
// Parse with offset
37
const asn1WithOffset = ASN1.decode(binaryData, 4);
38
console.log(asn1WithOffset.typeName()); // "NULL"
39
```
40

41
### ASN.1 Structure
42

43
The main ASN.1 class that represents parsed ASN.1 structures with complete metadata and content access.
44

45
```javascript { .api }
46
class ASN1 {
47
  constructor(stream: Stream, header: number, length: number, tag: ASN1Tag, tagLen: number, sub: ASN1[] | null);
48
  
49
  /** Stream containing the raw data */
50
  stream: Stream;
51
  /** Header length in bytes */
52
  header: number;
53
  /** Content length (-1 for indefinite length) */
54
  length: number;
55
  /** ASN.1 tag information */
56
  tag: ASN1Tag;
57
  /** Tag length in bytes */
58
  tagLen: number;
59
  /** Sub-elements for constructed types, null for primitive types */
60
  sub: ASN1[] | null;
61
  /** Definition information when matched against RFC definitions */
62
  def?: any;
63
  
64
  /**
65
   * Get human-readable type name for this ASN.1 element
66
   * @returns Type name string (e.g., "SEQUENCE", "INTEGER", "OCTET_STRING")
67
   */
68
  typeName(): string;
69
  
70
  /**
71
   * Get human-readable content preview
72
   * @param maxLength - Maximum length for content display (optional)
73
   * @returns Content string or null if no displayable content
74
   */
75
  content(maxLength?: number): string | null;
76
  
77
  /**
78
   * String representation for debugging
79
   * @returns Debug string with position and structure info
80
   */
81
  toString(): string;
82
  
83
  /**
84
   * Pretty formatted string representation with indentation
85
   * @param indent - Indentation string (optional, defaults to empty)
86
   * @returns Multi-line formatted string showing structure hierarchy
87
   */
88
  toPrettyString(indent?: string): string;
89
  
90
  /**
91
   * Get starting position in stream
92
   * @returns Starting byte position
93
   */
94
  posStart(): number;
95
  
96
  /**
97
   * Get content starting position (after tag and length)
98
   * @returns Content starting byte position
99
   */
100
  posContent(): number;
101
  
102
  /**
103
   * Get ending position
104
   * @returns Ending byte position
105
   */
106
  posEnd(): number;
107
  
108
  /**
109
   * Get position of the length field
110
   * @returns Length field byte position
111
   */
112
  posLen(): number;
113
  
114
  /**
115
   * Convert to hexadecimal string representation
116
   * @param type - Output format: 'raw', 'byte', or 'dump' (optional, defaults to 'raw')
117
   * @returns Hexadecimal string representation
118
   */
119
  toHexString(type?: 'raw' | 'byte' | 'dump'): string;
120
  
121
  /**
122
   * Convert to Base64url string representation
123
   * @param type - Output format: 'url' (no padding) or 'std' (with padding) (optional, defaults to 'url')
124
   * @returns Base64url string representation
125
   */
126
  toB64String(type?: 'url' | 'std'): string;
127
}
128
```
129

130
**Usage Examples:**
131

132
```javascript
133
import { ASN1 } from '@lapo/asn1js';
134
import { Base64 } from '@lapo/asn1js/base64.js';
135

136
// Parse a certificate
137
const certData = Base64.unarmor(`-----BEGIN CERTIFICATE-----
138
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA...
139
-----END CERTIFICATE-----`);
140

141
const cert = ASN1.decode(certData);
142

143
// Examine structure
144
console.log(cert.typeName()); // "SEQUENCE"
145
console.log(cert.sub.length); // Number of sub-elements
146
console.log(cert.toPrettyString());
147

148
// Access specific elements
149
const tbsCertificate = cert.sub[0];
150
const signatureAlgorithm = cert.sub[1];
151
const signatureValue = cert.sub[2];
152

153
// Get content preview
154
console.log(signatureValue.content(100)); // First 100 chars of signature
155

156
// Position information
157
console.log(`Certificate starts at ${cert.posStart()}`);
158
console.log(`Certificate content at ${cert.posContent()}`);
159
console.log(`Certificate ends at ${cert.posEnd()}`);
160

161
// Export formats
162
console.log(cert.toHexString('dump')); // Hex dump format
163
console.log(cert.toB64String('std')); // Standard Base64
164
```
165

166
### Length Decoding
167

168
Static method for decoding ASN.1 length fields according to DER/BER rules.
169

170
```javascript { .api }
171
/**
172
 * Decode ASN.1 length field from stream
173
 * @param stream - Stream positioned at length field
174
 * @returns Length value or null for indefinite length
175
 * @throws Error if length encoding is invalid or exceeds 48 bits
176
 */
177
static ASN1.decodeLength(stream: Stream): number | null;
178
```
179

180
**Usage Examples:**
181

182
```javascript
183
import { ASN1, Stream } from '@lapo/asn1js';
184

185
// Manual length decoding (typically not needed as ASN1.decode handles this)
186
const data = [0x82, 0x01, 0x00]; // Length = 256 in long form
187
const stream = new Stream(data, 0);
188
const length = ASN1.decodeLength(stream);
189
console.log(length); // 256
190
```
191

192
### ASN.1 Tag
193

194
Internal class representing ASN.1 tag information including class, construction, and tag number. This class is not exported from the module but instances are accessible via the `tag` property of ASN1 objects.
195

196
```javascript { .api }
197
interface ASN1Tag {
198
  /** Tag class: 0=Universal, 1=Application, 2=Context, 3=Private */
199
  tagClass: number;
200
  /** Whether tag is constructed (true) or primitive (false) */
201
  tagConstructed: boolean;
202
  /** Tag number within the class */
203
  tagNumber: number;
204
  
205
  /**
206
   * Check if tag is Universal class
207
   * @returns true if Universal class (tagClass === 0)
208
   */
209
  isUniversal(): boolean;
210
  
211
  /**
212
   * Check if tag is End-of-Contents
213
   * @returns true if EOC tag (class=0, number=0, primitive)
214
   */
215
  isEOC(): boolean;
216
  
217
}
218
```
219

220
**Usage Examples:**
221

222
```javascript
223
import { ASN1 } from '@lapo/asn1js';
224
import { Hex } from '@lapo/asn1js/hex.js';
225

226
const data = Hex.decode('30060403010203'); // SEQUENCE containing OCTET STRING
227
const asn1 = ASN1.decode(data);
228

229
// Examine tag
230
const tag = asn1.tag;
231
console.log(tag.tagClass); // 0 (Universal)
232
console.log(tag.tagConstructed); // true
233
console.log(tag.tagNumber); // 0x10 (SEQUENCE)
234
console.log(tag.isUniversal()); // true
235

236
// Check sub-element
237
const octetString = asn1.sub[0];
238
console.log(octetString.tag.tagNumber); // 0x04 (OCTET STRING)
239
console.log(octetString.tag.tagConstructed); // false
240
```