# asn1

This module provides ASN.1 encoder and decoder.

class asn1.Classes(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

class asn1.Decoder

  ASN.1 decoder. Understands BER (and DER which is a subset).

  enter() → None

    This method enters the constructed type that is at the current decoding offset.

    Note

    It is an error to call `Decoder.enter()` if the to be decoded ASN.1 tag is not of a constructed type.

    Returns:

      None

  eof() → bool

    Return True if we are at the end of input.

    Returns:

      bool – True if all input has been decoded, and False otherwise.

  leave() → None

    This method leaves the last constructed type that was `Decoder.enter()`-ed.

    Note

    It is an error to call `Decoder.leave()` if the current ASN.1 tag is not of a constructed type.

    Returns:

      None

  peek() → Tag

    This method returns the current ASN.1 tag (i.e. the tag that a subsequent `Decoder.read()` call would return) without updating the decoding offset. In case no more data is available from the input, this method returns `None` to signal end-of-file.

    This method is useful if you don’t know whether the next tag will be a primitive or a constructed tag. Depending on the return value of `peek`, you would decide to either issue a `Decoder.read()` in case of a primitive type, or an `Decoder.enter()` in case of a constructed type.

    Note

    Because this method does not advance the current offset in the input, calling it multiple times in a row will return the same value for all calls.

    Returns:

      `Tag` – The current ASN.1 tag.

    Raises:

      Error –

  read(tagnr: Number = None)

    This method decodes one ASN.1 tag from the input and returns it as a `(tag, value)` tuple. `tag` is a 3-tuple `(nr, typ, cls)`, while `value` is a Python object representing the ASN.1 value. The offset in the input is increased so that the next `Decoder.read()` call will return the next tag. In case no more data is available from the input, this method returns `None` to signal end-of-file.

    Returns:

      `Tag`, value – The current ASN.1 tag and its value.

    Raises:

      Error –

  start(data: bytes) → None

    This method instructs the decoder to start decoding the ASN.1 input `data`, which must be a passed in as plain Python bytes. This method may be called at any time to start a new decoding job. If this method is called while currently decoding another input, that decoding context is discarded.

    Note

    It is not necessary to specify the encoding because the decoder assumes the input is in BER or DER format.

    Parameters:

      data (bytes) – ASN.1 input, in BER or DER format, to be decoded.

    Returns:

      None

    Raises:

      Error –

class asn1.Encoder

  ASN.1 encoder. Uses DER encoding.

  construct(nr: int, cls: int = None) → None

    This method - context manager calls enter and leave methods, for better code mapping.

    Usage: ``` with encoder.construct(asn1.Numbers.Sequence):

    > encoder.write(1) with encoder.construct(asn1.Numbers.Sequence):

    > > encoder.write(‘foo’) encoder.write(‘bar’)

    > encoder.write(2)

    ``` encoder.output() will result following structure: SEQUENCE:

    > INTEGER: 1 SEQUENCE:

    > > STRING: foo STRING: bar

    > INTEGER: 2

    Parameters:

      - nr (int) – The desired ASN.1 type. Use `Numbers` enumeration.

      - cls (int) – This optional parameter specifies the class of the constructed type. The default class to use is the universal class. Use `Classes` enumeration.

    Returns:

      None

    Raises:

      Error –

  enter(nr: int, cls: int = None) → None

    This method starts the construction of a constructed type.

    Parameters:

      - nr (int) – The desired ASN.1 type. Use `Numbers` enumeration.

      - cls (int) – This optional parameter specifies the class of the constructed type. The default class to use is the universal class. Use `Classes` enumeration.

    Returns:

      None

    Raises:

      Error –

  leave() → None

    This method completes the construction of a constructed type and writes the encoded representation to the output buffer.

  output() → bytes

    This method returns the encoded ASN.1 data as plain Python `bytes`. This method can be called multiple times, also during encoding. In the latter case the data that has been encoded so far is returned.

    Note

    It is an error to call this method if the encoder is still constructing a constructed type, i.e. if `Encoder.enter()` has been called more times that `Encoder.leave()`.

    Returns:

      bytes – The DER encoded ASN.1 data.

    Raises:

      Error –

  start() → None

    This method instructs the encoder to start encoding a new ASN.1 output. This method may be called at any time to reset the encoder, and resets the current output (if any).

  write(value: object, nr: int = None, typ: int = None, cls: int = None) → None

    This method encodes one ASN.1 tag and writes it to the output buffer.

    Note

    Normally, `value` will be the only parameter to this method. In this case Python-ASN1 will autodetect the correct ASN.1 type from the type of `value`, and will output the encoded value based on this type.

    Parameters:

      - value (any) – The value of the ASN.1 tag to write. Python-ASN1 will try to autodetect the correct ASN.1 type from the type of `value`.

      - nr (int) – If the desired ASN.1 type cannot be autodetected or is autodetected wrongly, the `nr` parameter can be provided to specify the ASN.1 type to be used. Use `Numbers` enumeration.

      - typ (int) – This optional parameter can be used to write constructed types to the output by setting it to indicate the constructed encoding type. In this case, `value` must already be valid ASN.1 encoded data as plain Python bytes. This is not normally how constructed types should be encoded though, see `Encoder.enter()` and `Encoder.leave()` for the recommended way of doing this. Use `Types` enumeration.

      - cls (int) – This parameter can be used to override the class of the `value`. The default class is the universal class. Use `Classes` enumeration.

    Returns:

      None

    Raises:

      Error –

exception asn1.Error

  ASN.11 encoding or decoding error.

class asn1.Numbers(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

class asn1.Tag(nr, typ, cls)

  A named tuple to represent ASN.1 tags as returned by `Decoder.peek()` and `Decoder.read()`.

  cls

    Alias for field number 2

  nr

    Alias for field number 0

  typ

    Alias for field number 1

class asn1.Types(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)