You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: README.md
+31-67
Original file line number
Diff line number
Diff line change
@@ -7,12 +7,16 @@
7
7
8
8
Abstract Syntax Notation One (ASN.1) is a standard and notation that describes rules and structures for representing, encoding, transmitting, and decoding data in telecommunications and computer networking. [ASN1js][] is a pure JavaScript library implementing this standard. ASN.1 is the basis of all X.509 related data structures and numerous other protocols used on the web.
9
9
10
+
## Important Information for ASN1.js V1 Users
11
+
ASN1.js V2 (ES2015 version) is **incompactible** with ASN1.js V1 code.
12
+
10
13
## Introduction
11
14
12
15
[ASN1js][] is the first library for [BER][] encoding/decoding in Javascript designed for browser use. [BER][] is the basic encoding rules for [ASN.1][] that all others are based on, [DER][] is the encoding rules used by PKI applications - it is a subset of [BER][]. The [ASN1js][] library was tested against [freely available ASN.1:2008 test suite], with some limitations related to JavaScript language.
13
16
14
17
## Features of the library
15
18
19
+
* Based on latest features of JavaScipt language from ES2015 standard;
16
20
*[ASN1js][] is a "base layer" for full-featured JS library [PKIjs][], which is using Web Cryptography API and has all classes, neccessary to work with PKI-related data;
17
21
* Fully object-oriented library. Inhiritence is using everywhere inside the lib;
18
22
* Working with HTML5 data objects (ArrayBuffer, Uint8Array etc.);
@@ -23,12 +27,12 @@ Abstract Syntax Notation One (ASN.1) is a standard and notation that describes r
23
27
* Any sub-block may have unlimited length, as it described in ASN.1 standard (even "tag block");
24
28
* Ability to work with ASN.1 string date types (intcluding all "international" strings like UniversalString, BMPString, UTF8String) by passing native JavaScript strings into constuctors. And vice versa - all initially parsed data of ASN.1 string types right after decoding automatically converts into native JavaScript strings;
25
29
* Same with ASN.1 date-time types: for major types like UTCTime and GeneralizedTime there are automatic convertion between "JS date type - ASN.1 date-time type" + vice versa;
26
-
* Same with ASN.1 OBJECT-IDENTIFIER (OID) data-type: you can initialize OID by JavaScript string and can get string representation via calling "oid.value_block.toString()";
30
+
* Same with ASN.1 OBJECT-IDENTIFIER (OID) data-type: you can initialize OID by JavaScript string and can get string representation via calling "oid.valueBlock.toString()";
27
31
* Working with "easy-to-understand" ASN.1 schemas (pre-defined or built by user);
28
32
* Has special types to work with ASN.1 schemas:
29
-
*ANY
30
-
*CHOICE
31
-
*REPEATED
33
+
*Any
34
+
*Choice
35
+
*Repeated
32
36
* User can name any block inside ASN.1 schema and easily get information by name;
33
37
* Ability to parse internal data inside a primitively encoded data types and automatically validate it against special schema;
34
38
* All types inside library are dynamic;
@@ -38,8 +42,8 @@ Abstract Syntax Notation One (ASN.1) is a standard and notation that describes r
@@ -67,12 +71,12 @@ Abstract Syntax Notation One (ASN.1) is a standard and notation that describes r
67
71
68
72
```javascript
69
73
// #region How to create new ASN.1 structures by calling constuctors with parameters
70
-
var sequence2 =neworg.pkijs.asn1.SEQUENCE({
74
+
var sequence2 =newasn1js.Sequence({
71
75
value: [
72
-
neworg.pkijs.asn1.INTEGER({ value:1 }),
73
-
neworg.pkijs.asn1.INTEGER({
74
-
is_hex_only:true,
75
-
value_hex: integer_data
76
+
newasn1js.Integer({ value:1 }),
77
+
newasn1js.Integer({
78
+
isHexOnly:true,
79
+
valueHex: integer_data
76
80
}),
77
81
]
78
82
});
@@ -81,13 +85,13 @@ Abstract Syntax Notation One (ASN.1) is a standard and notation that describes r
81
85
82
86
```javascript
83
87
// #region How to validate ASN.1 against pre-defined schema
84
-
var asn1_schema =neworg.pkijs.asn1.SEQUENCE({
88
+
var asn1_schema =newasn1js.Sequence({
85
89
name:"block1",
86
90
value: [
87
-
neworg.pkijs.asn1.NULL({
91
+
newasn1js.Null({
88
92
name:"block2"
89
93
}),
90
-
neworg.pkijs.asn1.INTEGER({
94
+
newasn1js.Integer({
91
95
name:"block3",
92
96
optional:true// This block is absent inside data, but it's "optional". Hence verification against the schema will be passed.
93
97
})
@@ -102,14 +106,14 @@ Abstract Syntax Notation One (ASN.1) is a standard and notation that describes r
102
106
103
107
```javascript
104
108
// #region How to use "internal schemas" for primitevely encoded data types
105
-
var primitive_octetstring =neworg.pkijs.asn1.OCTETSTRING({ value_hex: encoded_sequence }); // Create a primitively encoded OCTETSTRING where internal data is an encoded SEQUENCE
109
+
var primitive_octetstring =newasn1js.OctetString({ valueHex: encoded_sequence }); // Create a primitively encoded OctetString where internal data is an encoded Sequence
106
110
107
-
var asn1_schema_internal =neworg.pkijs.asn1.OCTETSTRING({
111
+
var asn1_schema_internal =newasn1js.OctetString({
108
112
name:"outer_block",
109
-
primitive_schema:neworg.pkijs.asn1.SEQUENCE({
113
+
primitiveSchema:newasn1js.Sequence({
110
114
name:"block1",
111
115
value: [
112
-
neworg.pkijs.asn1.NULL({
116
+
newasn1js.Null({
113
117
name:"block2"
114
118
})
115
119
]
@@ -118,8 +122,8 @@ Abstract Syntax Notation One (ASN.1) is a standard and notation that describes r
118
122
119
123
var variant6 =org.pkijs.compareSchema(primitive_octetstring, primitive_octetstring, asn1_schema_internal);
120
124
var variant6_verified =variant4.verified;
121
-
var variant6_block1_tag_num =variant6.result.block1.id_block.tag_number;
122
-
var variant6_block2_tag_num =variant6.result.block2.id_block.tag_number;
125
+
var variant6_block1_tag_num =variant6.result.block1.idBlock.tagNumber;
126
+
var variant6_block2_tag_num =variant6.result.block2.idBlock.tagNumber;
123
127
// #endregion
124
128
```
125
129
@@ -131,55 +135,15 @@ More examples could be found in "examples" directory or inside [PKIjs][] library
131
135
*[Freely available ASN.1:2008 test suite](https://github.com/YuryStrozhevsky/ASN1-2008-free-test-suite) - the suite which can help you to validate (and better understand) any ASN.1 coder/decoder;
132
136
133
137
## Suitability
134
-
At this time this library should be considered suitable for research and experimentation, futher code and security review is needed before utilization in a production application.
135
-
136
-
## How to use ASN1js and PKIjs with Node.js
137
-
138
-
**!!! WARNING !!! **
139
-
**Currently there is no "polyfill" of WebCrypto in Node.js. Thus you will not be able to use signature / verification features of PKIjs in Node.js programs.**
140
-
141
-
In order to use [PKIjs][] you will also need [ASN1js][] plus [node.extend](https://www.npmjs.com/package/node.extend) package.
142
-
```javascript
143
-
var merge =require("node.extend");
144
-
145
-
var common =require("asn1js/org/pkijs/common");
146
-
var _asn1js =require("asn1js");
147
-
var _pkijs =require("pkijs");
148
-
var _x509schema =require("pkijs/org/pkijs/x509_schema");
149
-
150
-
// #region Merging function/object declarations for ASN1js and PKIjs
151
-
var asn1js =merge(true, _asn1js, common);
152
-
153
-
var x509schema =merge(true, _x509schema, asn1js);
154
-
155
-
var pkijs_1 =merge(true, _pkijs, asn1js);
156
-
var pkijs =merge(true, pkijs_1, x509schema);
157
-
// #endregion
158
-
```
159
-
160
-
After that you will ba able to use ASN1js and PKIjs via common way:
There are several commercial products, enterprise solitions as well as open source project based on versions of ASN1js. You should, however, do your own code and security review before utilization in a production application before utilizing any open source library to ensure it will meet your needs.
0 commit comments