asn1

class asn1.Classes(*values)[source]: ASN.1 tag classes.

class asn1.Decoder(stream: RawIOBase | BufferedIOBase | bytes | None = None)[source]

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

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. It is no more necessary to call this method. It is kept only for compatibility with previous versions of the library.

Returns:: None

eof() → bool[source]

Return True if we are at the end of input.

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

leave() → None[source]

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. It is no more necessary to call this method. It is kept only for compatibility with previous versions of the library.

Returns:: None

peek() → Tag | None[source]

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(flags: ReadFlags = ReadFlags.OnlyValue) → Tuple[Tag | None, Any][source]

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 number of unused bits can be requested in the flags parameter. When ReadFlags.OnlyValue is specified, the method the tuple (tag, (value, unused)). unused is the number of unused bits removed from the 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.

Parameters:: flags (asn1.DecoderFlags) – Return only the value or the value and the number of unused bits as a tuple.
Returns:: Tag, value – The current ASN.1 tag, its value and the number of unused bits if requested in start.
Raises:: Error –

start(stream: RawIOBase | BufferedIOBase | bytes) → None[source]

This method instructs the decoder to start decoding an ASN.1 input. 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:: stream (DecoderStream) – ASN.1 input, in BER or DER format, to be decoded.
Returns:: None
Raises:: Error –

class asn1.Encoder(stream: RawIOBase | BufferedWriter | None = None, encoding: Encoding | None = None)[source]

ASN.1 encoder. Uses DER encoding.

construct(nr: int, cls: int | None = None) → Generator[None, Any, None][source]

This method is a context manager that calls the 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 in the 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, optional) – Specifies the class of the constructed type. The default class is the universal class. Use Classes enumeration.

Returns:

None

Raises:

Error –

enter(nr: int, cls: int | None = None) → None[source]

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[source]: This method completes the construction of a constructed type and writes the encoded representation to the output stream.

output() → bytes[source]

This method returns the encoded ASN.1 data as plain Python bytes. With DER encoding and a stream, this method has to be called when all data are encoded. Otherwise, the stream will contain partial data. With DER encoding and no stream, this method has to be called multiple times. The data that has been encoded so far is returned. When using CER encoding, you do not need to call it at all. With CER, this method can only be called when using a BytesIO stream or no stream.

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 or CER encoded ASN.1 data.
Raises:: Error –

start(stream: RawIOBase | BufferedWriter | None = None, encoding: Encoding | None = None) → None[source]

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 reset the current output (if any).

Parameters:

stream (EncoderStream) – The output stream or the encoding with no stream.
encoding (Encoding or None) – The encoding (DER or CER) to use.

write(value: Any, nr: int | None = None, typ: int | None = None, cls: int | None = None) → None[source]

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 –

class asn1.Encoding(*values)[source]: ASN.1 encoding types.

exception asn1.Error[source]: ASN.11 encoding or decoding error.

class asn1.Numbers(*values)[source]: ASN.1 tag numbers.

class asn1.ReadFlags(*values)[source]: How to read values that may have unused bits.

class asn1.Tag(nr, typ, cls)

cls: Alias for field number 2

nr: Alias for field number 0

typ: Alias for field number 1

class asn1.Types(*values)[source]: ASN.1 tag types.