SwiftASN1

Overview

ASN.1, and the DER encoding scheme, is a commonly used object serialization format. The most common use-cases for ASN.1 in general computing are in the cryptographic space, but there are a number of use-cases in a wide range of fields. This module provides an implementation of a number of ASN.1 types, as well as the DER serialization format for ASN.1.

ASN.1 can be used abstractly to describe essentially any kind of object. ASN.1 objects are made up of either primitive or composite (called “constructed”) types. Individual scalar objects can be combined into aggregate types, and composed essentially arbitrarily to form abstract object formats.

Importantly, the ASN.1 object description does not define a specific encoding for these objects. Instead there are a wide range of possible ways to serialize or deserialize an ASN.1 object. Some of the most prominent are BER (the Basic Encoding Rules), CER (the Canonical Encoding Rules), DER (the Distinguished Encoding Rules), and XER (the XML Encoding Rules). For the cryptographic use-case DER is the standard choice, as a given ASN.1 object can be encoded in only one way under DER. This makes signing and verifying vastly easier, as it is at least in principle possible to perfectly reconstruct the serialization of a parsed object.

This module provides several moving pieces:

1. A high-level representation of an ASN.1 object, in the form of a tree of object nodes (ASN1Node).

2. A DER parser that can construct the ASN.1 tree from serialized bytes (parse(_:)).

3. A DER serializer that can construct serialized bytes from the ASN.1 tree (Serializer).

4. A number of built-in ASN.1 types, representing common constructs.

5. A PEM parser and serializer

These moving pieces combine to provide support for the DER representation of ASN.1 suitable for a wide range of cryptographic uses.

Articles

• Encoding and Decoding DER

  Serialize and deserialize objects from DER format.

  Read More

• Parsing and Serializing PEM

  Serialize and deserialize objects from PEM format.

  Read More

Parsing DER

• static func parse([UInt8]) throws -> ASN1Node

  Parses an array of bytes as DER-encoded ASN.1 bytes.

• static func parse(ArraySlice<UInt8>) throws -> ASN1Node

  Parses an array of bytes as DER-encoded ASN.1 bytes.

• protocol DERParseable

  Defines a type that can be parsed from a DER-encoded form.

• protocol DERSerializable

  Defines a type that can be serialized in DER-encoded form.

• protocol DERImplicitlyTaggable

  An ASN.1 node that can tolerate having an implicit tag.

• static func sequence<T>(ASN1Node, identifier: ASN1Identifier, (inout ASN1NodeCollection.Iterator) throws -> T) throws -> T

  Parse the node as an ASN.1 SEQUENCE.

• static func sequence<T>(of: T.Type, identifier: ASN1Identifier, rootNode: ASN1Node) throws -> [T]

  Parse the node as an ASN.1 SEQUENCE OF.

• static func sequence<T>(of: T.Type, identifier: ASN1Identifier, nodes: inout ASN1NodeCollection.Iterator) throws -> [T]

  Parse the node as an ASN.1 SEQUENCE OF.

• static func set<T>(ASN1Node, identifier: ASN1Identifier, (inout ASN1NodeCollection.Iterator) throws -> T) throws -> T

  Parse the node as an ASN.1 SET.

• static func decodeDefault<T>(inout ASN1NodeCollection.Iterator, identifier: ASN1Identifier, defaultValue: T, (ASN1Node) throws -> T) throws -> T

  Parses a value that is encoded with a DEFAULT.

• static func decodeDefaultExplicitlyTagged<T>(inout ASN1NodeCollection.Iterator, tagNumber: UInt, tagClass: ASN1Identifier.TagClass, defaultValue: T, (ASN1Node) throws -> T) throws -> T

  Parses a value that is encoded with a DEFAULT and an explicit tag.

• static func decodeDefault<T>(inout ASN1NodeCollection.Iterator, defaultValue: T) throws -> T

  Parses a value that is encoded with a DEFAULT.

• static func decodeDefault<T>(inout ASN1NodeCollection.Iterator, identifier: ASN1Identifier, defaultValue: T) throws -> T

  Parses a value that is encoded with a DEFAULT.

• static func decodeDefaultExplicitlyTagged<T>(inout ASN1NodeCollection.Iterator, tagNumber: UInt, tagClass: ASN1Identifier.TagClass, defaultValue: T) throws -> T

  Parses a value that is encoded with a DEFAULT and an explicit tag.

• static func optionalExplicitlyTagged<T>(inout ASN1NodeCollection.Iterator, tagNumber: UInt, tagClass: ASN1Identifier.TagClass, (ASN1Node) throws -> T) throws -> T?

  Parses an optional explicitly tagged element.

• static func optionalImplicitlyTagged<T>(inout ASN1NodeCollection.Iterator, tag: ASN1Identifier) throws -> T?

  Parses an optional implicitly tagged element.

• static func explicitlyTagged<T>(ASN1Node, tagNumber: UInt, tagClass: ASN1Identifier.TagClass, (ASN1Node) throws -> T) throws -> T

  Parses an explicitly tagged element.

• static func explicitlyTagged<T>(inout ASN1NodeCollection.Iterator, tagNumber: UInt, tagClass: ASN1Identifier.TagClass, (ASN1Node) throws -> T) throws -> T

  Parses an explicitly tagged element.

Serializing DER

• struct Serializer

  An object that can serialize ASN.1 bytes.

• protocol DERSerializable

  Defines a type that can be serialized in DER-encoded form.

• protocol DERImplicitlyTaggable

  An ASN.1 node that can tolerate having an implicit tag.

Representing ASN.1 types

• struct ASN1Node

  An ASN1Node is a single entry in the ASN.1 representation of a data structure.

• struct ASN1NodeCollection

  Represents a collection of ASN.1 nodes contained in a constructed ASN.1 node.

• struct ASN1Identifier

  An ASN1Identifier is a representation of the abstract notion of an ASN.1 identifier.

Built-in ASN.1 types

• protocol ASN1IntegerRepresentable

  A protocol that represents any internal object that can present itself as an INTEGER, or be parsed from an INTEGER.

• struct IntegerBytesCollection<Integer>

  A big-endian Collection of bytes representing a fixed width integer.

• struct GeneralizedTime

  GeneralizedTime represents a date and time.

• struct ASN1BitString

  A bitstring is a representation of a sequence of bits.

• struct UTCTime

  UTCTime represents a date and time.

• struct ASN1OctetString

  An OCTET STRING is a representation of a string of octets.

• struct ASN1Any

  An ASN1 ANY represents…well, anything.

• struct ASN1Null

  An ASN1 NULL represents nothing.

• struct ASN1ObjectIdentifier

  An Object Identifier is a representation of some kind of object.

• struct ASN1UTF8String

  A UTF8String represents a string made up of UTF-8 bytes.

• struct ASN1PrintableString

  PrintableString represents a String made up of bytes that can reliably be printed in a terminal.

• struct ASN1BMPString

  BMPString is an uncommon ASN.1 string type.

• struct ASN1IA5String

  IA5String represents a String made up of ASCII characters.

• struct ASN1TeletexString

  TeletexString is an uncommon ASN.1 string type.

• struct ASN1UniversalString

  UniversalString is an uncommon ASN.1 string type.

Parsing and Serializing PEM

• typealias PEMRepresentable

  Defines a type that can be serialized in and parsed from PEM-encoded form.

• protocol PEMParseable

  Defines a type that can be parsed from a PEM-encoded form.

• protocol PEMSerializable

  Defines a type that can be serialized in PEM-encoded form.

• struct PEMDocument

  A PEM document is some data, and a discriminator type that is used to advertise the content.