# Smart Card Shell

- - Home
- - GPError
  - GPSystem
  - ByteString
  - ByteBuffer
  - TLV
  - TLVList
  - Card
  - Atr
  - Key
  - Crypto
  - Application
  - GPApplication
  - GPSecDomain
- - ASN1
  - CardFile
  - IsoSecureChannel
  - ApplFactory
  - GPXML
  - JsScript
  - CardSim
- - X509
  - CRL
  - KeyStore
  - Signed CMS
  - Enveloped CMS
  - CMS Generator
  - XMLSignature
  - SSS
  - OCSPQuery
  - LDAP
  - SOAP
  - URLConnection
- - PKCS11Provider
  - PKCS11Session
  - PKCS11Object
- - OutlineNode
  - Dialog
  - Task
- - Tools
  - Modules
- - OpenSCDP

# ASN1 - Reference Documentation

Implementation of support for ASN.1 data structures using DER encoding rule

## Index of Methods

- ASN1() constructor
- add()
- get()
- find()
- remove()
- getBytes()
- getDate()
- setName()
- ASN1.defineObjectIdentifier()
- toString()
- ASN1.nameForObjectIdentifier()
- toString()

## Constants

Type | Name | Description
--- | --- | ---
Number | UNIVERSAL | END_OF_CONTENTS ASN.1 class
Number | APPLICATION | APPLICATION ASN.1 class
Number | CONTEXT | CONTEXT ASN.1 class
Number | PRIVATE | PRIVATE ASN.1 class
Number | END_OF_CONTENTS | END_OF_CONTENTS ASN.1 object
Number | BOOLEAN | BOOLEAN ASN.1 object
Number | INTEGER | INTEGER ASN.1 object
Number | BIT_STRING | BIT_STRING ASN.1 object
Number | OCTET_STRING | OCTET_STRING ASN.1 object
Number | NULL | NULL ASN.1 object
Number | OBJECT_IDENTIFIER | OBJECT_IDENTIFIER ASN.1 object
Number | OBJECT_DESCRIPTOR | OBJECT_DESCRIPTOR ASN.1 object
Number | EXTERNAL_TYPE | EXTERNAL_TYPE ASN.1 object
Number | REAL | REAL ASN.1 object
Number | ENUMERATED | ENUMERATED ASN.1 object
Number | EMBEDDED_PDV | EMBEDDED_PDV ASN.1 object
Number | UTF8String | UTF8String ASN.1 object
Number | RELATIVE_OID | RELATIVE_OID ASN.1 object
Number | SEQUENCE | SEQUENCE ASN.1 object
Number | SET | SET ASN.1 object
Number | NumericString | NumericString ASN.1 object
Number | PrintableString | PrintableString ASN.1 object
Number | T61String | T61String ASN.1 object
Number | IA5String | IA5String ASN.1 object
Number | UTCTime | UTCTime ASN.1 object
Number | GeneralizedTime | GeneralizedTime ASN.1 object
Number | GeneralString | GeneralString ASN.1 object
Number | UniversalString | UniversalString ASN.1 object
Number | BMPString | BMPString ASN.1 object

## Properties

Type | Name | Description
--- | --- | ---
Number | tag | The combined value of the tag, containing the class, constructed flag and number
Number | length | Length of the value field
ByteString | value | The value field
Number | tagclass | The class of the ASN.1 object. Is one of ASN1.UNIVERSAL, ASN1.APPLICATION, ASN1.CONTEXT or ASN1.PRIVATE
Number | tagnumber | The number element of the tag
Boolean | isconstructed | True, if the object is a constructed ASN.1 object
Number | size | Size of the concatenation of tag, length and value field
Number | elements | Number of elements in a constructed object. 0 for primitive objects
String | name | Name of object

## Constructor

### Prototype

ASN1(Number tag)

ASN1(Number tag, ByteString value)

ASN1(Number tag, ASN1 object*)

ASN1(ByteString encoded)

ASN1(String name, Number tag)

ASN1(String name, Number tag, ByteString value)

ASN1(String name, Number tag, ASN1 object*)

ASN1(String name, ByteString encoded)

### Description

Create an ASN.1 object, either primitive or constructed. The constructor without a value or with a list of TLV objects will create a constructed object, which can be further completed using the add() method. The constructor with a value field will create a primitive, immutuable object

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | tag | Tag value, including class, primitive/constructed flag and id
`String` | name | Object name to be assigned to the object
`ASN1` | object | One or more ASN1 object(s) to be included in constructed object
`ByteString` | value | Value field of object
`ByteString` | encoded | DER encoded ASN.1 object

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_DATA | ByteString does not contain a valid DER encoded object

### Example

    t = new ASN1(ASN1.SEQUENCE);
    assert(t instanceof ASN1);
    assert(t.tag == ASN1.SEQUENCE);
    assert(t.length == 0);
    assert(t.value.toString(HEX) == "");

    assert(t.tagclass == ASN1.UNIVERSAL);
    assert(t.tagnumber == 16);
    assert(t.isconstructed);
    assert(t.size == 2);
    assert(t.elements == 0);
    t = new ASN1("singleSequence", ASN1.SEQUENCE);
    print(t);

    t = new ASN1(ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX));
    assert(t instanceof ASN1);
    assert(t.tag == ASN1.OBJECT_IDENTIFIER);
    assert(t.length == 3);
    assert(t.value.toString(HEX) == "2A1200");

    assert(t.tagclass == ASN1.UNIVERSAL);
    assert(t.tagnumber == 6);
    assert(!t.isconstructed);
    assert(t.size == 5);
    t = new ASN1("objectIdentifier", ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX));
    print(t);

    t = new ASN1(new ByteString("06022A11", HEX));
    assert(t instanceof ASN1);
    assert(t.tag == ASN1.OBJECT_IDENTIFIER);
    assert(t.length == 2);
    assert(t.value.toString(HEX) == "2A11");

    assert(t.tagclass == ASN1.UNIVERSAL);
    assert(t.tagnumber == 6);
    assert(!t.isconstructed);
    assert(t.size == 4);
    t = new ASN1("fromByteString", new ByteString("06022A11", HEX));
    print(t);

    t = new ASN1(ASN1.SEQUENCE,
    		new ASN1(ASN1.OCTET_STRING, new ByteString("Hello World", ASCII)),
    		new ASN1(ASN1.GeneralizedTime, new ByteString("20051010120000Z", ASCII)));

    assert(t instanceof ASN1);
    assert(t.tag == ASN1.SEQUENCE);
    assert(t.elements == 2);

    assert(t.tagclass == ASN1.UNIVERSAL);
    assert(t.tagnumber == 16);
    assert(t.isconstructed);
    assert(t.size == 32);
    t = new ASN1("complexSequence", ASN1.SEQUENCE,
    		new ASN1(ASN1.OCTET_STRING, new ByteString("Hello World", ASCII)),
    		new ASN1(ASN1.GeneralizedTime, new ByteString("20051010120000Z", ASCII)));
    print(t);

    root = new X509("root.cer");
    bs = root.getBytes();
    print(bs);
    t = new ASN1(bs);
    assert(t instanceof ASN1);
    print(t);

## add()

### Prototype

ASN1 add(ASN1 object*)

ASN1 add(Number index, ASN1 object*)

### Description

Add one or more ASN.1 objects to a constructed object at index or at the end.

### Arguments

Type | Name | Description
--- | --- | ---
`ASN1` | object | ASN.1 objects to add
`Number` | index | Zero based index

### Return

`ASN1` | The object the method is applied to

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_MECH | Object must be constructed

### Example

    t = new ASN1(ASN1.SEQUENCE);
    t.add(new ASN1(ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX)));

    t.add(new ASN1(ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX)),
          new ASN1(ASN1.PrintableString, new ByteString("Hello World", ASCII)));

    t.add(0, new ASN1(ASN1.INTEGER, new ByteString("01", HEX)));

## get()

### Prototype

ASN1 get(Number index)

### Description

Get ASN.1 object at zero based index from constructed object.

This method does not provide a copy of the element, but a reference to it. Changes to the element will have an effect in parent objects or other instances obtained with the get() method

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | index | Zero based offset

### Return

`ASN1` | New ASN1 object representing the element at the requested index

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_INDEX | Index is out of range
GPError | GPError.INVALID_MECH | Object must be constructed

### Example

    t = new ASN1(ASN1.SEQUENCE);
    t.add(new ASN1(ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX)));
    t.add(new ASN1(ASN1.OCTET_STRING, new ByteString("ÄÖÜ", UTF8)));

    n = t.get(0);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.OBJECT_IDENTIFIER);
    assert(n.length == 3);

    n = t.get(1);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.OCTET_STRING);
    assert(n.length == 6);

## find()

### Prototype

ASN1 find(Number tag)

ASN1 find(Number tag, Number index)

ASN1 find(Number tag, ASN1 cursor)

### Description

Find ASN1 object with matching tag.

The method can be called with an object after which the search will start. The constant value null indicates the beginning of the list.

This method does not provide a copy of the element, but a reference to it. Changes to the element will have an effect in parent objects or other instances obtained with the get() method

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | tag | The tag value to search for
`Number` | index | Zero based offset of the object at which the search is started.
`ASN1` | cursor | The object after which the search resumes or null for a new search

### Return

`ASN1` | New ASN1 object representing the found element or null if no match found

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_INDEX | Index is out of range
GPError | GPError.INVALID_MECH | Object must be constructed

### Example

    t = new ASN1(ASN1.SEQUENCE);
    t.add(new ASN1(ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX)));
    t.add(new ASN1(ASN1.OCTET_STRING, new ByteString("ÄÖÜ", UTF8)));
    t.add(new ASN1(ASN1.INTEGER, new ByteString("00", HEX)));
    t.add(new ASN1(0x5F1C, new ByteString("5F1C", HEX)));
    t.add(new ASN1(ASN1.INTEGER, new ByteString("0000", HEX)));

    n = t.find(ASN1.OBJECT_IDENTIFIER);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.OBJECT_IDENTIFIER);

    n = t.find(ASN1.INTEGER);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.INTEGER);
    assert(n.length == 1);

    n = t.find(ASN1.INTEGER, n);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.INTEGER);
    assert(n.length == 2);

    n = t.find(ASN1.INTEGER, n);
    assert(n == null);

    n = t.find(ASN1.OBJECT_IDENTIFIER, n);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.OBJECT_IDENTIFIER);

    n = t.find(ASN1.INTEGER, 1);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.INTEGER);
    assert(n.length == 1);

    n = t.find(ASN1.INTEGER, 3);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.INTEGER);
    assert(n.length == 2);

    n = t.find(ASN1.OBJECT_IDENTIFIER, 0);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.OBJECT_IDENTIFIER);

    n = t.find(0x5F1C);
    assert(n instanceof ASN1);
    assert(n.tag == 0x5F1C);

    n = t.find(0x5F1D);
    assert(n == null);

## remove()

### Prototype

void remove(Number index)

### Description

Remove ASN.1 object at zero based index from constructed object.

### Arguments

Type | Name | Description
--- | --- | ---
`Number` | index | Zero based offset

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Type of argument is invalid for call
GPError | GPError.INVALID_INDEX | Index is out of range
GPError | GPError.INVALID_MECH | Object must be constructed

### Example

    t = new ASN1(ASN1.SEQUENCE);
    t.add(new ASN1(ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX)));
    t.add(new ASN1(ASN1.OCTET_STRING, new ByteString("ÄÖÜ", UTF8)));

    t.remove(0);

    n = t.get(0);
    assert(n instanceof ASN1);
    assert(n.tag == ASN1.OCTET_STRING);
    assert(n.length == 6);

## getBytes()

### Prototype

ByteString getBytes()

### Description

Return the DER encoded ASN.1 object

### Return

`ByteString` | The DER encoded object

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call

### Example

    t = new ASN1(ASN1.SEQUENCE);
    t.add(new ASN1(ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX)));
    assert(t.getBytes().toString(HEX) == "300506032A1200");

## getDate()

### Prototype

Date getDate()

### Description

Return the value field of a primitive ASN.1 object as a date. This usually works for for GeneralizedTime objects which store date and time in ISO8601 format.

### Return

`ByteString` | The DER encoded object

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_MECH | Object must be primitive
GPError | GPError.INVALID_DATA | Value field does not contain a valid date and time

### Example

    // Local time
    t = new ASN1(ASN1.GeneralizedTime, new ByteString("20050929113422", ASCII));
    d = t.getDate();
    print(d);
    assert(d.toString().substr(0,24) == "Thu Sep 29 2005 11:34:22");

    // UTC time
    t = new ASN1(ASN1.GeneralizedTime, new ByteString("20050929113422Z", ASCII));
    d = t.getDate();
    assert(d.getTime() == 1127993662000);

    // CEST time
    t = new ASN1(ASN1.GeneralizedTime, new ByteString("20050929133422+0200", ASCII));
    d = t.getDate();
    assert(d.getTime() == 1127993662000);

    // Local time with millisecond
    t = new ASN1(ASN1.GeneralizedTime, new ByteString("20050929113422.1", ASCII));
    d = t.getDate();
    assert(d.toString().substr(0,24) == "Thu Sep 29 2005 11:34:22");

    // UTC time with millisecond
    t = new ASN1(ASN1.GeneralizedTime, new ByteString("20050929113422.1Z", ASCII));
    d = t.getDate();
    assert(d.getTime() == 1127993662001);

    // CEST time with millisecond
    t = new ASN1(ASN1.GeneralizedTime, new ByteString("20050929133422.1+0200", ASCII));
    d = t.getDate();
    assert(d.getTime() == 1127993662001);

## setName()

### Prototype

setName(String name)

### Description

Assign a name to the ASN.1 object.

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call

### Example

    t = new ASN1(ASN1.SEQUENCE);
    t.setName("testObject");
    print(t.toString());

## ASN1.defineObjectIdentifier()

### Prototype

defineObjectIdentifier(String name, String definition)

### Description

Add a definition for a symbolic object identifier to the internal registry.

The definition may be recursive and can use the dotted or spaced format.

### Return

`` |

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call

### Example

    ASN1.defineObjectIdentifier("openscdp-test", "1.3.6.1.4.1.24991.0");
    ASN1.defineObjectIdentifier("openscdp-test-sub1", "openscdp-test.4");
    ASN1.defineObjectIdentifier("openscdp-test-sub2", "openscdp-test branch(5)");

    var b = new ByteString("openscdp-test-sub2", OID);
    print(b);
    assert(b.toString(OID) == "1.3.6.1.4.1.24991.0.5");

## toString()

### Prototype

String toString()

### Description

Dump the contents of the ASN.1 object

### Return

`String` | Dump of ASN.1 object

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Argument must be of type Number and either Card.RESET_COLD or Card.RESET_WARM

### Example

    t = new ASN1(ASN1.SEQUENCE);
    t.add(new ASN1(ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX)));
    print(t.toString());

## ASN1.nameForObjectIdentifier()

### Prototype

nameForObjectIdentifier(ByteString oid)

### Description

Return a name for the object identifier passed or undefined if no matching name is found.

### Return

`String` | The object identifier name or undefined

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call

### Example

    var b = new ByteString("openscdp-test-sub2", OID);
    print(b);
    assert(b.toString(OID) == "1.3.6.1.4.1.24991.0.5");
    assert(ASN1.nameForObjectIdentifier(b) == "openscdp-test-sub2");
    assert(ASN1.nameForObjectIdentifier(new ByteString("0102", HEX)) === undefined);

## toString()

### Prototype

String toString()

### Description

Dump the contents of the ASN.1 object

### Return

`String` | Dump of ASN.1 object

### Exceptions

Name | Value | Description
--- | --- | ---
GPError | GPError.ARGUMENTS_MISSING | Too few arguments in call
GPError | GPError.INVALID_ARGUMENTS | Too many arguments in call
GPError | GPError.INVALID_TYPE | Argument must be of type Number and either Card.RESET_COLD or Card.RESET_WARM

### Example

    t = new ASN1(ASN1.SEQUENCE);
    t.add(new ASN1(ASN1.OBJECT_IDENTIFIER, new ByteString("2A1200", HEX)));
    print(t.toString());

© Copyright 2003 - 2026 CardContact Systems GmbH , Minden, Germany