modulede.dlkw.asn10.0.1

This module contains support to encode and decode ASN.1 values.

  • Encoding is done using the DER (distinguished encoding rules) to ensure a unique encoded represenation.

  • Decoding is done using the BER to accept a wider range of input. If the data to encode is not in canonical form (that is, if it violates the DER, that is signalled via the GenericAsn1Value.violatesDer flag on the decoded object.

A specific custom ASN.1 type is typically implemented using this module by implementing

  1. an Asn1Value subclass, which will be most likely a subclass of Asn1Sequence, Asn1SequenceOf or Asn1SetOf
  2. an instance creating function taking some “basic” Ceylon types as input, encode them using instance creating functions of other ASN.1 types and delegating to the constructor of the class implemented in step 1.
  3. a Decoder subclass using the decodeSequence, decodeSequenceOf or decodeSetOf function.
By: Dirk Lattermann
Packages
de.dlkw.asn1

Encoding and decoding of (several) standard ASN.1 types.

Dependencies
ceylon.buffer1.2.2
ceylon.collection1.2.2
ceylon.time1.2.2
ceylon.whole1.2.2
FunctionsInterfacesClasses

Encoding and decoding of (several) standard ASN.1 types.

Functions
asn1Booleanshared Asn1Boolean asn1Boolean(Boolean val, Tag tag = ...)

Creates an Asn1Boolean.

Parameters:
  • val

    The boolean value to represent as ASN.1 value.

  • tag = UniversalTag.boolean

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

asn1Integershared Asn1Integer asn1Integer(Integer valu, Tag tag = ...)

Creates an ASN.1 INTEGER value, implemented by Asn1Integer

Parameters:
  • valu

    The integer value to represent as ASN.1 value.

  • tag = UniversalTag.integer

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

asn1Nullshared Asn1Null asn1Null(Tag tag = ...)

Creates an Asn1Null value.

Parameters:
  • tag = UniversalTag.null

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

asn1Sequenceshared Asn1Sequence<Types>|EncodingError asn1Sequence<Types>(Types elements, [Asn1Value<Anything>|Option+] defaults, Tag tag = ...)
given Types satisfies [Asn1Value<Anything>?+]

Creates an Asn1Sequence.

If an element with a default value is passed in as null, then the default value (and not null) will be returned in Asn1Value.val.

Parameters:
  • elements

    The elements to put into the sequence.

    An optional element or an element with a DEFAULT value may be passed as null; in that case, it won't appear in the encoded output.

    An element with a DEFAULT value which is passed as this default value won't appear in the encoded output either (as per the DER).

  • defaults

    A list of default values or optional/mandatory indicators. This list must have the same number of elements as the elements argument.

    Each defaults element can either be an Option value to indicate a mandatory or an OPTIONAL sequence component; or it can be an Asn1Value, in which case it must have the same type as the corresponding element in the elements argument.

  • tag = UniversalTag.sequence

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

asn1SequenceOfshared Asn1SequenceOf<Inner> asn1SequenceOf<Inner>(Inner[] elements, Tag tag = ...)
given Inner satisfies Asn1Value<Anything>

Creates an Asn1SequenceOf.

Using different tags on the elements might not make sense in ASN.1. I don't know now. It is the user's responsibility that the elements all have the same tag, then.

Parameters:
  • elements

    The sequence components' values to repesent as ASN.1 value.

  • tag = UniversalTag.sequence

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

asn1Setshared Asn1Set<Types>|EncodingError asn1Set<Types>(Types elements, [Asn1Value<Anything>|Option+] defaults, Tag tag = ...)
given Types satisfies [Asn1Value<Anything>+]

Creates an Asn1Set. This is a difficult and confusing ASN.1 concept. Do not write ASN.1 specifications that use SET, use SEQUENCE instead! Decoding is not yet supported.

The attribute Asn1Value.val will return the elements in the order given in the elements parameter here, not in the order of the DER encoding!

Parameters:
  • tag = UniversalTag.set
asn1SetOfshared Asn1SetOf<Inner>|EncodingError asn1SetOf<Inner>(Inner[] elements, Tag tag = ...)
given Inner satisfies Asn1Value<Anything>

Creates an Asn1SetOf.

Using different tags on the elements might not make sense in ASN.1. I don't know now. It is the user's responsibility that the elements all have the same tag, then.

The attribute Asn1Value.val will return the elements in the order of the DER encoding.

Parameters:
  • elements

    The set components' values to repesent as ASN.1 value.

  • tag = UniversalTag.set

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

asn1Wholeshared Asn1Whole asn1Whole(Whole valu, Tag tag = ...)

Creates an ASN.1 INTEGER value, implemented by Asn1Whole

Parameters:
  • valu

    The integer value to represent as ASN.1 value.

  • tag = UniversalTag.integer

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

bitStringFromBytesshared BitString|EncodingError bitStringFromBytes(Byte[] bytes, Integer numberOfBits = ..., Tag tag = ...)

Creates a BitString.

Parameters:
  • bytes

    The bits to create the bit string from.

    Bit 7 of bytes[0] is the first bit to put into the bit string, then come bit 6 to bit 0, then bit 7 of bytes[1], and so on.

    Must have a size of (numberOfBits + 7) / 8.

  • numberOfBits = bytes.size * 8

    The length of the bit string, in bits.

  • tag = UniversalTag.bitString

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

decodeIdentityOctetsshared [IdentityInfo, Integer]|DecodingError decodeIdentityOctets(Byte[] input, Integer offset = 0)

Decodes the identity octets of a BER encoded ASN.1 value.

Returns identity octets information and pos of first octet after identity octets

Parameters:
  • input

    The input containing the identity octets to decode.

  • offset = 0

    Position in input where the identity octets (that is, the ASN.1 value) start.

decodeLengthOctetsshared [Integer, Integer, Boolean]|DecodingError decodeLengthOctets(Byte[] input, Integer offset)

Decodes the length octets of a BER encoded ASN.1 value.

Returns the decoded length, the position of the first octet in input after the length octets, and a flag if the DER were violated.

Parameters:
  • input

    The input containing the length octets to decode.

  • offset

    Position in input where the length octets start.

encodeAsn1Sequenceshared [Byte[], IdentityInfo, Integer, Integer]|EncodingError encodeAsn1Sequence(Asn1Value<Anything>?[] elements, <Asn1Value<Anything>|Option>[] defaults, Tag tag)

Encodes an ASN.1 SEQUENCE.

Returns the encoded octets, the identity octets info, the offset of the length octets in the encoded octets, and the the offset of the contents octets.

If a mandatory element is not given (null), then an EncodingError is returned.

Parameters:
  • elements

    The elements to put into the sequence.

    An optional element or an element with a DEFAULT value may be passed as null; in that case, it won't appear in the encoded output.

    An element with a DEFAULT value which is passed as this default value won't appear in the encoded output either (as per the DER).

  • defaults

    A list of default values or optional/mandatory indicators. This list must have the same number of elements as the elements argument.

    Each defaults element can either be an Option value to indicate a mandatory or an OPTIONAL sequence component; or it can be an Asn1Value, in which case it must have the same type as the corresponding element in the elements argument. In the latter case, it is used as the DEFAULT value for the sequence component.

  • tag

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

encodeLengthshared [Byte+] encodeLength(Integer length)

Encodes the length octets.

Parameters:
  • length

    The length to encode.

generalizedTimeFromInstantshared GeneralizedTime|EncodingError generalizedTimeFromInstant(Instant instant, Tag tag = ...)

Creates a GeneralizedTime from an Instant.

Parameters:
  • instant

    The instant to create a GeneralizedTime from.

  • tag = UniversalTag.generalizedTime

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

generalizedTimeFromStringshared GeneralizedTime|EncodingError generalizedTimeFromString(String stringValue, Tag tag = ...)

Creates a GeneralizedTime from a String.

Parameters:
  • stringValue

    The string to create a GeneralizedTime for.

    DER only allows form YYYYMMDDhhmmss[.d]Z where .d is decimal, arbitray precision, but no trailing zeroes nor dot.

  • tag = UniversalTag.generalizedTime

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

hexdigitsshared String hexdigits(Byte b)

Formats a Byte as a two-digit hexadecimal number.

hexdumpshared String hexdump({Byte*} bytes)

Format a Byte sequence as a sequence of two-digit hexadecimal numbers, separated by a space.

ia5Stringshared IA5String|EncodingError ia5String(String val, Tag tag = ...)

Creates an ASN.1 IA5String. Returns an error if val is not representable as ASCII.

Parameters:
  • tag = UniversalTag.ia5String
objectIdentifiershared ObjectIdentifier objectIdentifier(Integer[] parts, Tag tag = ...)

Creates an ObjectIdentifier.

Parameters:
  • parts

    The parts (between the dots) of the OID as Integers.

  • tag = UniversalTag.objectIdentifier

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

octetStringshared OctetString octetString(Byte[] val, Tag tag = ...)

Creates an OctetString.

Parameters:
  • tag = UniversalTag.octetString
printableStringshared PrintableString|EncodingError printableString(String val, Tag tag = ...)

Creates an ASN.1 PrintableString. Returns an error if val contains a character that is not allowed.

Parameters:
  • val

    Allowed characters are: A-Z, a-z, 0-9, '()+,-./:=?, and space.

  • tag = UniversalTag.printableString

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

taggedValueshared TaggedValue<Type> taggedValue<Type>(Type wrapped, Tag tag)
given Type satisfies GenericAsn1Value

Creates a TaggedValue, wrapping an ASN.1 value with an explicit tag.

Parameters:
  • wrapped

    The ASN.1 value that shall be explictly tagged.

  • tag

    The tag to use as explicit tag for the value.

utcTimeFromInstantshared UTCTime|EncodingError utcTimeFromInstant(Instant instant, Tag tag = ...)

Creates a UTCTime from an Instant.

Parameters:
  • instant

    The instant to create a UTCTime from.

  • tag = UniversalTag.utcTime

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

utcTimeFromStringshared UTCTime|EncodingError utcTimeFromString(String stringValue, Integer latestYearRepresentable, Tag tag = ...)

Creates a UTCTime from a String.

As the UTCTime class internally contains an Instant to represent the encoded point in time, the two-digit year part of the string must be interpreted as belonging to a specific century. Two-digit year values are rather useless if that is not done.

Parameters:
  • stringValue

    The string to create a UTCTime for.

    DER only allows form YYMMDDhhmmss[.d]Z where .d is decimal, arbitray precision, but no trailing zeroes nor dot.

  • latestYearRepresentable

    Determines how the two-digit year is interpreted.

    For example, if latestYearRepresentable == 2049, then

    • “50” means 1950,
    • “99” means 1999,
    • “00” means 2000,
    • “49” means 2049.
  • tag = UniversalTag.utcTime

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

utf8Stringshared UTF8String|EncodingError utf8String(String val, Tag tag = ...)

Creates an ASN.1 UTF8String. Restriction from X.690 (07/2002), 8.21.10 is not (yet) enforced. (“Announcers and escape sequences shall not be used, and each character shall be encoded in the smallest number of octets
available for that character.“)

Parameters:
  • tag = UniversalTag.utf8String

    The (IMPLICIT) tag that should be used in the encoding. If omitted, the standard tag of class UNIVERSAL is used.

Interfaces
AnySwitchshared AnySwitch

Manages type information of a SEQUENCE component of type ANY DEFINED BY.

Classes
AnySwitchRegistryshared abstract AnySwitchRegistry

AnySwitch that looks up decoders in a Map, given a discriminator value.

Asn1Booleanshared Asn1Boolean

Represents an ASN.1 BOOLEAN value.

Asn1BooleanDecodershared Asn1BooleanDecoder

Decodes BOOLEAN. Returns an error if the length octets encode any value other than 1

Asn1Integershared Asn1Integer

Represents an ASN.1 INTEGER value, restricted to values representable in 4 octets.

For a larger range, please use Asn1Whole.

Asn1IntegerDecodershared Asn1IntegerDecoder

Decodes INTEGER to an Asn1Integer. Returns an error if the value is not representable in 4 bytes, (or if the encoding is invalid).

Asn1Nullshared Asn1Null

Represents an ASN.1 NULL value.

Asn1NullDecodershared Asn1NullDecoder

Decodes NULL.

Asn1Sequenceshared Asn1Sequence<out Types>
given Types satisfies [GenericAsn1Value?+]

Represents an ASN.1 SEQUENCE value.

The Types parameter defines the types the individual components of the ASN.1 SEQUENCE. Such a component may cover Null. This is used if (and only if) the SEQUENCE component is OPTIONAL. A sequence instance with an omitted optional component is represented as a null value.

Asn1SequenceOfshared Asn1SequenceOf<Inner>
given Inner satisfies Asn1Value<Anything>

Represents an ASN.1 SEQUENCE OF value.

Asn1Setshared Asn1Set<Types>
given Types satisfies [Asn1Value<Anything>?+]

Represents an ASN.1 SET value. This is not yet supported, and a Decoder for SET is missing.

The Types parameter defines the types the individual components of the ASN.1 SET. Such a component may cover Null. This is used if (and only if) the SEQUENCE component is OPTIONAL. A sequence instance with an omitted optional component is represented as a null value.

Asn1SetOfshared Asn1SetOf<Inner>
given Inner satisfies Asn1Value<Anything>

Represents an ASN.1 SET OF value.

Asn1Valueshared abstract Asn1Value<out Value>
given Value satisfies Anything

Base class for an ASN.1 value whose type definition is known.

This class can store a Ceylon value corresponding to the ASN.1 value, but if that's not feasible (as for example in OCTET STRING: contents possibly long but easy to decode), that Ceylon value may be calculated on the fly from the encoding.

Asn1Wholeshared Asn1Whole

Represents an ASN.1 INTEGER value that can represent arbitrary large values using Whole.

Asn1WholeDecodershared Asn1WholeDecoder

Decodes INTEGER to an Asn1Whole.

BitStringshared BitString

Represents an ASN.1 BIT STRING value.

Parameter types of the Asn1Value super class are for octet string contents and number of bits. The last octet in the octet string contents may contain unused bits.

BitStringDecodershared BitStringDecoder

Decodes BIT STRING.

ChoiceDecodershared ChoiceDecoder<P>
given P satisfies Asn1Value<Anything>

Decodes CHOICE.

Type parameter Þ is supposed to be the union type of all possible alternatives of the CHOICE.

Decodershared abstract Decoder<out Asn1Type>
given Asn1Type satisfies GenericAsn1Value

A decoder for an ASN.1 type.

DecodingErrorshared DecodingError

Returned if an error occured while decoding.

Descriptorshared Descriptor<out Element>
given Element satisfies GenericAsn1Value

Describes the definition of a SEQUENCE or SET component. Needed because not all information is available in the decoders used.

EncodingErrorshared EncodingError

Returned if an error occured while encoding.

EncodingMethodshared EncodingMethod

Enum class for the length encoding methods.

GeneralizedTimeshared GeneralizedTime

Represents an ASN.1 GeneralizedTime value.

GeneralizedTimeDecodershared GeneralizedTimeDecoder

Decodes GeneralizedTime.

GenericAsn1Valueshared GenericAsn1Value

A generic ASN.1 value with the information that can minimally be known without knowledge of its type's ASN.1 definition. A GenericAsn1Value always stores the encoded form.

GenericAsn1ValueDecodershared GenericAsn1ValueDecoder

Decodes an ASN.1 value without knowing its type definition.

GenericSequenceDecodershared GenericSequenceDecoder

Decodes a SEQUENCE without knowing the ASN.1 specification for it.

IA5Stringshared IA5String

Represent an ASN.1 IA5String value.

IA5String is treated like ASCII.

IA5StringDecodershared IA5StringDecoder

Decodes IA5String. Returns an error if the contents contains octets that are not ASCII values, that is, if they larger than 127.

IdentityInfoshared IdentityInfo

Information from the identity octets of an ASN.1 value according to the BER.

ObjectIdentifiershared ObjectIdentifier

Represents an ASN.1 OBJECT IDENTIFIER value.

ObjectIdentifierDecodershared ObjectIdentifierDecoder

Decodes OBJECT IDENTIFIER.

OctetStringshared OctetString

Represents an ASN.1 OCTET STRING value.

OctetStringDecodershared OctetStringDecoder

Decodes OCTET STRING.

Optionshared Option

Enum class to indicate if a sequence/set value is mandatory or optional.

PrintableStringshared PrintableString

Represents an ASN.1 PrintableString value.

PrintableStringDecodershared PrintableStringDecoder

Decodes PrintableString.

SequenceDecodershared SequenceDecoder<out Types>
given Types satisfies [GenericAsn1Value?+]

Decodes SEQUENCE.

SequenceOfDecodershared SequenceOfDecoder<Inner>
given Inner satisfies Asn1Value<Anything>

Decodes SEQUENCE OF.

SetOfDecodershared SetOfDecoder<Inner>
given Inner satisfies Asn1Value<Anything>

Decodes a SET OF.

StdDecodershared abstract StdDecoder<Asn1Type>
given Asn1Type satisfies Asn1Value<Anything>

An experimental helper decoder that does calculation and return of the next position value. It is questionable if that is really of much use.

Tagshared Tag

An ASN.1 tag consisting of tag class and number.

TagClassshared TagClass

The class of an ASN.1 tag.

TaggedValueshared TaggedValue<out Type>
given Type satisfies GenericAsn1Value

Represents an ASN.1 value with an EXPLICIT tag (used in a SEQUENCE, SET or CHOICE).

TaggedValueDecodershared TaggedValueDecoder<Type>
given Type satisfies GenericAsn1Value

Decodes an ASN.1 value with an EXPLICIT tag.

UTCTimeshared UTCTime

Represents an ASN.1 UTCTime value.

UTCTimeDecodershared UTCTimeDecoder

Decodes UTCTime.

UTF8Stringshared UTF8String

Represents an ASN.1 UTF8String value.

UTF8StringDecodershared UTF8StringDecoder

Decodes UTF8String.

Returns an error if the contents contains octets that are not a valid UTF-8 sequence.

UniversalTagshared UniversalTag

Enum class for the (supported) tags in tag class UNIVERSAL.