asn1.types.universal.external source code

1 module asn1.types.universal.external;
2 import asn1.types.identification;
3 
4 /**
5     According to the
6     $(LINK https://www.itu.int/en/pages/default.aspx, International Telecommunications Union)'s
7     $(LINK https://www.itu.int/rec/T-REC-X.680/en, X.680 - Abstract Syntax Notation One (ASN.1)),
8     the abstract definition for an $(MONO EXTERNAL), after removing the comments in the
9     specification, is as follows:
10 
11     $(PRE
12         EXTERNAL ::= [UNIVERSAL 8] SEQUENCE {
13             identification CHOICE {
14                 syntaxes SEQUENCE {
15                     abstract OBJECT IDENTIFIER,
16                     transfer OBJECT IDENTIFIER },
17                 syntax OBJECT IDENTIFIER,
18                 presentation-context-id INTEGER,
19                 context-negotiation SEQUENCE {
20                     presentation-context-id INTEGER,
21                     transfer-syntax OBJECT IDENTIFIER },
22                 transfer-syntax OBJECT IDENTIFIER,
23                 fixed NULL },
24             data-value-descriptor ObjectDescriptor OPTIONAL,
25             data-value OCTET STRING }
26                 ( WITH COMPONENTS {
27                     ... ,
28                     identification ( WITH COMPONENTS {
29                         ... ,
30                         syntaxes ABSENT,
31                         transfer-syntax ABSENT,
32                         fixed ABSENT } ) } )
33     )
34 
35     Note that the abstract syntax resembles that of $(MONO EmbeddedPDV) and
36     $(MONO CharacterString), except with a $(MONO WITH COMPONENTS) constraint that removes some
37     of our choices of $(MONO identification).
38     As can be seen on page 303 of Olivier Dubuisson's
39     $(I $(LINK http://www.oss.com/asn1/resources/books-whitepapers-pubs/dubuisson-asn1-book.PDF,
40         ASN.1: Communication Between Heterogeneous Systems)),
41     after applying the $(MONO WITH COMPONENTS) constraint, our reduced syntax becomes:
42 
43     $(PRE
44         EXTERNAL ::= [UNIVERSAL 8] IMPLICIT SEQUENCE {
45             identification CHOICE {
46                 syntax OBJECT IDENTIFIER,
47                 presentation-context-id INTEGER,
48                 context-negotiation SEQUENCE {
49                     presentation-context-id INTEGER,
50                     transfer-syntax OBJECT IDENTIFIER } },
51             data-value-descriptor ObjectDescriptor OPTIONAL,
52             data-value OCTET STRING }
53     )
54 
55     But, according to the
56     $(LINK https://www.itu.int/en/pages/default.aspx, International Telecommunications Union)'s
57     $(LINK http://www.itu.int/rec/T-REC-X.690/en, X.690 - ASN.1 encoding rules),
58     section 8.18, when encoded using Basic Encoding Rules (BER), is encoded as
59     follows, for compatibility reasons:
60 
61     $(PRE
62         EXTERNAL ::= [UNIVERSAL 8] IMPLICIT SEQUENCE {
63             direct-reference  OBJECT IDENTIFIER OPTIONAL,
64             indirect-reference  INTEGER OPTIONAL,
65             data-value-descriptor  ObjectDescriptor  OPTIONAL,
66             encoding  CHOICE {
67                 single-ASN1-type  [0] ANY,
68                 octet-aligned     [1] IMPLICIT OCTET STRING,
69                 arbitrary         [2] IMPLICIT BIT STRING } }
70     )
71 
72     The definition above is the pre-1994 definition of $(MONO EXTERNAL). The $(MONO syntax)
73     field of the post-1994 definition maps to the $(MONO direct-reference) field of
74     the pre-1994 definition. The $(MONO presentation-context-id) field of the post-1994
75     definition maps to the $(MONO indirect-reference) field of the pre-1994 definition.
76     If $(MONO context-negotiation) is used, per the abstract syntax, then the
77     $(MONO presentation-context-id) field of the $(MONO context-negotiation) $(MONO SEQUENCE) in the
78     post-1994 definition maps to the $(MONO indirect-reference) field of the pre-1994
79     definition, and the $(MONO transfer-syntax) field of the $(MONO context-negotiation)
80     $(MONO SEQUENCE) maps to the $(MONO direct-reference) field of the pre-1994 definition.
81 
82     The following additional constraints are applied to the abstract syntax
83     when using Canonical Encoding Rules or Distinguished Encoding Rules,
84     which are also defined in the
85     $(LINK https://www.itu.int/en/pages/default.aspx,
86     International Telecommunications Union)'s
87     $(LINK http://www.itu.int/rec/T-REC-X.690/en, X.690 - ASN.1 encoding rules):
88 
89     $(PRE
90         EXTERNAL ( WITH COMPONENTS {
91             ... ,
92             identification ( WITH COMPONENTS {
93                 ... ,
94                 presentation-context-id ABSENT,
95                 context-negotiation ABSENT } ) } )
96     )
97 
98     The stated purpose of the constraints shown above is to restrict the use of
99     the $(MONO presentation-context-id), either by itself or within the
100     $(MONO context-negotiation), which makes the following the effective abstract
101     syntax of $(MONO EXTERNAL) when using Canonical Encoding Rules or
102     Distinguished Encoding Rules:
103 
104     $(PRE
105         EXTERNAL ::= [UNIVERSAL 8] SEQUENCE {
106             identification CHOICE {
107                 syntaxes SEQUENCE {
108                     abstract OBJECT IDENTIFIER,
109                     transfer OBJECT IDENTIFIER },
110                 syntax OBJECT IDENTIFIER,
111                 presentation-context-id INTEGER,
112                 context-negotiation SEQUENCE {
113                     presentation-context-id INTEGER,
114                     transfer-syntax OBJECT IDENTIFIER },
115                 transfer-syntax OBJECT IDENTIFIER,
116                 fixed NULL },
117             data-value-descriptor ObjectDescriptor OPTIONAL,
118             data-value OCTET STRING }
119                 ( WITH COMPONENTS {
120                     ... ,
121                     identification ( WITH COMPONENTS {
122                         ... ,
123                         syntaxes ABSENT,
124                         presentation-context-id ABSENT,
125                         context-negotiation ABSENT,
126                         transfer-syntax ABSENT,
127                         fixed ABSENT } ) } )
128     )
129 
130     With the constraints applied, the abstract syntax for $(MONO EXTERNAL)s encoded
131     using Canonical Encoding Rules or Distinguished Encoding Rules becomes:
132 
133     $(PRE
134         EXTERNAL ::= [UNIVERSAL 8] SEQUENCE {
135             identification CHOICE {
136                 syntax OBJECT IDENTIFIER },
137             data-value-descriptor ObjectDescriptor OPTIONAL,
138             data-value OCTET STRING }
139     )
140 
141     Upon removing the $(MONO CHOICE) tag (since you have no choice but to use syntax
142     at this point), the encoding definition when using
143     Canonical Encoding Rules or Distinguished Encoding Rules:
144 
145     $(PRE
146         EXTERNAL ::= [UNIVERSAL 8] SEQUENCE {
147             syntax OBJECT IDENTIFIER,
148             data-value-descriptor ObjectDescriptor OPTIONAL,
149             data-value OCTET STRING }
150     )
151 */
152 public
153 struct External
154 {
155     /**
156         A field indicating the the transfer syntax used to indicate the means
157         by which the data-value field is encoded. Can also be used to specify
158         the abstract syntax of what is encoded.
159     */
160     public ASN1ContextSwitchingTypeID identification;
161     /// An optional field used to describe the encoded data.
162     public string dataValueDescriptor; // Made public because validation is done at encoding.
163     /// The encoded data
164     public ubyte[] dataValue;
165     /**
166         A field that exists only to determine the developer's choice of
167         encoding used, per the pre-1994 definition of EXTERNAL.
168 
169         octet-aligned is a sensible default, since it is the most lax of the
170         three choices.
171     */
172     ASN1ExternalEncodingChoice encoding = ASN1ExternalEncodingChoice.octetAligned;
173 }
174 
175 ///
176 public alias ASN1ExternalEncodingChoice = AbstractSyntaxNotation1ExternalEncodingChoice;
177 /**
178     The CHOICE of encoding used for the encoding of a pre-1994 EXTERNAL,
179     as used by the Basic Encoding Rules, Canonical Encoding Rules, or
180     Distinguished Encoding Rules.
181 */
182 public
183 enum AbstractSyntaxNotation1ExternalEncodingChoice : ubyte
184 {
185     /// single-ASN1-type [0] ABSTRACT-SYNTAX.&Type
186     singleASN1Type = singleAbstractSyntaxNotation1Type,
187     /// single-ASN1-type [0] ABSTRACT-SYNTAX.&Type
188     singleAbstractSyntaxNotation1Type = 0x00u,
189     /// octet-aligned [1] IMPLICIT OCTET STRING
190     octetAligned = 0x01u,
191     /// arbitrary [2] IMPLICIT BIT STRING
192     arbitrary = 0x02u
193 }