tutorials/asn1.md - third_party/pc-dart - Git at Google

 # ASN1

 Pointycastle has a build in ASN1 support to handle the most common ASN1 objects.

 ## Overview

 The package contains an ASN1Parser that can parse the ASN1 objects, like ASN1Integer, ASN1Sequence, ASN1BitString and many more.

 ## Supported ASN1 objects

 The following table lists all supported types and the possible encoding and decoding rules supported.

 | ASN1 Type         | Decode From                                                                                   | Encode To                                                                                     |
 | ----------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | BOOLEAN           | DER                                                                                           | DER                                                                                           |
 | INTEGER           | DER                                                                                           | DER                                                                                           |
 | BIT_STRING        | DER / BER Constructed / BER Long Length Form / BER Padded / BER Constructed Indefinite Length | DER / BER Constructed / BER Long Length Form / BER Padded / BER Constructed Indefinite Length |
 | OCTET_STRING      | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              |
 | NULL              | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              |
 | OBJECT_IDENTIFIER | DER                                                                                           | DER                                                                                           |
 | ENUMERATED        | DER                                                                                           | DER                                                                                           |
 | UTF8_STRING       | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              |
 | SEQUENCE          | DER                                                                                           | DER                                                                                           |
 | SET               | DER                                                                                           | DER                                                                                           |
 | PRINTABLE_STRING  | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              |
 | IA5_STRING        | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              | DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length              |
 | UTC_TIME          | DER                                                                                           | DER                                                                                           |

 More information about the different encoding rules can be found at <https://www.bouncycastle.org/asn1_layman_93.txt>

 ### Working with ASN1 objects

 Every ASN1 object can be instanced in several ways.

 #### Named constructor fromBytes

 The fromBytes constructed will create an instance according to the given bytes. It detects automatically the encoding rule used within the given bytes.

 #### Default constructor

 The default constructor takes different arguments, depending on the object. Every default constructor automatically sets the right ASN1 tag. If needed the tag can also be overridden.

 Example for the default constructor of an ASN1UTF8String entity:

 ```dart
 var asn1Object = ASN1UTF8String(utf8StringValue: 'Hello World');
 ```

 If an ASN1 object supports **constructed** encoding/decoding, the default constructor allows to pass a list of child elements. In this case, the tag needs to be set manually to the right constructed tag.

 ```dart
 var e1 = ASN1UTF8String(utf8StringValue: 'Hello');

 var e2 = ASN1UTF8String(utf8StringValue: ' World');

 varar asn1Object = ASN1UTF8String(elements: [e1, e2], tag: ASN1Tags.UTF8_STRING_CONSTRUCTED);
 ```

 ## Parsing ASN1

 To parse an ASN1Object, we need to pass the bytes representing the object to the parser. In this example we use the following structure :

 ```bash
    SEQUENCE (4 elem)
       SET (1 elem)
         SEQUENCE (2 elem)
           OBJECT IDENTIFIER 2.5.4.6 countryName (X.520 DN component)
           PrintableString US
       SET (1 elem)
         SEQUENCE (2 elem)
           OBJECT IDENTIFIER 2.5.4.10 organizationName (X.520 DN component)
           PrintableString DigiCert Inc
       SET (1 elem)
         SEQUENCE (2 elem)
           OBJECT IDENTIFIER 2.5.4.11 organizationalUnitName (X.520 DN component)
           PrintableString www.digicert.com
       SET (1 elem)
         SEQUENCE (2 elem)
           OBJECT IDENTIFIER 2.5.4.3 commonName (X.520 DN component)
           PrintableString Thawte RSA CA 2018
 ```

 ```dart
 // Base64 encoded string that represents the above structure
 var base64String =
         'MFwxCzAJBgNVBAYTAlVTMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5jb20xGzAZBgNVBAMTElRoYXd0ZSBSU0EgQ0EgMjAxOA==';
 // Convert to byte list
 var bytes = base64.decode(base64String);
 // Pass the byte list to the ASN1Parser
 var parser = ASN1Parser(bytes);
 ```

 Now we can use the parser to move between every object within the above structure. The first element is an ASN1Sequence with 4 child elements.

 ```dart
 // Grab the first element by calling nextObject() and cast it to ASN1Sequence
 var sequence = parser.nextObject() as ASN1Sequence;
 // Iterate over each element
 sequence.elements.forEach((element) {
     var asn1Set = element as ASN1Set;
     var seq = asn1Set.elements.elementAt(0) as ASN1Sequence
     var objectIdentifier = seq.elements.elementAt(0) as ASN1ObjectIdentifier;
     var printableString = seq.elements.elementAt(1) as ASN1PrintableString;
     print('${objectIdentifier.objectIdentifierAsString} = ${printableString.stringValue}')
 });
 ```

 The above code will print out the following lines :

 ```bash
 2.5.4.6 = US
 2.5.4.10 = DigiCert Inc
 2.5.4.11 = www.digicert.com
 2.5.4.3 = Thawte RSA CA 2018
 ```

 ## Encoding ASN1

 The ASN1 objects can be also used to create ASN1 structures and encode them and process them as base64 encoded string in other software. As an example, we will create a RSA Public Key PEM string.

 ```dart

 final BEGIN_PUBLIC_KEY = '-----BEGIN PUBLIC KEY-----';
 final END_PUBLIC_KEY = '-----END PUBLIC KEY-----';

 // Create a new RSA pulic key
 var publicKey;

 // Create the top level sequence
 var topLevelSeq = ASN1Sequence();

 // Create the sequence holding the algorithm information
 var algorithmSeq = ASN1Sequence();
 var paramsAsn1Obj = ASN1Object.fromBytes(Uint8List.fromList([0x5, 0x0]));
 algorithmSeq.add(ASN1ObjectIdentifier.fromComponentString('1.2.840.113549.1.1.1'));
 algorithmSeq.add(paramsAsn1Obj);

 // Create the constructed ASN1BitString
 var modulus = ASN1Integer(publicKey.modulus);
 var exponent = ASN1Integer(publicKey.exponent);
 var publicKeySeqBitString = ASN1BitString(elements : [modulus, exponent], tag: ASN1Tags.BIT_STRING_CONSTRUCTED);

 // Add ASN1 objects to the top level sequence
 topLevelSeq.add(algorithmSeq);
 topLevelSeq.add(publicKeySeqBitString);

 // Encode base64
 var dataBase64 = base64.encode(topLevelSeq.encodedBytes);
 var chunks = StringUtils.chunk(dataBase64, 64);

 print('$BEGIN_PUBLIC_KEY\n${chunks.join('\n')}\n$END_PUBLIC_KEY');
 ```

 The result will be something similar to this:

 ```bash
 -----BEGIN PUBLIC KEY-----
 MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAg1ea9Y7zO2Gt7kzYOSp5
 I4dZHY75ZCYNMegmg0obKVxauRXeBL+pfhuDgq1+k0Z3iOfOELczOgaonTsJiHo8
 kQcqgYNj0dmKKb+/318+3aEIZa6PreIgWJ0scM0oupHeiEA/M45vQIDMOv6jjVa5
 mB1u/nHXQpvzH1i4H9tlODTSvIoIabW2/14+JNIm1KNQz/H/NsbooraY6POvqGtr
 Ek743CRJNH9mgEYEQnOF0dYiS8h+JoXxcIDuaLz/WCRx1AWvINj3YNBgiIc6N4/Y
 2nv5lAKajhfh8grs7hCRvXUzT9wcvj9aNtmOHm4cH/WpVK4sXGuLxN1MxDyqaPIv
 9QIDAQAB
 -----END PUBLIC KEY-----
 ```

 And the ASN1 structure looks like this :

 ```bash
 SEQUENCE (2 elem)
   SEQUENCE (2 elem)
     OBJECT IDENTIFIER 1.2.840.113549.1.1.1 rsaEncryption (PKCS #1)
     NULL
   BIT STRING (2160 bit) 001100001000001000000001000010100000001010000010000000010000000100000…
     SEQUENCE (2 elem)
       INTEGER (2048 bit) 165804177387087149617220457493747588873959131224426853644136343567339…
       INTEGER 65537
 ```
	# ASN1

	Pointycastle has a build in ASN1 support to handle the most common ASN1 objects.

	## Overview

	The package contains an ASN1Parser that can parse the ASN1 objects, like ASN1Integer, ASN1Sequence, ASN1BitString and many more.

	## Supported ASN1 objects

	The following table lists all supported types and the possible encoding and decoding rules supported.

	\| ASN1 Type \| Decode From \| Encode To \|
	\| ----------------- \| --------------------------------------------------------------------------------------------- \| --------------------------------------------------------------------------------------------- \|
	\| BOOLEAN \| DER \| DER \|
	\| INTEGER \| DER \| DER \|
	\| BIT_STRING \| DER / BER Constructed / BER Long Length Form / BER Padded / BER Constructed Indefinite Length \| DER / BER Constructed / BER Long Length Form / BER Padded / BER Constructed Indefinite Length \|
	\| OCTET_STRING \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \|
	\| NULL \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \|
	\| OBJECT_IDENTIFIER \| DER \| DER \|
	\| ENUMERATED \| DER \| DER \|
	\| UTF8_STRING \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \|
	\| SEQUENCE \| DER \| DER \|
	\| SET \| DER \| DER \|
	\| PRINTABLE_STRING \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \|
	\| IA5_STRING \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \| DER / BER Constructed / BER Long Length Form / BER Constructed Indefinite Length \|
	\| UTC_TIME \| DER \| DER \|

	More information about the different encoding rules can be found at <https://www.bouncycastle.org/asn1_layman_93.txt>

	### Working with ASN1 objects

	Every ASN1 object can be instanced in several ways.

	#### Named constructor fromBytes

	The fromBytes constructed will create an instance according to the given bytes. It detects automatically the encoding rule used within the given bytes.

	#### Default constructor

	The default constructor takes different arguments, depending on the object. Every default constructor automatically sets the right ASN1 tag. If needed the tag can also be overridden.

	Example for the default constructor of an ASN1UTF8String entity:

	```dart
	var asn1Object = ASN1UTF8String(utf8StringValue: 'Hello World');
	```

	If an ASN1 object supports constructed encoding/decoding, the default constructor allows to pass a list of child elements. In this case, the tag needs to be set manually to the right constructed tag.

	```dart
	var e1 = ASN1UTF8String(utf8StringValue: 'Hello');

	var e2 = ASN1UTF8String(utf8StringValue: ' World');

	varar asn1Object = ASN1UTF8String(elements: [e1, e2], tag: ASN1Tags.UTF8_STRING_CONSTRUCTED);
	```

	## Parsing ASN1

	To parse an ASN1Object, we need to pass the bytes representing the object to the parser. In this example we use the following structure :

	```bash
	SEQUENCE (4 elem)
	SET (1 elem)
	SEQUENCE (2 elem)
	OBJECT IDENTIFIER 2.5.4.6 countryName (X.520 DN component)
	PrintableString US
	SET (1 elem)
	SEQUENCE (2 elem)
	OBJECT IDENTIFIER 2.5.4.10 organizationName (X.520 DN component)
	PrintableString DigiCert Inc
	SET (1 elem)
	SEQUENCE (2 elem)
	OBJECT IDENTIFIER 2.5.4.11 organizationalUnitName (X.520 DN component)
	PrintableString www.digicert.com
	SET (1 elem)
	SEQUENCE (2 elem)
	OBJECT IDENTIFIER 2.5.4.3 commonName (X.520 DN component)
	PrintableString Thawte RSA CA 2018
	```

	```dart
	// Base64 encoded string that represents the above structure
	var base64String =
	'MFwxCzAJBgNVBAYTAlVTMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5jb20xGzAZBgNVBAMTElRoYXd0ZSBSU0EgQ0EgMjAxOA==';
	// Convert to byte list
	var bytes = base64.decode(base64String);
	// Pass the byte list to the ASN1Parser
	var parser = ASN1Parser(bytes);
	```

	Now we can use the parser to move between every object within the above structure. The first element is an ASN1Sequence with 4 child elements.

	```dart
	// Grab the first element by calling nextObject() and cast it to ASN1Sequence
	var sequence = parser.nextObject() as ASN1Sequence;
	// Iterate over each element
	sequence.elements.forEach((element) {
	var asn1Set = element as ASN1Set;
	var seq = asn1Set.elements.elementAt(0) as ASN1Sequence
	var objectIdentifier = seq.elements.elementAt(0) as ASN1ObjectIdentifier;
	var printableString = seq.elements.elementAt(1) as ASN1PrintableString;
	print('${objectIdentifier.objectIdentifierAsString} = ${printableString.stringValue}')
	});
	```

	The above code will print out the following lines :

	```bash
	2.5.4.6 = US
	2.5.4.10 = DigiCert Inc
	2.5.4.11 = www.digicert.com
	2.5.4.3 = Thawte RSA CA 2018
	```

	## Encoding ASN1

	The ASN1 objects can be also used to create ASN1 structures and encode them and process them as base64 encoded string in other software. As an example, we will create a RSA Public Key PEM string.

	```dart

	final BEGIN_PUBLIC_KEY = '-----BEGIN PUBLIC KEY-----';
	final END_PUBLIC_KEY = '-----END PUBLIC KEY-----';

	// Create a new RSA pulic key
	var publicKey;

	// Create the top level sequence
	var topLevelSeq = ASN1Sequence();

	// Create the sequence holding the algorithm information
	var algorithmSeq = ASN1Sequence();
	var paramsAsn1Obj = ASN1Object.fromBytes(Uint8List.fromList([0x5, 0x0]));
	algorithmSeq.add(ASN1ObjectIdentifier.fromComponentString('1.2.840.113549.1.1.1'));
	algorithmSeq.add(paramsAsn1Obj);

	// Create the constructed ASN1BitString
	var modulus = ASN1Integer(publicKey.modulus);
	var exponent = ASN1Integer(publicKey.exponent);
	var publicKeySeqBitString = ASN1BitString(elements : [modulus, exponent], tag: ASN1Tags.BIT_STRING_CONSTRUCTED);

	// Add ASN1 objects to the top level sequence
	topLevelSeq.add(algorithmSeq);
	topLevelSeq.add(publicKeySeqBitString);

	// Encode base64
	var dataBase64 = base64.encode(topLevelSeq.encodedBytes);
	var chunks = StringUtils.chunk(dataBase64, 64);

	print('$BEGIN_PUBLIC_KEY\n${chunks.join('\n')}\n$END_PUBLIC_KEY');
	```

	The result will be something similar to this:

	```bash
	-----BEGIN PUBLIC KEY-----
	MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAg1ea9Y7zO2Gt7kzYOSp5
	I4dZHY75ZCYNMegmg0obKVxauRXeBL+pfhuDgq1+k0Z3iOfOELczOgaonTsJiHo8
	kQcqgYNj0dmKKb+/318+3aEIZa6PreIgWJ0scM0oupHeiEA/M45vQIDMOv6jjVa5
	mB1u/nHXQpvzH1i4H9tlODTSvIoIabW2/14+JNIm1KNQz/H/NsbooraY6POvqGtr
	Ek743CRJNH9mgEYEQnOF0dYiS8h+JoXxcIDuaLz/WCRx1AWvINj3YNBgiIc6N4/Y
	2nv5lAKajhfh8grs7hCRvXUzT9wcvj9aNtmOHm4cH/WpVK4sXGuLxN1MxDyqaPIv
	9QIDAQAB
	-----END PUBLIC KEY-----
	```

	And the ASN1 structure looks like this :

	```bash
	SEQUENCE (2 elem)
	SEQUENCE (2 elem)
	OBJECT IDENTIFIER 1.2.840.113549.1.1.1 rsaEncryption (PKCS #1)
	NULL
	BIT STRING (2160 bit) 001100001000001000000001000010100000001010000010000000010000000100000…
	SEQUENCE (2 elem)
	INTEGER (2048 bit) 165804177387087149617220457493747588873959131224426853644136343567339…
	INTEGER 65537
	```