diff options
Diffstat (limited to 'docs/source/pyasn1')
-rw-r--r-- | docs/source/pyasn1/contents.rst | 14 | ||||
-rw-r--r-- | docs/source/pyasn1/error/contents.rst | 60 | ||||
-rw-r--r-- | docs/source/pyasn1/type/base/asn1type.rst | 10 | ||||
-rw-r--r-- | docs/source/pyasn1/type/base/constructedasn1type.rst | 10 | ||||
-rw-r--r-- | docs/source/pyasn1/type/base/contents.rst | 20 | ||||
-rw-r--r-- | docs/source/pyasn1/type/base/novalue.rst | 6 | ||||
-rw-r--r-- | docs/source/pyasn1/type/base/simpleasn1type.rst | 10 | ||||
-rw-r--r-- | docs/source/pyasn1/type/opentype/contents.rst | 94 | ||||
-rw-r--r-- | docs/source/pyasn1/type/opentype/opentype.rst | 7 | ||||
-rw-r--r-- | docs/source/pyasn1/type/univ/contents.rst | 4 | ||||
-rw-r--r-- | docs/source/pyasn1/type/univ/sequence.rst | 9 | ||||
-rw-r--r-- | docs/source/pyasn1/type/univ/sequenceof.rst | 8 | ||||
-rw-r--r-- | docs/source/pyasn1/type/univ/set.rst | 8 | ||||
-rw-r--r-- | docs/source/pyasn1/type/univ/setof.rst | 8 |
14 files changed, 232 insertions, 36 deletions
diff --git a/docs/source/pyasn1/contents.rst b/docs/source/pyasn1/contents.rst index 474bbff..eaa7835 100644 --- a/docs/source/pyasn1/contents.rst +++ b/docs/source/pyasn1/contents.rst @@ -139,6 +139,7 @@ type's values. .. toctree:: :maxdepth: 2 + /pyasn1/type/base/contents /pyasn1/type/univ/contents /pyasn1/type/char/contents /pyasn1/type/useful/contents @@ -212,3 +213,16 @@ implemented in pyasn1. /pyasn1/codec/cer/contents /pyasn1/codec/der/contents /pyasn1/codec/native/contents + +Exceptions +---------- + +Operations on PyASN1 schema and value objects might cause errors. These +errors are manifested to the caller in form of Python exceptions. + +The exception hierarchy is as follows (ordered from least specific). + +.. toctree:: + :maxdepth: 2 + + /pyasn1/error/contents diff --git a/docs/source/pyasn1/error/contents.rst b/docs/source/pyasn1/error/contents.rst new file mode 100644 index 0000000..be8a04c --- /dev/null +++ b/docs/source/pyasn1/error/contents.rst @@ -0,0 +1,60 @@ + +.. _error.PyAsn1Error: + +.. |PyAsn1Error| replace:: PyAsn1Error + +|PyAsn1Error| +------------- + +.. autoclass:: pyasn1.error.PyAsn1Error + :members: + +.. _error.ValueConstraintError: + +.. |ValueConstraintError| replace:: ValueConstraintError + +|ValueConstraintError| +---------------------- + +.. autoclass:: pyasn1.error.ValueConstraintError + :members: + +.. _error.SubstrateUnderrunError: + +.. |SubstrateUnderrunError| replace:: SubstrateUnderrunError + +|SubstrateUnderrunError| +------------------------ + +.. autoclass:: pyasn1.error.SubstrateUnderrunError + :members: + +.. _error.PyAsn1UnicodeError: + +.. |PyAsn1UnicodeError| replace:: PyAsn1UnicodeError + +|PyAsn1UnicodeError| +-------------------- + +.. autoclass:: pyasn1.error.PyAsn1UnicodeError + :members: + +.. _error.PyAsn1UnicodeDecodeError: + +.. |PyAsn1UnicodeDecodeError| replace:: PyAsn1UnicodeDecodeError + +|PyAsn1UnicodeDecodeError| +-------------------------- + +.. autoclass:: pyasn1.error.PyAsn1UnicodeDecodeError + :members: + +.. _error.PyAsn1UnicodeEncodeError: + +.. |PyAsn1UnicodeEncodeError| replace:: PyAsn1UnicodeEncodeError + +|PyAsn1UnicodeEncodeError| +-------------------------- + +.. autoclass:: pyasn1.error.PyAsn1UnicodeEncodeError + :members: diff --git a/docs/source/pyasn1/type/base/asn1type.rst b/docs/source/pyasn1/type/base/asn1type.rst new file mode 100644 index 0000000..94fe04d --- /dev/null +++ b/docs/source/pyasn1/type/base/asn1type.rst @@ -0,0 +1,10 @@ + +.. _base.Asn1Type: + +.. |ASN.1| replace:: Asn1Type + +|ASN.1| type +------------ + +.. autoclass:: pyasn1.type.base.Asn1Type(tagSet=TagSet(), subtypeSpec=ConstraintsIntersection()) + :members: isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, subtypeSpec diff --git a/docs/source/pyasn1/type/base/constructedasn1type.rst b/docs/source/pyasn1/type/base/constructedasn1type.rst new file mode 100644 index 0000000..54d828f --- /dev/null +++ b/docs/source/pyasn1/type/base/constructedasn1type.rst @@ -0,0 +1,10 @@ + +.. _base.ConstructedAsn1Type: + +.. |ASN.1| replace:: ConstructedAsn1Type + +|ASN.1| type +------------ + +.. autoclass:: pyasn1.type.base.ConstructedAsn1Type(tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection(), componentType=None) + :members: isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, subtypeSpec diff --git a/docs/source/pyasn1/type/base/contents.rst b/docs/source/pyasn1/type/base/contents.rst new file mode 100644 index 0000000..ffb325c --- /dev/null +++ b/docs/source/pyasn1/type/base/contents.rst @@ -0,0 +1,20 @@ + +.. _type.base: + +ASN.1 type system +----------------- + +The ASN.1 language defines a collection of data types such as *INTEGER* +or *SET*. With pyasn1, ASN.1 types are represented by Python classes. +The base classes are described in this part of the documentation. + +User code might not need to use them directly, except for figuring out +if given object belongs to ASN.1 type or not. + +.. toctree:: + :maxdepth: 2 + + /pyasn1/type/base/asn1type + /pyasn1/type/base/simpleasn1type + /pyasn1/type/base/constructedasn1type + /pyasn1/type/base/novalue diff --git a/docs/source/pyasn1/type/base/novalue.rst b/docs/source/pyasn1/type/base/novalue.rst new file mode 100644 index 0000000..6e34792 --- /dev/null +++ b/docs/source/pyasn1/type/base/novalue.rst @@ -0,0 +1,6 @@ +.. _type.base.NoValue: + +NoValue sentinel +---------------- + +.. autoclass:: pyasn1.type.base.NoValue() diff --git a/docs/source/pyasn1/type/base/simpleasn1type.rst b/docs/source/pyasn1/type/base/simpleasn1type.rst new file mode 100644 index 0000000..03a960d --- /dev/null +++ b/docs/source/pyasn1/type/base/simpleasn1type.rst @@ -0,0 +1,10 @@ + +.. _base.SimpleAsn1Type: + +.. |ASN.1| replace:: SimpleAsn1Type + +|ASN.1| type +------------ + +.. autoclass:: pyasn1.type.base.SimpleAsn1Type(value=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection()) + :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, subtypeSpec diff --git a/docs/source/pyasn1/type/opentype/contents.rst b/docs/source/pyasn1/type/opentype/contents.rst index 9ae10d0..034870b 100644 --- a/docs/source/pyasn1/type/opentype/contents.rst +++ b/docs/source/pyasn1/type/opentype/contents.rst @@ -1,16 +1,67 @@ .. _type.opentype: -Untyped fields of constructed types ------------------------------------ +Dynamic or open type +-------------------- -To aid data structures flexibility, ASN.1 allows the designer to -leave incomplete field type specification in the -:ref:`Sequence <univ.Sequence>` and :ref:`Set <univ.Set>` types. +ASN.1 allows data structure designer to leave "holes" in field type +specification of :ref:`Sequence <univ.Sequence>` or +:ref:`Set <univ.Set>` types. -To figure out field's type at the run time, a type selector field -must accompany the open type field. The open type situation can -be captured by the :ref:`OpenType <opentype.OpenType>` object. +The idea behind that feature is that there can be times, when the +exact field type is not known at the design time, or it is anticipated +that new field types may come up in the future. + +This "hole" type is manifested in the data structure by :ref:`Any <univ.Any>` +type. Technically, the actual type is serialized into an octet stream +and then put into :ref:`Any <univ.Any>` "container", which is in fact an +(untagged, by default) specialization of ASN.1 +:ref:`OctetString <univ.OctetString>` type. + +.. code-block:: bash + + Algorithm ::= SEQUENCE { + algorithm OBJECT IDENTIFIER, + parameters ANY DEFINED BY algorithm OPTIONAL + } + +On the receiving end, to know how to interpret the open type +serialization, the receiver can rely on the supplied value in +the other field of the data structure. That other field is +semantically linked with the open type field. This link +is expressed in ASN.1 by the *DEFINE BY* clause. + +From ASN.1 perspective, it is not an error if the decoder does +not know a type selector value it receives. In that case pyasn1 decoder +just leaves serialized blob in the open type field. + +.. note:: + + By default, ASN.1 ANY type has no tag. That makes it an + "invisible" in serialization. However, like any other ASN.1 type, + ANY type can be subtyped by :ref:`tagging <type.tag>`. + +Besides scalar open type fields, ASN.1 allows using *SET OF* +or *SEQUENCE OF* containers holding zero or more of *ANY* +scalars. + +.. code-block:: bash + + AttributeTypeAndValues ::= SEQUENCE { + type OBJECT IDENTIFIER, + values SET OF ANY DEFINED BY type + } + +.. note:: + + A single type selector field is used to guide the decoder + of potentially many elements of a *SET OF* or *SEQUENCE OF* container + all at once. That implies that all *ANY* elements must be of the same + type in any given instance of a data structure. + +When expressing ASN.1 type "holes" in pyasn1, the +:ref:`OpenType <opentype.OpenType>` object should be used to establish +a semantic link between type selector field and open type field. .. code-block:: python @@ -24,15 +75,38 @@ be captured by the :ref:`OpenType <opentype.OpenType>` object. """ Algorithm ::= SEQUENCE { algorithm OBJECT IDENTIFIER, - parameters ANY DEFINED BY algorithm OPTIONAL + parameters ANY DEFINED BY algorithm } """ componentType = NamedTypes( NamedType('algorithm', ObjectIdentifier()), - OptionalNamedType('parameters', Any(), + NamedType('parameters', Any(), openType=OpenType('algorithm', algo_map)) ) +Similarly for `SET OF ANY DEFINED BY` or `SEQUENCE OF ANY DEFINED BY` +constructs: + +.. code-block:: python + + algo_map = { + ObjectIdentifier('1.2.840.113549.1.1.1'): rsaEncryption(), + ObjectIdentifier('1.2.840.113549.1.1.2'): md2WithRSAEncryption() + } + + + class Algorithm(Sequence): + """ + Algorithm ::= SEQUENCE { + algorithm OBJECT IDENTIFIER, + parameters SET OF ANY DEFINED BY algorithm + } + """ + componentType = NamedTypes( + NamedType('algorithm', ObjectIdentifier()), + NamedType('parameters', SetOf(componentType=Any()), + openType=OpenType('algorithm', algo_map)) + ) .. toctree:: :maxdepth: 2 diff --git a/docs/source/pyasn1/type/opentype/opentype.rst b/docs/source/pyasn1/type/opentype/opentype.rst index dc2fa47..8ce9303 100644 --- a/docs/source/pyasn1/type/opentype/opentype.rst +++ b/docs/source/pyasn1/type/opentype/opentype.rst @@ -9,9 +9,4 @@ .. autoclass:: pyasn1.type.opentype.OpenType :members: - .. note:: - - The |OpenType| class models an untyped field of a constructed ASN.1 - type. In ASN.1 syntax it is usually represented by the - `ANY DEFINED BY` clause. Typically used with :ref:`Any <univ.Any>` - type. +More information on open type use can be found :ref:`here <type.opentype>`.
\ No newline at end of file diff --git a/docs/source/pyasn1/type/univ/contents.rst b/docs/source/pyasn1/type/univ/contents.rst index 2a5ba25..d546e1c 100644 --- a/docs/source/pyasn1/type/univ/contents.rst +++ b/docs/source/pyasn1/type/univ/contents.rst @@ -32,7 +32,3 @@ and constructed. /pyasn1/type/univ/set /pyasn1/type/univ/sequence /pyasn1/type/univ/choice - -.. _univ.noValue: - -.. autoclass:: pyasn1.type.univ.NoValue() diff --git a/docs/source/pyasn1/type/univ/sequence.rst b/docs/source/pyasn1/type/univ/sequence.rst index 6d2c6b5..0988004 100644 --- a/docs/source/pyasn1/type/univ/sequence.rst +++ b/docs/source/pyasn1/type/univ/sequence.rst @@ -6,14 +6,15 @@ |ASN.1| type ------------ -.. autoclass:: pyasn1.type.univ.Sequence(componentType=None, tagSet=tagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection()) +.. autoclass:: pyasn1.type.univ.Sequence(componentType=NamedTypes(), tagSet=tagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection()) :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec, getComponentByPosition, - setComponentByPosition, getComponentByName, setComponentByName, setDefaultComponents + setComponentByPosition, getComponentByName, setComponentByName, setDefaultComponents, + clear, reset .. note:: The |ASN.1| type models a collection of named ASN.1 components. Ordering of the components **is** preserved upon de/serialisation. - .. automethod:: pyasn1.type.univ.Sequence.clone(componentType=None, tagSet=tagSet(), subtypeSpec=ConstraintsIntersection()) - .. automethod:: pyasn1.type.univ.Sequence.subtype(componentType=None, implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection()) + .. automethod:: pyasn1.type.univ.Sequence.clone(componentType=NamedTypes(), tagSet=tagSet(), subtypeSpec=ConstraintsIntersection()) + .. automethod:: pyasn1.type.univ.Sequence.subtype(componentType=NamedTypes(), implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection()) diff --git a/docs/source/pyasn1/type/univ/sequenceof.rst b/docs/source/pyasn1/type/univ/sequenceof.rst index dadef67..6a09b92 100644 --- a/docs/source/pyasn1/type/univ/sequenceof.rst +++ b/docs/source/pyasn1/type/univ/sequenceof.rst @@ -6,14 +6,14 @@ |ASN.1| type ------------ -.. autoclass:: pyasn1.type.univ.SequenceOf(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection()) +.. autoclass:: pyasn1.type.univ.SequenceOf(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection()) :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec, - getComponentByPosition, setComponentByPosition + getComponentByPosition, setComponentByPosition, clear, reset .. note:: The |ASN.1| type models a collection of elements of a single ASN.1 type. Ordering of the components **is** preserved upon de/serialisation. - .. automethod:: pyasn1.type.univ.SequenceOf.clone(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection()) - .. automethod:: pyasn1.type.univ.SequenceOf.subtype(componentType=None, implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection()) + .. automethod:: pyasn1.type.univ.SequenceOf.clone(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection()) + .. automethod:: pyasn1.type.univ.SequenceOf.subtype(componentType=NoValue(), implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection()) diff --git a/docs/source/pyasn1/type/univ/set.rst b/docs/source/pyasn1/type/univ/set.rst index 5c75938..792d2e9 100644 --- a/docs/source/pyasn1/type/univ/set.rst +++ b/docs/source/pyasn1/type/univ/set.rst @@ -6,15 +6,15 @@ |ASN.1| type ------------ -.. autoclass:: pyasn1.type.univ.Set(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection()) +.. autoclass:: pyasn1.type.univ.Set(componentType=NamedTypes(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection()) :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec, getComponentByPosition, setComponentByPosition, getComponentByName, setComponentByName, setDefaultComponents, - getComponentByType, setComponentByType + getComponentByType, setComponentByType, clear, reset .. note:: The |ASN.1| type models a collection of named ASN.1 components. Ordering of the components **is not** preserved upon de/serialisation. - .. automethod:: pyasn1.type.univ.Set.clone(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection()) - .. automethod:: pyasn1.type.univ.Set.subtype(componentType=None, implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection()) + .. automethod:: pyasn1.type.univ.Set.clone(componentType=NamedTypes(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection()) + .. automethod:: pyasn1.type.univ.Set.subtype(componentType=NamedTypes(), implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection()) diff --git a/docs/source/pyasn1/type/univ/setof.rst b/docs/source/pyasn1/type/univ/setof.rst index 0317f4a..67ef92f 100644 --- a/docs/source/pyasn1/type/univ/setof.rst +++ b/docs/source/pyasn1/type/univ/setof.rst @@ -6,14 +6,14 @@ |ASN.1| type ------------ -.. autoclass:: pyasn1.type.univ.SetOf(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection()) +.. autoclass:: pyasn1.type.univ.SetOf(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection(), sizeSpec=ConstraintsIntersection()) :members: isValue, isSameTypeWith, isSuperTypeOf, tagSet, effectiveTagSet, tagMap, componentType, subtypeSpec, sizeSpec, - Â getComponentByPosition, setComponentByPosition + Â getComponentByPosition, setComponentByPosition, clear, reset .. note:: The |ASN.1| type models a collection of elements of a single ASN.1 type. Ordering of the components **is not** preserved upon de/serialisation. - .. automethod:: pyasn1.type.univ.SetOf.clone(componentType=None, tagSet=TagSet(), subtypeSpec=ConstraintsIntersection()) - .. automethod:: pyasn1.type.univ.SetOf.subtype(componentType=None, implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection()) + .. automethod:: pyasn1.type.univ.SetOf.clone(componentType=NoValue(), tagSet=TagSet(), subtypeSpec=ConstraintsIntersection()) + .. automethod:: pyasn1.type.univ.SetOf.subtype(componentType=NoValue(), implicitTag=Tag(), explicitTag=Tag(),subtypeSpec=ConstraintsIntersection()) |