@root/asn1
Built by The Root Company for Greenlock and ACME.js
Lightweight, Zero-Dependency ASN.1 encoder and decoder for Node.js and Browsers, in less than 300 lines of vanilla JavaScript
| 1.6k gzipped | 4.2k minified | 8.4k pretty |
- Zero External Dependencies
-
Universal Support
- Node.js
- Browsers
- Vanilla JS
This ASN.1 codec is built for simplicity. It encodes into DER format and decodes into a simple, classless Array of Arrays and values.
Most people don't actually want to work with ANS.1 directly, but rather intend to work with pre-defined x509 schemas.
If you're most people, you're actually looking for one or more of these:
Want to contribute? Need commercial support?
Usage
ASN.1 DER consists values which have
- a type (2-bit class, 6-bit tag)
- a coded length
- zero or more values
Common types include:
0x30 SEQUENCE
0x02 INTEGER*
0x03 BIT STRING**
0x04 OCTET STRING
0x05 NULL
0x06 OBJECT IDENTIFIER
0x0C UTF8String
0x16 IA5String (ASCII)
0x17 UTCTime
0x31 SET
0xA0 context-specific***
0xA3 context-specific***
* INTEGERS are always BigInt-encoded (a leading '00' for positive numbers with a 1 in the most-significant-bit position)
**BIT STRINGS have a leading "bit mask" which, for all practical purposes, is actually always '00'
*** See https://stackoverflow.com/a/15071901/151312
The core value in this library is that it:
- correctly sums the byte length of children elements
- correctly encodes BigInts
Parser Usage
There are three options:
-
der(required) - the input bytes as a buffer -
json(default) - returns hex strings for values, rather than buffers -
verbose- returns a more human-friendly object that is useful for debugging
ASN1.parse({ der: `<Buffer>`, json: true, verbose: true });
Default (hex) output:
[
'30',
[
['02', '01'],
['04', '2c8996...'],
['a0', [['06', '2a8648...']]],
['a1', [['03', '04bdd8...']]]
]
];
Verbose output:
{ type: 48,
lengthSize: 0,
length: 119,
children:
[ { type: 2, lengthSize: 0, length: 1, value: <Buffer 01> },
{ type: 4,
lengthSize: 0,
length: 32,
value:
<Buffer 2c 89 96 ...>,
children: [] },
{ type: 160, lengthSize: 0, length: 10, children: [Array] },
{ type: 161, lengthSize: 0, length: 68, children: [Array] } ] }
Packer Usage
You can use either of two syntaxes. One is much easier to read than the other.
Ironically, hex strings are used in place of buffers for efficiency.
ASN1.Any(hexType, hexBytes1, hexBytes2, ...);
ASN1.UInt(hexBigInt);
ASN1.BitStr(hexBitStream);
In practice, you'll be cascading the objects into a final hex string:
// result is a hex-encoded DER
var der = hexToBuf(
ASN1.Any('30' // Sequence
, ASN1.UInt('01') // Integer (Version 1)
, ASN1.Any('04', '07CAD7...') // Octet String
, ASN1.Any('A0', '06082A...') // [0] Object ID (context-specific)
, ASN1.Any('A1', // [1] (context-specific value)
ASN1.BitStr('04BDD8...')
)
)
);
Alternatively you can pack either the sparse array or verbose object, using hex strings or buffers:
-
jsonwhen set to true will return a hex-encoded DER rather than a DER buffer
var buf = Uint8Array.from([0x01]);
ASN1.pack(
[
'30',
[
['02', buf],
['04', '07CAD7...'],
['A0', '06082A...'],
['A1', ['03', '04BDD8...']]
]
],
{ json: false }
);
var buf = Uint8Array.from([0x01]);
ASN1.pack(
{
type: 48,
children: [
{ type: 2, value: '01' },
{ type: 4, value: '2c 89 96 ...', children: [] },
{ type: 160, children: [...] },
{ type: 161, children: [...] }
]
},
{ json: false }
);
Install
This package contains both node-specific and browser-specific code,
and the package.json#browser field ensures that your package manager
will automatically choose the correct code for your environment.
Node (and Webpack)
npm install -g @root/asn1
var asn1 = require('@root/asn1');
// just the packer
var asn1 = require('@root/asn1/packer');
// just the parser
var asn1 = require('@root/asn1/parser');
Browsers (Vanilla JS)
<script src="https://unpkg.com/@root/asn1/dist/asn1.all.js"></script>
<script src="https://unpkg.com/@root/asn1/dist/asn1.all.min.js"></script>
var ASN1 = window.ASN1;
Examples
Decoding DER to JSON-ASN.1
var PEM = require('@root/pem/packer');
var Enc = require('@root/encoding');
var ASN1 = require('@root/asn1/parser');
var pem = [
'-----BEGIN EC PRIVATE KEY-----',
'MHcCAQEEICyJlsaqkx2z9yx0H6rHA0lM3/7jXjxqn/VOhExHDuR6oAoGCCqGSM49',
'AwEHoUQDQgAEvdjQ3T6VBX82LIKDzepYgRsz3HgRwp83yPuonu6vqoshSQRe0Aye',
'mmdXUDX2wTZsmFSjhY9uroRiBbGZrigbKA==',
'-----END EC PRIVATE KEY-----'
].join('\n');
var der = PEM.parseBlock(pem).bytes;
var asn1 = ASN1.parse({ der: der, json: true, verbose: false });
[
"30",
[
["02", "01"],
[
"04",
"2c8996c6aa931db3f72c741faac703494cdffee35e3c6a9ff54e844c470ee47a"
],
["a0", [["06", "2a8648ce3d030107"]]],
[
"a1",
[
[
"03",
"04bdd8d0dd3e95057f362c8283cdea58811b33dc7811c29f37c8fba89eeeafaa8b2149045ed00c9e9a67575035f6c1366c9854a3858f6eae846205b199ae281b28"
]
]
]
]
]
{
"type": 48,
"lengthSize": 0,
"length": 119,
"children": [
{ "type": 2, "lengthSize": 0, "length": 1, "value": "01" },
{
"type": 4,
"lengthSize": 0,
"length": 32,
"value": "2c8996c6aa931db3f72c741faac703494cdffee35e3c6a9ff54e844c470ee47a",
"children": []
},
{
"type": 160,
"lengthSize": 0,
"length": 10,
"children": [
{
"type": 6,
"lengthSize": 0,
"length": 8,
"value": "2a8648ce3d030107"
}
]
},
{
"type": 161,
"lengthSize": 0,
"length": 68,
"children": [
{
"type": 3,
"lengthSize": 0,
"length": 66,
"value": "04bdd8d0dd3e95057f362c8283cdea58811b33dc7811c29f37c8fba89eeeafaa8b2149045ed00c9e9a67575035f6c1366c9854a3858f6eae846205b199ae281b28",
"children": []
}
]
}
]
}
Encoding ASN.1 to DER
Here's an example of an SEC1-encoded EC P-256 Public/Private Keypair:
var ASN1 = require('@root/asn1/packer');
var Enc = require('@root/encoding');
var PEM = require('@root/pem/packer');
// 1.2.840.10045.3.1.7
// prime256v1 (ANSI X9.62 named elliptic curve)
var OBJ_ID_EC_256 = '06 08 2A8648CE3D030107';
var jwk = {
crv: 'P-256',
d: 'LImWxqqTHbP3LHQfqscDSUzf_uNePGqf9U6ETEcO5Ho',
kty: 'EC',
x: 'vdjQ3T6VBX82LIKDzepYgRsz3HgRwp83yPuonu6vqos',
y: 'IUkEXtAMnppnV1A19sE2bJhUo4WPbq6EYgWxma4oGyg',
kid: 'MnfJYyS9W5gUjrJLdn8ePMzik8ZJz2qc-VZmKOs_oCw'
};
var d = Enc.base64ToHex(jwk.d);
var x = Enc.base64ToHex(jwk.x);
var y = Enc.base64ToHex(jwk.y);
var der = Enc.hexToBuf(
ASN1.Any('30' // Sequence
, ASN1.UInt('01') // Integer (Version 1)
, ASN1.Any('04', d) // Octet String
, ASN1.Any('A0', OBJ_ID_EC_256) // [0] Object ID
, ASN1.Any('A1', // [1] Embedded EC/ASN1 public key
ASN1.BitStr('04' + x + y)
)
)
);
var pem = PEM.packBlock({
type: 'EC PRIVATE KEY',
bytes: der
});
Disabiguation
ASN1.Any(typ, hexVal, ...)
There was once an actual ASN.1 type with the literal name 'Any'.
It was deprecated in 1994 and the Any in this API simply means "give any value"
Contributions
Did this project save you some time? Maybe make your day? Even save the day?
Please say "thanks" via Paypal or Patreon:
- Paypal: \$5 | \$10 | Any amount: paypal@therootcompany.com
- Patreon: https://patreon.com/rootprojects
Where does your contribution go?
Root is a collection of experts who trust each other and enjoy working together on deep-tech, Indie Web projects.
Our goal is to operate as a sustainable community.
Your contributions - both in code and especially monetarily - help to not just this project, but also our broader work of projects that fuel the Indie Web.
Also, we chat on Keybase in #rootprojects
Commercial Support
Do you need...
- more features?
- bugfixes, on your timeline?
- custom code, built by experts?
- commercial support and licensing?
Contact aj@therootcompany.com for support options.
Legal
Copyright AJ ONeal, Root 2018-2019
MPL-2.0 | Terms of Use | Privacy Policy