| OLD | NEW |
|---|
| (Empty) |
| 1 <html> | |
| 2 <title> | |
| 3 PyASN1 programmer's manual | |
| 4 </title> | |
| 5 <head> | |
| 6 </head> | |
| 7 <body> | |
| 8 <center> | |
| 9 <table width=60%> | |
| 10 <tr> | |
| 11 <td> | |
| 12 | |
| 13 <h3> | |
| 14 PyASN1 programmer's manual | |
| 15 </h3> | |
| 16 | |
| 17 <p align=right> | |
| 18 <i>written by <a href=mailto:ilya@glas.net>Ilya Etingof</a>, 2011-2012</i> | |
| 19 </p> | |
| 20 | |
| 21 <p> | |
| 22 Free and open-source pyasn1 library makes it easier for programmers and | |
| 23 network engineers to develop, debug and experiment with ASN.1-based protocols | |
| 24 using Python programming language as a tool. | |
| 25 </p> | |
| 26 | |
| 27 <p> | |
| 28 Abstract Syntax Notation One | |
| 29 (<a href=http://en.wikipedia.org/wiki/Abstract_Syntax_Notation_1x>ASN.1</a>) | |
| 30 is a set of | |
| 31 <a href=http://www.itu.int/ITU-T/studygroups/com17/languages/X.680-X.693-0207w.z
ip> | |
| 32 ITU standards</a> concered with provisioning instrumentation for developing | |
| 33 data exchange protocols in a robust, clear and interoperabable way for | |
| 34 various IT systems and applications. Most of the efforts are targeting the | |
| 35 following areas: | |
| 36 <ul> | |
| 37 <li>Data structures: the standard introduces a collection of basic data types | |
| 38 (similar to integers, bits, strings, arrays and records in a programming | |
| 39 language) that can be used for defining complex, possibly nested data | |
| 40 structures representing domain-specific data units. | |
| 41 <li>Serialization protocols: domain-specific data units expressed in ASN.1 | |
| 42 types could be converted into a series of octets for storage or transmission | |
| 43 over the wire and then recovered back into their structured form on the | |
| 44 receiving end. This process is immune to various hardware and software | |
| 45 related dependencies. | |
| 46 <li>Data description language: could be used to describe particular set of | |
| 47 domain-specific data structures and their relationships. Such a description | |
| 48 could be passed to an ASN.1 compiler for automated generation of program | |
| 49 code that represents ASN.1 data structures in language-native environment | |
| 50 and handles data serialization issues. | |
| 51 </ul> | |
| 52 </p> | |
| 53 | |
| 54 <p> | |
| 55 This tutorial and algorithms, implemented by pyasn1 library, are | |
| 56 largely based on the information read in the book | |
| 57 <a href="http://www.oss.com/asn1/dubuisson.html"> | |
| 58 ASN.1 - Communication between heterogeneous systems</a> | |
| 59 by Olivier Dubuisson. Another relevant resource is | |
| 60 <a href=ftp://ftp.rsasecurity.com/pub/pkcs/ascii/layman.asc> | |
| 61 A Layman's Guide to a Subset of ASN.1, BER, and DER</a> by Burton S. Kaliski. | |
| 62 It's advised to refer to these books for more in-depth knowledge on the | |
| 63 subject of ASN.1. | |
| 64 </p> | |
| 65 | |
| 66 <p> | |
| 67 As of this writing, pyasn1 library implements most of standard ASN.1 data | |
| 68 structures in a rather detailed and feature-rich manner. Another highly | |
| 69 important capability of the library is its data serialization facilities. | |
| 70 The last component of the standard - ASN.1 compiler is planned for | |
| 71 implementation in the future. | |
| 72 </p> | |
| 73 | |
| 74 </p> | |
| 75 The pyasn1 library was designed to follow the pre-1995 ASN.1 specification | |
| 76 (also known as X.208). Later, post 1995, revision (X.680) introduced | |
| 77 significant changes most of which have not yet been supported by pyasn1. | |
| 78 </p> | |
| 79 | |
| 80 <h3> | |
| 81 Table of contents | |
| 82 </h3> | |
| 83 | |
| 84 <p> | |
| 85 <ul> | |
| 86 <li><a href="#1">1. Data model for ASN.1 types</a> | |
| 87 <li><a href="#1.1">1.1 Scalar types</a> | |
| 88 <li><a href="#1.1.1">1.1.1 Boolean type</a> | |
| 89 <li><a href="#1.1.2">1.1.2 Null type</a> | |
| 90 <li><a href="#1.1.3">1.1.3 Integer type</a> | |
| 91 <li><a href="#1.1.4">1.1.4 Enumerated type</a> | |
| 92 <li><a href="#1.1.5">1.1.5 Real type</a> | |
| 93 <li><a href="#1.1.6">1.1.6 Bit string type</a> | |
| 94 <li><a href="#1.1.7">1.1.7 OctetString type</a> | |
| 95 <li><a href="#1.1.8">1.1.8 ObjectIdentifier type</a> | |
| 96 <li><a href="#1.1.9">1.1.9 Character string types</a> | |
| 97 <li><a href="#1.1.10">1.1.10 Useful types</a> | |
| 98 <li><a href="#1.2">1.2 Tagging</a> | |
| 99 <li><a href="#1.3">1.3 Constructed types</a> | |
| 100 <li><a href="#1.3.1">1.3.1 Sequence and Set types</a> | |
| 101 <li><a href="#1.3.2">1.3.2 SequenceOf and SetOf types</a> | |
| 102 <li><a href="#1.3.3">1.3.3 Choice type</a> | |
| 103 <li><a href="#1.3.4">1.3.4 Any type</a> | |
| 104 <li><a href="#1.4">1.4 Subtype constraints</a> | |
| 105 <li><a href="#1.4.1">1.4.1 Single value constraint</a> | |
| 106 <li><a href="#1.4.2">1.4.2 Value range constraint</a> | |
| 107 <li><a href="#1.4.3">1.4.3 Size constraint</a> | |
| 108 <li><a href="#1.4.4">1.4.4 Alphabet constraint</a> | |
| 109 <li><a href="#1.4.5">1.4.5 Constraint combinations</a> | |
| 110 <li><a href="#1.5">1.5 Types relationships</a> | |
| 111 <li><a href="#2">2. Codecs</a> | |
| 112 <li><a href="#2.1">2.1 Encoders</a> | |
| 113 <li><a href="#2.2">2.2 Decoders</a> | |
| 114 <li><a href="#2.2.1">2.2.1 Decoding untagged types</a> | |
| 115 <li><a href="#2.2.2">2.2.2 Ignoring unknown types</a> | |
| 116 <li><a href="#3">3. Feedback and getting help</a> | |
| 117 </ul> | |
| 118 | |
| 119 | |
| 120 <a name="1"></a> | |
| 121 <h3> | |
| 122 1. Data model for ASN.1 types | |
| 123 </h3> | |
| 124 | |
| 125 <p> | |
| 126 All ASN.1 types could be categorized into two groups: scalar (also called | |
| 127 simple or primitive) and constructed. The first group is populated by | |
| 128 well-known types like Integer or String. Members of constructed group | |
| 129 hold other types (simple or constructed) as their inner components, thus | |
| 130 they are semantically close to a programming language records or lists. | |
| 131 </p> | |
| 132 | |
| 133 <p> | |
| 134 In pyasn1, all ASN.1 types and values are implemented as Python objects. | |
| 135 The same pyasn1 object can represent either ASN.1 type and/or value | |
| 136 depending of the presense of value initializer on object instantiation. | |
| 137 We will further refer to these as <i>pyasn1 type object</i> versus <i>pyasn1 | |
| 138 value object</i>. | |
| 139 </p> | |
| 140 | |
| 141 <p> | |
| 142 Primitive ASN.1 types are implemented as immutable scalar objects. There values | |
| 143 could be used just like corresponding native Python values (integers, | |
| 144 strings/bytes etc) and freely mixed with them in expressions. | |
| 145 </p> | |
| 146 | |
| 147 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 148 <pre> | |
| 149 >>> from pyasn1.type import univ | |
| 150 >>> asn1IntegerValue = univ.Integer(12) | |
| 151 >>> asn1IntegerValue - 2 | |
| 152 10 | |
| 153 >>> univ.OctetString('abc') == 'abc' | |
| 154 True # Python 2 | |
| 155 >>> univ.OctetString(b'abc') == b'abc' | |
| 156 True # Python 3 | |
| 157 </pre> | |
| 158 </td></tr></table> | |
| 159 | |
| 160 <p> | |
| 161 It would be an error to perform an operation on a pyasn1 type object | |
| 162 as it holds no value to deal with: | |
| 163 </p> | |
| 164 | |
| 165 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 166 <pre> | |
| 167 >>> from pyasn1.type import univ | |
| 168 >>> asn1IntegerType = univ.Integer() | |
| 169 >>> asn1IntegerType - 2 | |
| 170 ... | |
| 171 pyasn1.error.PyAsn1Error: No value for __coerce__() | |
| 172 </pre> | |
| 173 </td></tr></table> | |
| 174 | |
| 175 <a name="1.1"></a> | |
| 176 <h4> | |
| 177 1.1 Scalar types | |
| 178 </h4> | |
| 179 | |
| 180 <p> | |
| 181 In the sub-sections that follow we will explain pyasn1 mapping to those | |
| 182 primitive ASN.1 types. Both, ASN.1 notation and corresponding pyasn1 | |
| 183 syntax will be given in each case. | |
| 184 </p> | |
| 185 | |
| 186 <a name="1.1.1"></a> | |
| 187 <h4> | |
| 188 1.1.1 Boolean type | |
| 189 </h4> | |
| 190 | |
| 191 <p> | |
| 192 This is the simplest type those values could be either True or False. | |
| 193 </p> | |
| 194 | |
| 195 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 196 <pre> | |
| 197 ;; type specification | |
| 198 FunFactorPresent ::= BOOLEAN | |
| 199 | |
| 200 ;; values declaration and assignment | |
| 201 pythonFunFactor FunFactorPresent ::= TRUE | |
| 202 cobolFunFactor FunFactorPresent :: FALSE | |
| 203 </pre> | |
| 204 </td></tr></table> | |
| 205 | |
| 206 <p> | |
| 207 And here's pyasn1 version of it: | |
| 208 </p> | |
| 209 | |
| 210 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 211 <pre> | |
| 212 >>> from pyasn1.type import univ | |
| 213 >>> class FunFactorPresent(univ.Boolean): pass | |
| 214 ... | |
| 215 >>> pythonFunFactor = FunFactorPresent(True) | |
| 216 >>> cobolFunFactor = FunFactorPresent(False) | |
| 217 >>> pythonFunFactor | |
| 218 FunFactorPresent('True(1)') | |
| 219 >>> cobolFunFactor | |
| 220 FunFactorPresent('False(0)') | |
| 221 >>> pythonFunFactor == cobolFunFactor | |
| 222 False | |
| 223 >>> | |
| 224 </pre> | |
| 225 </td></tr></table> | |
| 226 | |
| 227 <a name="1.1.2"></a> | |
| 228 <h4> | |
| 229 1.1.2 Null type | |
| 230 </h4> | |
| 231 | |
| 232 <p> | |
| 233 The NULL type is sometimes used to express the absense of any information. | |
| 234 </p> | |
| 235 | |
| 236 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 237 <pre> | |
| 238 ;; type specification | |
| 239 Vote ::= CHOICE { | |
| 240 agreed BOOLEAN, | |
| 241 skip NULL | |
| 242 } | |
| 243 </td></tr></table> | |
| 244 | |
| 245 ;; value declaration and assignment | |
| 246 myVote Vote ::= skip:NULL | |
| 247 </pre> | |
| 248 | |
| 249 <p> | |
| 250 We will explain the CHOICE type later in this paper, meanwhile the NULL | |
| 251 type: | |
| 252 </p> | |
| 253 | |
| 254 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 255 <pre> | |
| 256 >>> from pyasn1.type import univ | |
| 257 >>> skip = univ.Null() | |
| 258 >>> skip | |
| 259 Null('') | |
| 260 >>> | |
| 261 </pre> | |
| 262 </td></tr></table> | |
| 263 | |
| 264 <a name="1.1.3"></a> | |
| 265 <h4> | |
| 266 1.1.3 Integer type | |
| 267 </h4> | |
| 268 | |
| 269 <p> | |
| 270 ASN.1 defines the values of Integer type as negative or positive of whatever | |
| 271 length. This definition plays nicely with Python as the latter places no | |
| 272 limit on Integers. However, some ASN.1 implementations may impose certain | |
| 273 limits of integer value ranges. Keep that in mind when designing new | |
| 274 data structures. | |
| 275 </p> | |
| 276 | |
| 277 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 278 <pre> | |
| 279 ;; values specification | |
| 280 age-of-universe INTEGER ::= 13750000000 | |
| 281 mean-martian-surface-temperature INTEGER ::= -63 | |
| 282 </pre> | |
| 283 </td></tr></table> | |
| 284 | |
| 285 <p> | |
| 286 A rather strigntforward mapping into pyasn1: | |
| 287 </p> | |
| 288 | |
| 289 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 290 <pre> | |
| 291 >>> from pyasn1.type import univ | |
| 292 >>> ageOfUniverse = univ.Integer(13750000000) | |
| 293 >>> ageOfUniverse | |
| 294 Integer(13750000000) | |
| 295 >>> | |
| 296 >>> meanMartianSurfaceTemperature = univ.Integer(-63) | |
| 297 >>> meanMartianSurfaceTemperature | |
| 298 Integer(-63) | |
| 299 >>> | |
| 300 </pre> | |
| 301 </td></tr></table> | |
| 302 | |
| 303 <p> | |
| 304 ASN.1 allows to assign human-friendly names to particular values of | |
| 305 an INTEGER type. | |
| 306 </p> | |
| 307 | |
| 308 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 309 <pre> | |
| 310 Temperature ::= INTEGER { | |
| 311 freezing(0), | |
| 312 boiling(100) | |
| 313 } | |
| 314 </pre> | |
| 315 </td></tr></table> | |
| 316 | |
| 317 <p> | |
| 318 The Temperature type expressed in pyasn1: | |
| 319 </p> | |
| 320 | |
| 321 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 322 <pre> | |
| 323 >>> from pyasn1.type import univ, namedval | |
| 324 >>> class Temperature(univ.Integer): | |
| 325 ... namedValues = namedval.NamedValues(('freezing', 0), ('boiling', 100)) | |
| 326 ... | |
| 327 >>> t = Temperature(0) | |
| 328 >>> t | |
| 329 Temperature('freezing(0)') | |
| 330 >>> t + 1 | |
| 331 Temperature(1) | |
| 332 >>> t + 100 | |
| 333 Temperature('boiling(100)') | |
| 334 >>> t = Temperature('boiling') | |
| 335 >>> t | |
| 336 Temperature('boiling(100)') | |
| 337 >>> Temperature('boiling') / 2 | |
| 338 Temperature(50) | |
| 339 >>> -1 < Temperature('freezing') | |
| 340 True | |
| 341 >>> 47 > Temperature('boiling') | |
| 342 False | |
| 343 >>> | |
| 344 </pre> | |
| 345 </td></tr></table> | |
| 346 | |
| 347 <p> | |
| 348 These values labels have no effect on Integer type operations, any value | |
| 349 still could be assigned to a type (information on value constraints will | |
| 350 follow further in this paper). | |
| 351 </p> | |
| 352 | |
| 353 <a name="1.1.4"></a> | |
| 354 <h4> | |
| 355 1.1.4 Enumerated type | |
| 356 </h4> | |
| 357 | |
| 358 <p> | |
| 359 ASN.1 Enumerated type differs from an Integer type in a number of ways. | |
| 360 Most important is that its instance can only hold a value that belongs | |
| 361 to a set of values specified on type declaration. | |
| 362 </p> | |
| 363 | |
| 364 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 365 <pre> | |
| 366 error-status ::= ENUMERATED { | |
| 367 no-error(0), | |
| 368 authentication-error(10), | |
| 369 authorization-error(20), | |
| 370 general-failure(51) | |
| 371 } | |
| 372 </pre> | |
| 373 </td></tr></table> | |
| 374 | |
| 375 <p> | |
| 376 When constructing Enumerated type we will use two pyasn1 features: values | |
| 377 labels (as mentioned above) and value constraint (will be described in | |
| 378 more details later on). | |
| 379 </p> | |
| 380 | |
| 381 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 382 <pre> | |
| 383 >>> from pyasn1.type import univ, namedval, constraint | |
| 384 >>> class ErrorStatus(univ.Enumerated): | |
| 385 ... namedValues = namedval.NamedValues( | |
| 386 ... ('no-error', 0), | |
| 387 ... ('authentication-error', 10), | |
| 388 ... ('authorization-error', 20), | |
| 389 ... ('general-failure', 51) | |
| 390 ... ) | |
| 391 ... subtypeSpec = univ.Enumerated.subtypeSpec + \ | |
| 392 ... constraint.SingleValueConstraint(0, 10, 20, 51) | |
| 393 ... | |
| 394 >>> errorStatus = univ.ErrorStatus('no-error') | |
| 395 >>> errorStatus | |
| 396 ErrorStatus('no-error(0)') | |
| 397 >>> errorStatus == univ.ErrorStatus('general-failure') | |
| 398 False | |
| 399 >>> univ.ErrorStatus('non-existing-state') | |
| 400 Traceback (most recent call last): | |
| 401 ... | |
| 402 pyasn1.error.PyAsn1Error: Can't coerce non-existing-state into integer | |
| 403 >>> | |
| 404 </pre> | |
| 405 </td></tr></table> | |
| 406 | |
| 407 <p> | |
| 408 Particular integer values associated with Enumerated value states | |
| 409 have no meaning. They should not be used as such or in any kind of | |
| 410 math operation. Those integer values are only used by codecs to | |
| 411 transfer state from one entity to another. | |
| 412 </p> | |
| 413 | |
| 414 <a name="1.1.5"></a> | |
| 415 <h4> | |
| 416 1.1.5 Real type | |
| 417 </h4> | |
| 418 | |
| 419 <p> | |
| 420 Values of the Real type are a three-component tuple of mantissa, base and | |
| 421 exponent. All three are integers. | |
| 422 </p> | |
| 423 | |
| 424 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 425 <pre> | |
| 426 pi ::= REAL { mantissa 314159, base 10, exponent -5 } | |
| 427 </pre> | |
| 428 </td></tr></table> | |
| 429 | |
| 430 <p> | |
| 431 Corresponding pyasn1 objects can be initialized with either a three-component | |
| 432 tuple or a Python float. Infinite values could be expressed in a way, | |
| 433 compatible with Python float type. | |
| 434 | |
| 435 </p> | |
| 436 | |
| 437 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 438 <pre> | |
| 439 >>> from pyasn1.type import univ | |
| 440 >>> pi = univ.Real((314159, 10, -5)) | |
| 441 >>> pi | |
| 442 Real((314159, 10,-5)) | |
| 443 >>> float(pi) | |
| 444 3.14159 | |
| 445 >>> pi == univ.Real(3.14159) | |
| 446 True | |
| 447 >>> univ.Real('inf') | |
| 448 Real('inf') | |
| 449 >>> univ.Real('-inf') == float('-inf') | |
| 450 True | |
| 451 >>> | |
| 452 </pre> | |
| 453 </td></tr></table> | |
| 454 | |
| 455 <p> | |
| 456 If a Real object is initialized from a Python float or yielded by a math | |
| 457 operation, the base is set to decimal 10 (what affects encoding). | |
| 458 </p> | |
| 459 | |
| 460 <a name="1.1.6"></a> | |
| 461 <h4> | |
| 462 1.1.6 Bit string type | |
| 463 </h4> | |
| 464 | |
| 465 <p> | |
| 466 ASN.1 BIT STRING type holds opaque binary data of an arbitrarily length. | |
| 467 A BIT STRING value could be initialized by either a binary (base 2) or | |
| 468 hex (base 16) value. | |
| 469 </p> | |
| 470 | |
| 471 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 472 <pre> | |
| 473 public-key BIT STRING ::= '1010111011110001010110101101101 | |
| 474 1011000101010000010110101100010 | |
| 475 0110101010000111101010111111110'B | |
| 476 | |
| 477 signature BIT STRING ::= 'AF01330CD932093392100B39FF00DE0'H | |
| 478 </pre> | |
| 479 </td></tr></table> | |
| 480 | |
| 481 <p> | |
| 482 The pyasn1 BitString objects can initialize from native ASN.1 notation | |
| 483 (base 2 or base 16 strings) or from a Python tuple of binary components. | |
| 484 </p> | |
| 485 | |
| 486 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 487 <pre> | |
| 488 >>> from pyasn1.type import univ | |
| 489 >>> publicKey = univ.BitString( | |
| 490 ... "'1010111011110001010110101101101" | |
| 491 ... "1011000101010000010110101100010" | |
| 492 ... "0110101010000111101010111111110'B" | |
| 493 ) | |
| 494 >>> publicKey | |
| 495 BitString("'10101110111100010101101011011011011000101010000010110101100010\ | |
| 496 0110101010000111101010111111110'B") | |
| 497 >>> signature = univ.BitString( | |
| 498 ... "'AF01330CD932093392100B39FF00DE0'H" | |
| 499 ... ) | |
| 500 >>> signature | |
| 501 BitString("'101011110000000100110011000011001101100100110010000010010011001\ | |
| 502 1100100100001000000001011001110011111111100000000110111100000'B") | |
| 503 >>> fingerprint = univ.BitString( | |
| 504 ... (1, 0, 1, 1 ,0, 1, 1, 1, 0, 1, 0, 1) | |
| 505 ... ) | |
| 506 >>> fingerprint | |
| 507 BitString("'101101110101'B") | |
| 508 >>> | |
| 509 </pre> | |
| 510 </td></tr></table> | |
| 511 | |
| 512 <p> | |
| 513 Another BIT STRING initialization method supported by ASN.1 notation | |
| 514 is to specify only 1-th bits along with their human-friendly label | |
| 515 and bit offset relative to the beginning of the bit string. With this | |
| 516 method, all not explicitly mentioned bits are doomed to be zeros. | |
| 517 </p> | |
| 518 | |
| 519 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 520 <pre> | |
| 521 bit-mask BIT STRING ::= { | |
| 522 read-flag(0), | |
| 523 write-flag(2), | |
| 524 run-flag(4) | |
| 525 } | |
| 526 </pre> | |
| 527 </td></tr></table> | |
| 528 | |
| 529 <p> | |
| 530 To express this in pyasn1, we will employ the named values feature (as with | |
| 531 Enumeration type). | |
| 532 </p> | |
| 533 | |
| 534 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 535 <pre> | |
| 536 >>> from pyasn1.type import univ, namedval | |
| 537 >>> class BitMask(univ.BitString): | |
| 538 ... namedValues = namedval.NamedValues( | |
| 539 ... ('read-flag', 0), | |
| 540 ... ('write-flag', 2), | |
| 541 ... ('run-flag', 4) | |
| 542 ... ) | |
| 543 >>> bitMask = BitMask('read-flag,run-flag') | |
| 544 >>> bitMask | |
| 545 BitMask("'10001'B") | |
| 546 >>> tuple(bitMask) | |
| 547 (1, 0, 0, 0, 1) | |
| 548 >>> bitMask[4] | |
| 549 1 | |
| 550 >>> | |
| 551 </pre> | |
| 552 </td></tr></table> | |
| 553 | |
| 554 <p> | |
| 555 The BitString objects mimic the properties of Python tuple type in part | |
| 556 of immutable sequence object protocol support. | |
| 557 </p> | |
| 558 | |
| 559 <a name="1.1.7"></a> | |
| 560 <h4> | |
| 561 1.1.7 OctetString type | |
| 562 </h4> | |
| 563 | |
| 564 <p> | |
| 565 The OCTET STRING type is a confusing subject. According to ASN.1 | |
| 566 specification, this type is similar to BIT STRING, the major difference | |
| 567 is that the former operates in 8-bit chunks of data. What is important | |
| 568 to note, is that OCTET STRING was NOT designed to handle text strings - the | |
| 569 standard provides many other types specialized for text content. For that | |
| 570 reason, ASN.1 forbids to initialize OCTET STRING values with "quoted text | |
| 571 strings", only binary or hex initializers, similar to BIT STRING ones, | |
| 572 are allowed. | |
| 573 </p> | |
| 574 | |
| 575 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 576 <pre> | |
| 577 thumbnail OCTET STRING ::= '1000010111101110101111000000111011'B | |
| 578 thumbnail OCTET STRING ::= 'FA9823C43E43510DE3422'H | |
| 579 </pre> | |
| 580 </td></tr></table> | |
| 581 | |
| 582 <p> | |
| 583 However, ASN.1 users (e.g. protocols designers) seem to ignore the original | |
| 584 purpose of the OCTET STRING type - they used it for handling all kinds of | |
| 585 data, including text strings. | |
| 586 </p> | |
| 587 | |
| 588 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 589 <pre> | |
| 590 welcome-message OCTET STRING ::= "Welcome to ASN.1 wilderness!" | |
| 591 </pre> | |
| 592 </td></tr></table> | |
| 593 | |
| 594 <p> | |
| 595 In pyasn1, we have taken a liberal approach and allowed both BIT STRING | |
| 596 style and quoted text initializers for the OctetString objects. To avoid | |
| 597 possible collisions, quoted text is the default initialization syntax. | |
| 598 </p> | |
| 599 | |
| 600 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 601 <pre> | |
| 602 >>> from pyasn1.type import univ | |
| 603 >>> thumbnail = univ.OctetString( | |
| 604 ... binValue='1000010111101110101111000000111011' | |
| 605 ... ) | |
| 606 >>> thumbnail | |
| 607 OctetString(hexValue='85eebcec0') | |
| 608 >>> thumbnail = univ.OctetString( | |
| 609 ... hexValue='FA9823C43E43510DE3422' | |
| 610 ... ) | |
| 611 >>> thumbnail | |
| 612 OctetString(hexValue='fa9823c43e4351de34220') | |
| 613 >>> | |
| 614 </pre> | |
| 615 </td></tr></table> | |
| 616 | |
| 617 <p> | |
| 618 Most frequent usage of the OctetString class is to instantiate it with | |
| 619 a text string. | |
| 620 </p> | |
| 621 | |
| 622 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 623 <pre> | |
| 624 >>> from pyasn1.type import univ | |
| 625 >>> welcomeMessage = univ.OctetString('Welcome to ASN.1 wilderness!') | |
| 626 >>> welcomeMessage | |
| 627 OctetString(b'Welcome to ASN.1 wilderness!') | |
| 628 >>> print('%s' % welcomeMessage) | |
| 629 Welcome to ASN.1 wilderness! | |
| 630 >>> welcomeMessage[11:16] | |
| 631 OctetString(b'ASN.1') | |
| 632 >>> | |
| 633 </pre> | |
| 634 </td></tr></table> | |
| 635 | |
| 636 <p> | |
| 637 OctetString objects support the immutable sequence object protocol. | |
| 638 In other words, they behave like Python 3 bytes (or Python 2 strings). | |
| 639 </p> | |
| 640 | |
| 641 <p> | |
| 642 When running pyasn1 on Python 3, it's better to use the bytes objects for | |
| 643 OctetString instantiation, as it's more reliable and efficient. | |
| 644 </p> | |
| 645 | |
| 646 <p> | |
| 647 Additionally, OctetString's can also be instantiated with a sequence of | |
| 648 8-bit integers (ASCII codes). | |
| 649 </p> | |
| 650 | |
| 651 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 652 <pre> | |
| 653 >>> univ.OctetString((77, 101, 101, 103, 111)) | |
| 654 OctetString(b'Meego') | |
| 655 </pre> | |
| 656 </td></tr></table> | |
| 657 | |
| 658 <p> | |
| 659 It is sometimes convenient to express OctetString instances as 8-bit | |
| 660 characters (Python 3 bytes or Python 2 strings) or 8-bit integers. | |
| 661 </p> | |
| 662 | |
| 663 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 664 <pre> | |
| 665 >>> octetString = univ.OctetString('ABCDEF') | |
| 666 >>> octetString.asNumbers() | |
| 667 (65, 66, 67, 68, 69, 70) | |
| 668 >>> octetString.asOctets() | |
| 669 b'ABCDEF' | |
| 670 </pre> | |
| 671 </td></tr></table> | |
| 672 | |
| 673 <a name="1.1.8"></a> | |
| 674 <h4> | |
| 675 1.1.8 ObjectIdentifier type | |
| 676 </h4> | |
| 677 | |
| 678 <p> | |
| 679 Values of the OBJECT IDENTIFIER type are sequences of integers that could | |
| 680 be used to identify virtually anything in the world. Various ASN.1-based | |
| 681 protocols employ OBJECT IDENTIFIERs for their own identification needs. | |
| 682 </p> | |
| 683 | |
| 684 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 685 <pre> | |
| 686 internet-id OBJECT IDENTIFIER ::= { | |
| 687 iso(1) identified-organization(3) dod(6) internet(1) | |
| 688 } | |
| 689 </pre> | |
| 690 </td></tr></table> | |
| 691 | |
| 692 <p> | |
| 693 One of the natural ways to map OBJECT IDENTIFIER type into a Python | |
| 694 one is to use Python tuples of integers. So this approach is taken by | |
| 695 pyasn1. | |
| 696 </p> | |
| 697 | |
| 698 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 699 <pre> | |
| 700 >>> from pyasn1.type import univ | |
| 701 >>> internetId = univ.ObjectIdentifier((1, 3, 6, 1)) | |
| 702 >>> internetId | |
| 703 ObjectIdentifier('1.3.6.1') | |
| 704 >>> internetId[2] | |
| 705 6 | |
| 706 >>> internetId[1:3] | |
| 707 ObjectIdentifier('3.6') | |
| 708 </pre> | |
| 709 </td></tr></table> | |
| 710 | |
| 711 <p> | |
| 712 A more human-friendly "dotted" notation is also supported. | |
| 713 </p> | |
| 714 | |
| 715 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 716 <pre> | |
| 717 >>> from pyasn1.type import univ | |
| 718 >>> univ.ObjectIdentifier('1.3.6.1') | |
| 719 ObjectIdentifier('1.3.6.1') | |
| 720 </pre> | |
| 721 </td></tr></table> | |
| 722 | |
| 723 <p> | |
| 724 Symbolic names of the arcs of object identifier, sometimes present in | |
| 725 ASN.1 specifications, are not preserved and used in pyasn1 objects. | |
| 726 </p> | |
| 727 | |
| 728 <p> | |
| 729 The ObjectIdentifier objects mimic the properties of Python tuple type in | |
| 730 part of immutable sequence object protocol support. | |
| 731 </p> | |
| 732 | |
| 733 <a name="1.1.9"></a> | |
| 734 <h4> | |
| 735 1.1.9 Character string types | |
| 736 </h4> | |
| 737 | |
| 738 <p> | |
| 739 ASN.1 standard introduces a diverse set of text-specific types. All of them | |
| 740 were designed to handle various types of characters. Some of these types seem | |
| 741 be obsolete nowdays, as their target technologies are gone. Another issue | |
| 742 to be aware of is that raw OCTET STRING type is sometimes used in practice | |
| 743 by ASN.1 users instead of specialized character string types, despite | |
| 744 explicit prohibition imposed by ASN.1 specification. | |
| 745 </p> | |
| 746 | |
| 747 <p> | |
| 748 The two types are specific to ASN.1 are NumericString and PrintableString. | |
| 749 </p> | |
| 750 | |
| 751 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 752 <pre> | |
| 753 welcome-message ::= PrintableString { | |
| 754 "Welcome to ASN.1 text types" | |
| 755 } | |
| 756 | |
| 757 dial-pad-numbers ::= NumericString { | |
| 758 "0", "1", "2", "3", "4", "5", "6", "7", "8", "9" | |
| 759 } | |
| 760 </pre> | |
| 761 </td></tr></table> | |
| 762 | |
| 763 <p> | |
| 764 Their pyasn1 implementations are: | |
| 765 </p> | |
| 766 | |
| 767 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 768 <pre> | |
| 769 >>> from pyasn1.type import char | |
| 770 >>> '%s' % char.PrintableString("Welcome to ASN.1 text types") | |
| 771 'Welcome to ASN.1 text types' | |
| 772 >>> dialPadNumbers = char.NumericString( | |
| 773 "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" | |
| 774 ) | |
| 775 >>> dialPadNumbers | |
| 776 NumericString(b'0123456789') | |
| 777 >>> | |
| 778 </pre> | |
| 779 </td></tr></table> | |
| 780 | |
| 781 <p> | |
| 782 The following types came to ASN.1 from ISO standards on character sets. | |
| 783 </p> | |
| 784 | |
| 785 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 786 <pre> | |
| 787 >>> from pyasn1.type import char | |
| 788 >>> char.VisibleString("abc") | |
| 789 VisibleString(b'abc') | |
| 790 >>> char.IA5String('abc') | |
| 791 IA5String(b'abc') | |
| 792 >>> char.TeletexString('abc') | |
| 793 TeletexString(b'abc') | |
| 794 >>> char.VideotexString('abc') | |
| 795 VideotexString(b'abc') | |
| 796 >>> char.GraphicString('abc') | |
| 797 GraphicString(b'abc') | |
| 798 >>> char.GeneralString('abc') | |
| 799 GeneralString(b'abc') | |
| 800 >>> | |
| 801 </pre> | |
| 802 </td></tr></table> | |
| 803 | |
| 804 <p> | |
| 805 The last three types are relatively recent addition to the family of | |
| 806 character string types: UniversalString, BMPString, UTF8String. | |
| 807 </p> | |
| 808 | |
| 809 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 810 <pre> | |
| 811 >>> from pyasn1.type import char | |
| 812 >>> char.UniversalString("abc") | |
| 813 UniversalString(b'abc') | |
| 814 >>> char.BMPString('abc') | |
| 815 BMPString(b'abc') | |
| 816 >>> char.UTF8String('abc') | |
| 817 UTF8String(b'abc') | |
| 818 >>> utf8String = char.UTF8String('У попа была собака') | |
| 819 >>> utf8String | |
| 820 UTF8String(b'\xd0\xa3 \xd0\xbf\xd0\xbe\xd0\xbf\xd0\xb0 \xd0\xb1\xd1\x8b\xd0\xbb\
xd0\xb0 \ | |
| 821 \xd1\x81\xd0\xbe\xd0\xb1\xd0\xb0\xd0\xba\xd0\xb0') | |
| 822 >>> print(utf8String) | |
| 823 У попа была собака | |
| 824 >>> | |
| 825 </pre> | |
| 826 </td></tr></table> | |
| 827 | |
| 828 <p> | |
| 829 In pyasn1, all character type objects behave like Python strings. None of | |
| 830 them is currently constrained in terms of valid alphabet so it's up to | |
| 831 the data source to keep an eye on data validation for these types. | |
| 832 </p> | |
| 833 | |
| 834 <a name="1.1.10"></a> | |
| 835 <h4> | |
| 836 1.1.10 Useful types | |
| 837 </h4> | |
| 838 | |
| 839 <p> | |
| 840 There are three so-called useful types defined in the standard: | |
| 841 ObjectDescriptor, GeneralizedTime, UTCTime. They all are subtypes | |
| 842 of GraphicString or VisibleString types therefore useful types are | |
| 843 character string types. | |
| 844 </p> | |
| 845 | |
| 846 <p> | |
| 847 It's advised by the ASN.1 standard to have an instance of ObjectDescriptor | |
| 848 type holding a human-readable description of corresponding instance of | |
| 849 OBJECT IDENTIFIER type. There are no formal linkage between these instances | |
| 850 and provision for ObjectDescriptor uniqueness in the standard. | |
| 851 </p> | |
| 852 | |
| 853 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 854 <pre> | |
| 855 >>> from pyasn1.type import useful | |
| 856 >>> descrBER = useful.ObjectDescriptor( | |
| 857 "Basic encoding of a single ASN.1 type" | |
| 858 ) | |
| 859 >>> | |
| 860 </pre> | |
| 861 </td></tr></table> | |
| 862 | |
| 863 <p> | |
| 864 GeneralizedTime and UTCTime types are designed to hold a human-readable | |
| 865 timestamp in a universal and unambiguous form. The former provides | |
| 866 more flexibility in notation while the latter is more strict but has | |
| 867 Y2K issues. | |
| 868 </p> | |
| 869 | |
| 870 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 871 <pre> | |
| 872 ;; Mar 8 2010 12:00:00 MSK | |
| 873 moscow-time GeneralizedTime ::= "20110308120000.0" | |
| 874 ;; Mar 8 2010 12:00:00 UTC | |
| 875 utc-time GeneralizedTime ::= "201103081200Z" | |
| 876 ;; Mar 8 1999 12:00:00 UTC | |
| 877 utc-time UTCTime ::= "9803081200Z" | |
| 878 </pre> | |
| 879 </td></tr></table> | |
| 880 | |
| 881 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 882 <pre> | |
| 883 >>> from pyasn1.type import useful | |
| 884 >>> moscowTime = useful.GeneralizedTime("20110308120000.0") | |
| 885 >>> utcTime = useful.UTCTime("9803081200Z") | |
| 886 >>> | |
| 887 </pre> | |
| 888 </td></tr></table> | |
| 889 | |
| 890 <p> | |
| 891 Despite their intended use, these types possess no special, time-related, | |
| 892 handling in pyasn1. They are just printable strings. | |
| 893 </p> | |
| 894 | |
| 895 <a name="1.2"></a> | |
| 896 <h4> | |
| 897 1.2 Tagging | |
| 898 </h4> | |
| 899 | |
| 900 <p> | |
| 901 In order to continue with the Constructed ASN.1 types, we will first have | |
| 902 to introduce the concept of tagging (and its pyasn1 implementation), as | |
| 903 some of the Constructed types rely upon the tagging feature. | |
| 904 </p> | |
| 905 | |
| 906 <p> | |
| 907 When a value is coming into an ASN.1-based system (received from a network | |
| 908 or read from some storage), the receiving entity has to determine the | |
| 909 type of the value to interpret and verify it accordingly. | |
| 910 </p> | |
| 911 | |
| 912 <p> | |
| 913 Historically, the first data serialization protocol introduced in | |
| 914 ASN.1 was BER (Basic Encoding Rules). According to BER, any serialized | |
| 915 value is packed into a triplet of (Type, Length, Value) where Type is a | |
| 916 code that identifies the value (which is called <i>tag</i> in ASN.1), | |
| 917 length is the number of bytes occupied by the value in its serialized form | |
| 918 and value is ASN.1 value in a form suitable for serial transmission or storage. | |
| 919 </p> | |
| 920 | |
| 921 <p> | |
| 922 For that reason almost every ASN.1 type has a tag (which is actually a | |
| 923 BER type) associated with it by default. | |
| 924 </p> | |
| 925 | |
| 926 <p> | |
| 927 An ASN.1 tag could be viewed as a tuple of three numbers: | |
| 928 (Class, Format, Number). While Number identifies a tag, Class component | |
| 929 is used to create scopes for Numbers. Four scopes are currently defined: | |
| 930 UNIVERSAL, context-specific, APPLICATION and PRIVATE. The Format component | |
| 931 is actually a one-bit flag - zero for tags associated with scalar types, | |
| 932 and one for constructed types (will be discussed later on). | |
| 933 </p> | |
| 934 | |
| 935 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 936 <pre> | |
| 937 MyIntegerType ::= [12] INTEGER | |
| 938 MyOctetString ::= [APPLICATION 0] OCTET STRING | |
| 939 </pre> | |
| 940 </td></tr></table> | |
| 941 | |
| 942 <p> | |
| 943 In pyasn1, tags are implemented as immutable, tuple-like objects: | |
| 944 </p> | |
| 945 | |
| 946 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 947 <pre> | |
| 948 >>> from pyasn1.type import tag | |
| 949 >>> myTag = tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 10) | |
| 950 >>> myTag | |
| 951 Tag(tagClass=128, tagFormat=0, tagId=10) | |
| 952 >>> tuple(myTag) | |
| 953 (128, 0, 10) | |
| 954 >>> myTag[2] | |
| 955 10 | |
| 956 >>> myTag == tag.Tag(tag.tagClassApplication, tag.tagFormatSimple, 10) | |
| 957 False | |
| 958 >>> | |
| 959 </pre> | |
| 960 </td></tr></table> | |
| 961 | |
| 962 <p> | |
| 963 Default tag, associated with any ASN.1 type, could be extended or replaced | |
| 964 to make new type distinguishable from its ancestor. The standard provides | |
| 965 two modes of tag mangling - IMPLICIT and EXPLICIT. | |
| 966 </p> | |
| 967 | |
| 968 <p> | |
| 969 EXPLICIT mode works by appending new tag to the existing ones thus creating | |
| 970 an ordered set of tags. This set will be considered as a whole for type | |
| 971 identification and encoding purposes. Important property of EXPLICIT tagging | |
| 972 mode is that it preserves base type information in encoding what makes it | |
| 973 possible to completely recover type information from encoding. | |
| 974 </p> | |
| 975 | |
| 976 <p> | |
| 977 When tagging in IMPLICIT mode, the outermost existing tag is dropped and | |
| 978 replaced with a new one. | |
| 979 </p> | |
| 980 | |
| 981 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 982 <pre> | |
| 983 MyIntegerType ::= [12] IMPLICIT INTEGER | |
| 984 MyOctetString ::= [APPLICATION 0] EXPLICIT OCTET STRING | |
| 985 </pre> | |
| 986 </td></tr></table> | |
| 987 | |
| 988 <p> | |
| 989 To model both modes of tagging, a specialized container TagSet object (holding | |
| 990 zero, one or more Tag objects) is used in pyasn1. | |
| 991 </p> | |
| 992 | |
| 993 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 994 <pre> | |
| 995 >>> from pyasn1.type import tag | |
| 996 >>> tagSet = tag.TagSet( | |
| 997 ... tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 10), # base tag | |
| 998 ... tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 10) # effective tag | |
| 999 ... ) | |
| 1000 >>> tagSet | |
| 1001 TagSet(Tag(tagClass=128, tagFormat=0, tagId=10)) | |
| 1002 >>> tagSet.getBaseTag() | |
| 1003 Tag(tagClass=128, tagFormat=0, tagId=10) | |
| 1004 >>> tagSet = tagSet.tagExplicitly( | |
| 1005 ... tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 20) | |
| 1006 ... ) | |
| 1007 >>> tagSet | |
| 1008 TagSet(Tag(tagClass=128, tagFormat=0, tagId=10), | |
| 1009 Tag(tagClass=128, tagFormat=32, tagId=20)) | |
| 1010 >>> tagSet = tagSet.tagExplicitly( | |
| 1011 ... tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 30) | |
| 1012 ... ) | |
| 1013 >>> tagSet | |
| 1014 TagSet(Tag(tagClass=128, tagFormat=0, tagId=10), | |
| 1015 Tag(tagClass=128, tagFormat=32, tagId=20), | |
| 1016 Tag(tagClass=128, tagFormat=32, tagId=30)) | |
| 1017 >>> tagSet = tagSet.tagImplicitly( | |
| 1018 ... tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 40) | |
| 1019 ... ) | |
| 1020 >>> tagSet | |
| 1021 TagSet(Tag(tagClass=128, tagFormat=0, tagId=10), | |
| 1022 Tag(tagClass=128, tagFormat=32, tagId=20), | |
| 1023 Tag(tagClass=128, tagFormat=32, tagId=40)) | |
| 1024 >>> | |
| 1025 </pre> | |
| 1026 </td></tr></table> | |
| 1027 | |
| 1028 <p> | |
| 1029 As a side note: the "base tag" concept (accessible through the getBaseTag() | |
| 1030 method) is specific to pyasn1 -- the base tag is used to identify the original | |
| 1031 ASN.1 type of an object in question. Base tag is never occurs in encoding | |
| 1032 and is mostly used internally by pyasn1 for choosing type-specific data | |
| 1033 processing algorithms. The "effective tag" is the one that always appears in | |
| 1034 encoding and is used on tagSets comparation. | |
| 1035 </p> | |
| 1036 | |
| 1037 <p> | |
| 1038 Any two TagSet objects could be compared to see if one is a derivative | |
| 1039 of the other. Figuring this out is also useful in cases when a type-specific | |
| 1040 data processing algorithms are to be chosen. | |
| 1041 </p> | |
| 1042 | |
| 1043 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1044 <pre> | |
| 1045 >>> from pyasn1.type import tag | |
| 1046 >>> tagSet1 = tag.TagSet( | |
| 1047 ... tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 10) # base tag | |
| 1048 ... tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 10) # effective tag | |
| 1049 ... ) | |
| 1050 >>> tagSet2 = tagSet1.tagExplicitly( | |
| 1051 ... tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 20) | |
| 1052 ... ) | |
| 1053 >>> tagSet1.isSuperTagSetOf(tagSet2) | |
| 1054 True | |
| 1055 >>> tagSet2.isSuperTagSetOf(tagSet1) | |
| 1056 False | |
| 1057 >>> | |
| 1058 </pre> | |
| 1059 </td></tr></table> | |
| 1060 | |
| 1061 <p> | |
| 1062 We will complete this discussion on tagging with a real-world example. The | |
| 1063 following ASN.1 tagged type: | |
| 1064 </p> | |
| 1065 | |
| 1066 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1067 <pre> | |
| 1068 MyIntegerType ::= [12] EXPLICIT INTEGER | |
| 1069 </pre> | |
| 1070 </td></tr></table> | |
| 1071 | |
| 1072 <p> | |
| 1073 could be expressed in pyasn1 like this: | |
| 1074 </p> | |
| 1075 | |
| 1076 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1077 <pre> | |
| 1078 >>> from pyasn1.type import univ, tag | |
| 1079 >>> class MyIntegerType(univ.Integer): | |
| 1080 ... tagSet = univ.Integer.tagSet.tagExplicitly( | |
| 1081 ... tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 12) | |
| 1082 ... ) | |
| 1083 >>> myInteger = MyIntegerType(12345) | |
| 1084 >>> myInteger.getTagSet() | |
| 1085 TagSet(Tag(tagClass=0, tagFormat=0, tagId=2), | |
| 1086 Tag(tagClass=128, tagFormat=32, tagId=12)) | |
| 1087 >>> | |
| 1088 </pre> | |
| 1089 </td></tr></table> | |
| 1090 | |
| 1091 <p> | |
| 1092 Referring to the above code, the tagSet class attribute is a property of any | |
| 1093 pyasn1 type object that assigns default tagSet to a pyasn1 value object. This | |
| 1094 default tagSet specification can be ignored and effectively replaced by some | |
| 1095 other tagSet value passed on object instantiation. | |
| 1096 </p> | |
| 1097 | |
| 1098 <p> | |
| 1099 It's important to understand that the tag set property of pyasn1 type/value | |
| 1100 object can never be modifed in place. In other words, a pyasn1 type/value | |
| 1101 object can never change its tags. The only way is to create a new pyasn1 | |
| 1102 type/value object and associate different tag set with it. | |
| 1103 </p> | |
| 1104 | |
| 1105 | |
| 1106 <a name="1.3"></a> | |
| 1107 <h4> | |
| 1108 1.3 Constructed types | |
| 1109 </h4> | |
| 1110 | |
| 1111 <p> | |
| 1112 Besides scalar types, ASN.1 specifies so-called constructed ones - these | |
| 1113 are capable of holding one or more values of other types, both scalar | |
| 1114 and constructed. | |
| 1115 </p> | |
| 1116 | |
| 1117 <p> | |
| 1118 In pyasn1 implementation, constructed ASN.1 types behave like | |
| 1119 Python sequences, and also support additional component addressing methods, | |
| 1120 specific to particular constructed type. | |
| 1121 </p> | |
| 1122 | |
| 1123 <a name="1.3.1"></a> | |
| 1124 <h4> | |
| 1125 1.3.1 Sequence and Set types | |
| 1126 </h4> | |
| 1127 | |
| 1128 <p> | |
| 1129 The Sequence and Set types have many similar properties: | |
| 1130 </p> | |
| 1131 <ul> | |
| 1132 <li>they can hold any number of inner components of different types | |
| 1133 <li>every component has a human-friendly identifier | |
| 1134 <li>any component can have a default value | |
| 1135 <li>some components can be absent. | |
| 1136 </ul> | |
| 1137 | |
| 1138 <p> | |
| 1139 However, Sequence type guarantees the ordering of Sequence value components | |
| 1140 to match their declaration order. By contrast, components of the | |
| 1141 Set type can be ordered to best suite application's needs. | |
| 1142 <p> | |
| 1143 | |
| 1144 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1145 <pre> | |
| 1146 Record ::= SEQUENCE { | |
| 1147 id INTEGER, | |
| 1148 room [0] INTEGER OPTIONAL, | |
| 1149 house [1] INTEGER DEFAULT 0 | |
| 1150 } | |
| 1151 </pre> | |
| 1152 </td></tr></table> | |
| 1153 | |
| 1154 <p> | |
| 1155 Up to this moment, the only method we used for creating new pyasn1 types | |
| 1156 is Python sub-classing. With this method, a new, named Python class is created | |
| 1157 what mimics type derivation in ASN.1 grammar. However, ASN.1 also allows for | |
| 1158 defining anonymous subtypes (room and house components in the example above). | |
| 1159 To support anonymous subtyping in pyasn1, a cloning operation on an existing | |
| 1160 pyasn1 type object can be invoked what creates a new instance of original | |
| 1161 object with possibly modified properties. | |
| 1162 </p> | |
| 1163 | |
| 1164 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1165 <pre> | |
| 1166 >>> from pyasn1.type import univ, namedtype, tag | |
| 1167 >>> class Record(univ.Sequence): | |
| 1168 ... componentType = namedtype.NamedTypes( | |
| 1169 ... namedtype.NamedType('id', univ.Integer()), | |
| 1170 ... namedtype.OptionalNamedType( | |
| 1171 ... 'room', | |
| 1172 ... univ.Integer().subtype(implicitTag=tag.Tag(tag.tagClassContext, tag.ta
gFormatSimple, 0)) | |
| 1173 ... ), | |
| 1174 ... namedtype.DefaultedNamedType( | |
| 1175 ... 'house', | |
| 1176 ... univ.Integer(0).subtype(implicitTag=tag.Tag(tag.tagClassContext, tag.t
agFormatSimple, 1)) | |
| 1177 ... ) | |
| 1178 ... ) | |
| 1179 >>> | |
| 1180 </pre> | |
| 1181 </td></tr></table> | |
| 1182 | |
| 1183 <p> | |
| 1184 All pyasn1 constructed type classes have a class attribute <b>componentType</b> | |
| 1185 that represent default type specification. Its value is a NamedTypes object. | |
| 1186 </p> | |
| 1187 | |
| 1188 <p> | |
| 1189 The NamedTypes class instance holds a sequence of NameType, OptionalNamedType | |
| 1190 or DefaultedNamedType objects which, in turn, refer to pyasn1 type objects that | |
| 1191 represent inner SEQUENCE components specification. | |
| 1192 </p> | |
| 1193 | |
| 1194 <p> | |
| 1195 Finally, invocation of a subtype() method of pyasn1 type objects in the code | |
| 1196 above returns an implicitly tagged copy of original object. | |
| 1197 </p> | |
| 1198 | |
| 1199 <p> | |
| 1200 Once a SEQUENCE or SET type is decleared with pyasn1, it can be instantiated | |
| 1201 and initialized (continuing the above code): | |
| 1202 </p> | |
| 1203 | |
| 1204 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1205 <pre> | |
| 1206 >>> record = Record() | |
| 1207 >>> record.setComponentByName('id', 123) | |
| 1208 >>> print(record.prettyPrint()) | |
| 1209 Record: | |
| 1210 id=123 | |
| 1211 >>> | |
| 1212 >>> record.setComponentByPosition(1, 321) | |
| 1213 >>> print(record.prettyPrint()) | |
| 1214 Record: | |
| 1215 id=123 | |
| 1216 room=321 | |
| 1217 >>> | |
| 1218 >>> record.setDefaultComponents() | |
| 1219 >>> print(record.prettyPrint()) | |
| 1220 Record: | |
| 1221 id=123 | |
| 1222 room=321 | |
| 1223 house=0 | |
| 1224 </pre> | |
| 1225 </td></tr></table> | |
| 1226 | |
| 1227 <p> | |
| 1228 Inner components of pyasn1 Sequence/Set objects could be accessed using the | |
| 1229 following methods: | |
| 1230 </p> | |
| 1231 | |
| 1232 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1233 <pre> | |
| 1234 >>> record.getComponentByName('id') | |
| 1235 Integer(123) | |
| 1236 >>> record.getComponentByPosition(1) | |
| 1237 Integer(321) | |
| 1238 >>> record[2] | |
| 1239 Integer(0) | |
| 1240 >>> for idx in range(len(record)): | |
| 1241 ... print(record.getNameByPosition(idx), record.getComponentByPosition(idx)) | |
| 1242 id 123 | |
| 1243 room 321 | |
| 1244 house 0 | |
| 1245 >>> | |
| 1246 </pre> | |
| 1247 </td></tr></table> | |
| 1248 | |
| 1249 <p> | |
| 1250 The Set type share all the properties of Sequence type, and additionally | |
| 1251 support by-tag component addressing (as all Set components have distinct | |
| 1252 types). | |
| 1253 </p> | |
| 1254 | |
| 1255 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1256 <pre> | |
| 1257 >>> from pyasn1.type import univ, namedtype, tag | |
| 1258 >>> class Gamer(univ.Set): | |
| 1259 ... componentType = namedtype.NamedTypes( | |
| 1260 ... namedtype.NamedType('score', univ.Integer()), | |
| 1261 ... namedtype.NamedType('player', univ.OctetString()), | |
| 1262 ... namedtype.NamedType('id', univ.ObjectIdentifier()) | |
| 1263 ... ) | |
| 1264 >>> gamer = Gamer() | |
| 1265 >>> gamer.setComponentByType(univ.Integer().getTagSet(), 121343) | |
| 1266 >>> gamer.setComponentByType(univ.OctetString().getTagSet(), 'Pascal') | |
| 1267 >>> gamer.setComponentByType(univ.ObjectIdentifier().getTagSet(), (1,3,7,2)) | |
| 1268 >>> print(gamer.prettyPrint()) | |
| 1269 Gamer: | |
| 1270 score=121343 | |
| 1271 player=b'Pascal' | |
| 1272 id=1.3.7.2 | |
| 1273 >>> | |
| 1274 </pre> | |
| 1275 </td></tr></table> | |
| 1276 | |
| 1277 <a name="1.3.2"></a> | |
| 1278 <h4> | |
| 1279 1.3.2 SequenceOf and SetOf types | |
| 1280 </h4> | |
| 1281 | |
| 1282 <p> | |
| 1283 Both, SequenceOf and SetOf types resemble an unlimited size list of components. | |
| 1284 All the components must be of the same type. | |
| 1285 </p> | |
| 1286 | |
| 1287 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1288 <pre> | |
| 1289 Progression ::= SEQUENCE OF INTEGER | |
| 1290 | |
| 1291 arithmeticProgression Progression ::= { 1, 3, 5, 7 } | |
| 1292 </pre> | |
| 1293 </td></tr></table> | |
| 1294 | |
| 1295 <p> | |
| 1296 SequenceOf and SetOf types are expressed by the very similar pyasn1 type | |
| 1297 objects. Their components can only be addressed by position and they | |
| 1298 both have a property of automatic resize. | |
| 1299 </p> | |
| 1300 | |
| 1301 <p> | |
| 1302 To specify inner component type, the <b>componentType</b> class attribute | |
| 1303 should refer to another pyasn1 type object. | |
| 1304 </p> | |
| 1305 | |
| 1306 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1307 <pre> | |
| 1308 >>> from pyasn1.type import univ | |
| 1309 >>> class Progression(univ.SequenceOf): | |
| 1310 ... componentType = univ.Integer() | |
| 1311 >>> arithmeticProgression = Progression() | |
| 1312 >>> arithmeticProgression.setComponentByPosition(1, 111) | |
| 1313 >>> print(arithmeticProgression.prettyPrint()) | |
| 1314 Progression: | |
| 1315 -empty- 111 | |
| 1316 >>> arithmeticProgression.setComponentByPosition(0, 100) | |
| 1317 >>> print(arithmeticProgression.prettyPrint()) | |
| 1318 Progression: | |
| 1319 100 111 | |
| 1320 >>> | |
| 1321 >>> for idx in range(len(arithmeticProgression)): | |
| 1322 ... arithmeticProgression.getComponentByPosition(idx) | |
| 1323 Integer(100) | |
| 1324 Integer(111) | |
| 1325 >>> | |
| 1326 </pre> | |
| 1327 </td></tr></table> | |
| 1328 | |
| 1329 <p> | |
| 1330 Any scalar or constructed pyasn1 type object can serve as an inner component. | |
| 1331 Missing components are prohibited in SequenceOf/SetOf value objects. | |
| 1332 </p> | |
| 1333 | |
| 1334 <a name="1.3.3"></a> | |
| 1335 <h4> | |
| 1336 1.3.3 Choice type | |
| 1337 </h4> | |
| 1338 | |
| 1339 <p> | |
| 1340 Values of ASN.1 CHOICE type can contain only a single value of a type from a | |
| 1341 list of possible alternatives. Alternatives must be ASN.1 types with | |
| 1342 distinct tags for the whole structure to remain unambiguous. Unlike most | |
| 1343 other types, CHOICE is an untagged one, e.g. it has no base tag of its own. | |
| 1344 </p> | |
| 1345 | |
| 1346 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1347 <pre> | |
| 1348 CodeOrMessage ::= CHOICE { | |
| 1349 code INTEGER, | |
| 1350 message OCTET STRING | |
| 1351 } | |
| 1352 </pre> | |
| 1353 </td></tr></table> | |
| 1354 | |
| 1355 <p> | |
| 1356 In pyasn1 implementation, Choice object behaves like Set but accepts only | |
| 1357 a single inner component at a time. It also offers a few additional methods | |
| 1358 specific to its behaviour. | |
| 1359 </p> | |
| 1360 | |
| 1361 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1362 <pre> | |
| 1363 >>> from pyasn1.type import univ, namedtype | |
| 1364 >>> class CodeOrMessage(univ.Choice): | |
| 1365 ... componentType = namedtype.NamedTypes( | |
| 1366 ... namedtype.NamedType('code', univ.Integer()), | |
| 1367 ... namedtype.NamedType('message', univ.OctetString()) | |
| 1368 ... ) | |
| 1369 >>> | |
| 1370 >>> codeOrMessage = CodeOrMessage() | |
| 1371 >>> print(codeOrMessage.prettyPrint()) | |
| 1372 CodeOrMessage: | |
| 1373 >>> codeOrMessage.setComponentByName('code', 123) | |
| 1374 >>> print(codeOrMessage.prettyPrint()) | |
| 1375 CodeOrMessage: | |
| 1376 code=123 | |
| 1377 >>> codeOrMessage.setComponentByName('message', 'my string value') | |
| 1378 >>> print(codeOrMessage.prettyPrint()) | |
| 1379 CodeOrMessage: | |
| 1380 message=b'my string value' | |
| 1381 >>> | |
| 1382 </pre> | |
| 1383 </td></tr></table> | |
| 1384 | |
| 1385 <p> | |
| 1386 Since there could be only a single inner component value in the pyasn1 Choice | |
| 1387 value object, either of the following methods could be used for fetching it | |
| 1388 (continuing previous code): | |
| 1389 </p> | |
| 1390 | |
| 1391 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1392 <pre> | |
| 1393 >>> codeOrMessage.getName() | |
| 1394 'message' | |
| 1395 >>> codeOrMessage.getComponent() | |
| 1396 OctetString(b'my string value') | |
| 1397 >>> | |
| 1398 </pre> | |
| 1399 </td></tr></table> | |
| 1400 | |
| 1401 <a name="1.3.4"></a> | |
| 1402 <h4> | |
| 1403 1.3.4 Any type | |
| 1404 </h4> | |
| 1405 | |
| 1406 <p> | |
| 1407 The ASN.1 ANY type is a kind of wildcard or placeholder that matches | |
| 1408 any other type without knowing it in advance. Like CHOICE type, ANY | |
| 1409 has no base tag. | |
| 1410 </p> | |
| 1411 | |
| 1412 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1413 <pre> | |
| 1414 Error ::= SEQUENCE { | |
| 1415 code INTEGER, | |
| 1416 parameter ANY DEFINED BY code | |
| 1417 } | |
| 1418 </pre> | |
| 1419 </td></tr></table> | |
| 1420 | |
| 1421 <p> | |
| 1422 The ANY type is frequently used in specifications, where exact type is not | |
| 1423 yet agreed upon between communicating parties or the number of possible | |
| 1424 alternatives of a type is infinite. | |
| 1425 Sometimes an auxiliary selector is kept around to help parties indicate | |
| 1426 the kind of ANY payload in effect ("code" in the example above). | |
| 1427 </p> | |
| 1428 | |
| 1429 <p> | |
| 1430 Values of the ANY type contain serialized ASN.1 value(s) in form of | |
| 1431 an octet string. Therefore pyasn1 Any value object share the properties of | |
| 1432 pyasn1 OctetString object. | |
| 1433 </p> | |
| 1434 | |
| 1435 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1436 <pre> | |
| 1437 >>> from pyasn1.type import univ | |
| 1438 >>> someValue = univ.Any(b'\x02\x01\x01') | |
| 1439 >>> someValue | |
| 1440 Any(b'\x02\x01\x01') | |
| 1441 >>> str(someValue) | |
| 1442 '\x02\x01\x01' | |
| 1443 >>> bytes(someValue) | |
| 1444 b'\x02\x01\x01' | |
| 1445 >>> | |
| 1446 </pre> | |
| 1447 </td></tr></table> | |
| 1448 | |
| 1449 <p> | |
| 1450 Receiving application is supposed to explicitly deserialize the content of Any | |
| 1451 value object, possibly using auxiliary selector for figuring out its ASN.1 | |
| 1452 type to pick appropriate decoder. | |
| 1453 </p> | |
| 1454 | |
| 1455 <p> | |
| 1456 There will be some more talk and code snippets covering Any type in the codecs | |
| 1457 chapters that follow. | |
| 1458 </p> | |
| 1459 | |
| 1460 <a name="1.4"></a> | |
| 1461 <h4> | |
| 1462 1.4 Subtype constraints | |
| 1463 </h4> | |
| 1464 | |
| 1465 <p> | |
| 1466 Most ASN.1 types can correspond to an infinite set of values. To adapt to | |
| 1467 particular application's data model and needs, ASN.1 provides a mechanism | |
| 1468 for limiting the infinite set to values, that make sense in particular case. | |
| 1469 </p> | |
| 1470 | |
| 1471 <p> | |
| 1472 Imposing value constraints on an ASN.1 type can also be seen as creating | |
| 1473 a subtype from its base type. | |
| 1474 </p> | |
| 1475 | |
| 1476 <p> | |
| 1477 In pyasn1, constraints take shape of immutable objects capable | |
| 1478 of evaluating given value against constraint-specific requirements. | |
| 1479 Constraint object is a property of pyasn1 type. Like TagSet property, | |
| 1480 associated with every pyasn1 type, constraints can never be modified | |
| 1481 in place. The only way to modify pyasn1 type constraint is to associate | |
| 1482 new constraint object to a new pyasn1 type object. | |
| 1483 </p> | |
| 1484 | |
| 1485 <p> | |
| 1486 A handful of different flavors of <i>constraints</i> are defined in ASN.1. | |
| 1487 We will discuss them one by one in the following chapters and also explain | |
| 1488 how to combine and apply them to types. | |
| 1489 </p> | |
| 1490 | |
| 1491 <a name="1.4.1"></a> | |
| 1492 <h4> | |
| 1493 1.4.1 Single value constraint | |
| 1494 </h4> | |
| 1495 | |
| 1496 <p> | |
| 1497 This kind of constraint allows for limiting type to a finite, specified set | |
| 1498 of values. | |
| 1499 </p> | |
| 1500 | |
| 1501 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1502 <pre> | |
| 1503 DialButton ::= OCTET STRING ( | |
| 1504 "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | |
| 1505 ) | |
| 1506 </pre> | |
| 1507 </td></tr></table> | |
| 1508 | |
| 1509 <p> | |
| 1510 Its pyasn1 implementation would look like: | |
| 1511 </p> | |
| 1512 | |
| 1513 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1514 <pre> | |
| 1515 >>> from pyasn1.type import constraint | |
| 1516 >>> c = constraint.SingleValueConstraint( | |
| 1517 '0','1','2','3','4','5','6','7','8','9' | |
| 1518 ) | |
| 1519 >>> c | |
| 1520 SingleValueConstraint(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) | |
| 1521 >>> c('0') | |
| 1522 >>> c('A') | |
| 1523 Traceback (most recent call last): | |
| 1524 ... | |
| 1525 pyasn1.type.error.ValueConstraintError: | |
| 1526 SingleValueConstraint(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) failed at: A | |
| 1527 >>> | |
| 1528 </pre> | |
| 1529 </td></tr></table> | |
| 1530 | |
| 1531 <p> | |
| 1532 As can be seen in the snippet above, if a value violates the constraint, an | |
| 1533 exception will be thrown. A constrainted pyasn1 type object holds a | |
| 1534 reference to a constraint object (or their combination, as will be explained | |
| 1535 later) and calls it for value verification. | |
| 1536 </p> | |
| 1537 | |
| 1538 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1539 <pre> | |
| 1540 >>> from pyasn1.type import univ, constraint | |
| 1541 >>> class DialButton(univ.OctetString): | |
| 1542 ... subtypeSpec = constraint.SingleValueConstraint( | |
| 1543 ... '0','1','2','3','4','5','6','7','8','9' | |
| 1544 ... ) | |
| 1545 >>> DialButton('0') | |
| 1546 DialButton(b'0') | |
| 1547 >>> DialButton('A') | |
| 1548 Traceback (most recent call last): | |
| 1549 ... | |
| 1550 pyasn1.type.error.ValueConstraintError: | |
| 1551 SingleValueConstraint(0, 1, 2, 3, 4, 5, 6, 7, 8, 9) failed at: A | |
| 1552 >>> | |
| 1553 </pre> | |
| 1554 </td></tr></table> | |
| 1555 | |
| 1556 <p> | |
| 1557 Constrained pyasn1 value object can never hold a violating value. | |
| 1558 </p> | |
| 1559 | |
| 1560 <a name="1.4.2"></a> | |
| 1561 <h4> | |
| 1562 1.4.2 Value range constraint | |
| 1563 </h4> | |
| 1564 | |
| 1565 <p> | |
| 1566 A pair of values, compliant to a type to be constrained, denote low and upper | |
| 1567 bounds of allowed range of values of a type. | |
| 1568 </p> | |
| 1569 | |
| 1570 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1571 <pre> | |
| 1572 Teenagers ::= INTEGER (13..19) | |
| 1573 </pre> | |
| 1574 </td></tr></table> | |
| 1575 | |
| 1576 <p> | |
| 1577 And in pyasn1 terms: | |
| 1578 </p> | |
| 1579 | |
| 1580 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1581 <pre> | |
| 1582 >>> from pyasn1.type import univ, constraint | |
| 1583 >>> class Teenagers(univ.Integer): | |
| 1584 ... subtypeSpec = constraint.ValueRangeConstraint(13, 19) | |
| 1585 >>> Teenagers(14) | |
| 1586 Teenagers(14) | |
| 1587 >>> Teenagers(20) | |
| 1588 Traceback (most recent call last): | |
| 1589 ... | |
| 1590 pyasn1.type.error.ValueConstraintError: | |
| 1591 ValueRangeConstraint(13, 19) failed at: 20 | |
| 1592 >>> | |
| 1593 </pre> | |
| 1594 </td></tr></table> | |
| 1595 | |
| 1596 <p> | |
| 1597 Value range constraint usually applies numeric types. | |
| 1598 </p> | |
| 1599 | |
| 1600 <a name="1.4.3"></a> | |
| 1601 <h4> | |
| 1602 1.4.3 Size constraint | |
| 1603 </h4> | |
| 1604 | |
| 1605 <p> | |
| 1606 It is sometimes convenient to set or limit the allowed size of a data item | |
| 1607 to be sent from one application to another to manage bandwidth and memory | |
| 1608 consumption issues. Size constraint specifies the lower and upper bounds | |
| 1609 of the size of a valid value. | |
| 1610 </p> | |
| 1611 | |
| 1612 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1613 <pre> | |
| 1614 TwoBits ::= BIT STRING (SIZE (2)) | |
| 1615 </pre> | |
| 1616 </td></tr></table> | |
| 1617 | |
| 1618 <p> | |
| 1619 Express the same grammar in pyasn1: | |
| 1620 </p> | |
| 1621 | |
| 1622 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1623 <pre> | |
| 1624 >>> from pyasn1.type import univ, constraint | |
| 1625 >>> class TwoBits(univ.BitString): | |
| 1626 ... subtypeSpec = constraint.ValueSizeConstraint(2, 2) | |
| 1627 >>> TwoBits((1,1)) | |
| 1628 TwoBits("'11'B") | |
| 1629 >>> TwoBits((1,1,0)) | |
| 1630 Traceback (most recent call last): | |
| 1631 ... | |
| 1632 pyasn1.type.error.ValueConstraintError: | |
| 1633 ValueSizeConstraint(2, 2) failed at: (1, 1, 0) | |
| 1634 >>> | |
| 1635 </pre> | |
| 1636 </td></tr></table> | |
| 1637 | |
| 1638 <p> | |
| 1639 Size constraint can be applied to potentially massive values - bit or octet | |
| 1640 strings, SEQUENCE OF/SET OF values. | |
| 1641 </p> | |
| 1642 | |
| 1643 <a name="1.4.4"></a> | |
| 1644 <h4> | |
| 1645 1.4.4 Alphabet constraint | |
| 1646 </h4> | |
| 1647 | |
| 1648 <p> | |
| 1649 The permitted alphabet constraint is similar to Single value constraint | |
| 1650 but constraint applies to individual characters of a value. | |
| 1651 </p> | |
| 1652 | |
| 1653 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1654 <pre> | |
| 1655 MorseCode ::= PrintableString (FROM ("."|"-"|" ")) | |
| 1656 </pre> | |
| 1657 </td></tr></table> | |
| 1658 | |
| 1659 <p> | |
| 1660 And in pyasn1: | |
| 1661 </p> | |
| 1662 | |
| 1663 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1664 <pre> | |
| 1665 >>> from pyasn1.type import char, constraint | |
| 1666 >>> class MorseCode(char.PrintableString): | |
| 1667 ... subtypeSpec = constraint.PermittedAlphabetConstraint(".", "-", " ") | |
| 1668 >>> MorseCode("...---...") | |
| 1669 MorseCode('...---...') | |
| 1670 >>> MorseCode("?") | |
| 1671 Traceback (most recent call last): | |
| 1672 ... | |
| 1673 pyasn1.type.error.ValueConstraintError: | |
| 1674 PermittedAlphabetConstraint(".", "-", " ") failed at: "?" | |
| 1675 >>> | |
| 1676 </pre> | |
| 1677 </td></tr></table> | |
| 1678 | |
| 1679 <p> | |
| 1680 Current implementation does not handle ranges of characters in constraint | |
| 1681 (FROM "A".."Z" syntax), one has to list the whole set in a range. | |
| 1682 </p> | |
| 1683 | |
| 1684 <a name="1.4.5"></a> | |
| 1685 <h4> | |
| 1686 1.4.5 Constraint combinations | |
| 1687 </h4> | |
| 1688 | |
| 1689 <p> | |
| 1690 Up to this moment, we used a single constraint per ASN.1 type. The standard, | |
| 1691 however, allows for combining multiple individual constraints into | |
| 1692 intersections, unions and exclusions. | |
| 1693 </p> | |
| 1694 | |
| 1695 <p> | |
| 1696 In pyasn1 data model, all of these methods of constraint combinations are | |
| 1697 implemented as constraint-like objects holding individual constraint (or | |
| 1698 combination) objects. Like terminal constraint objects, combination objects | |
| 1699 are capable to perform value verification at its set of enclosed constraints | |
| 1700 according to the logic of particular combination. | |
| 1701 </p> | |
| 1702 | |
| 1703 <p> | |
| 1704 Constraints intersection verification succeeds only if a value is | |
| 1705 compliant to each constraint in a set. To begin with, the following | |
| 1706 specification will constitute a valid telephone number: | |
| 1707 </p> | |
| 1708 | |
| 1709 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1710 <pre> | |
| 1711 PhoneNumber ::= NumericString (FROM ("0".."9")) (SIZE 11) | |
| 1712 </pre> | |
| 1713 </td></tr></table> | |
| 1714 | |
| 1715 <p> | |
| 1716 Constraint intersection object serves the logic above: | |
| 1717 </p> | |
| 1718 | |
| 1719 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1720 <pre> | |
| 1721 >>> from pyasn1.type import char, constraint | |
| 1722 >>> class PhoneNumber(char.NumericString): | |
| 1723 ... subtypeSpec = constraint.ConstraintsIntersection( | |
| 1724 ... constraint.PermittedAlphabetConstraint('0','1','2','3','4','5','6','7','
8','9'), | |
| 1725 ... constraint.ValueSizeConstraint(11, 11) | |
| 1726 ... ) | |
| 1727 >>> PhoneNumber('79039343212') | |
| 1728 PhoneNumber('79039343212') | |
| 1729 >>> PhoneNumber('?9039343212') | |
| 1730 Traceback (most recent call last): | |
| 1731 ... | |
| 1732 pyasn1.type.error.ValueConstraintError: | |
| 1733 ConstraintsIntersection( | |
| 1734 PermittedAlphabetConstraint('0','1','2','3','4','5','6','7','8','9'), | |
| 1735 ValueSizeConstraint(11, 11)) failed at: | |
| 1736 PermittedAlphabetConstraint('0','1','2','3','4','5','6','7','8','9') failed a
t: "?039343212" | |
| 1737 >>> PhoneNumber('9343212') | |
| 1738 Traceback (most recent call last): | |
| 1739 ... | |
| 1740 pyasn1.type.error.ValueConstraintError: | |
| 1741 ConstraintsIntersection( | |
| 1742 PermittedAlphabetConstraint('0','1','2','3','4','5','6','7','8','9'), | |
| 1743 ValueSizeConstraint(11, 11)) failed at: | |
| 1744 ValueSizeConstraint(10, 10) failed at: "9343212" | |
| 1745 >>> | |
| 1746 </pre> | |
| 1747 </td></tr></table> | |
| 1748 | |
| 1749 <p> | |
| 1750 Union of constraints works by making sure that a value is compliant | |
| 1751 to any of the constraint in a set. For instance: | |
| 1752 </p> | |
| 1753 | |
| 1754 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1755 <pre> | |
| 1756 CapitalOrSmall ::= IA5String (FROM ('A','B','C') | FROM ('a','b','c')) | |
| 1757 </pre> | |
| 1758 </td></tr></table> | |
| 1759 | |
| 1760 <p> | |
| 1761 It's important to note, that a value must fully comply to any single | |
| 1762 constraint in a set. In the specification above, a value of all small or | |
| 1763 all capital letters is compliant, but a mix of small&capitals is not. | |
| 1764 Here's its pyasn1 analogue: | |
| 1765 </p> | |
| 1766 | |
| 1767 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1768 <pre> | |
| 1769 >>> from pyasn1.type import char, constraint | |
| 1770 >>> class CapitalOrSmall(char.IA5String): | |
| 1771 ... subtypeSpec = constraint.ConstraintsUnion( | |
| 1772 ... constraint.PermittedAlphabetConstraint('A','B','C'), | |
| 1773 ... constraint.PermittedAlphabetConstraint('a','b','c') | |
| 1774 ... ) | |
| 1775 >>> CapitalOrSmall('ABBA') | |
| 1776 CapitalOrSmall('ABBA') | |
| 1777 >>> CapitalOrSmall('abba') | |
| 1778 CapitalOrSmall('abba') | |
| 1779 >>> CapitalOrSmall('Abba') | |
| 1780 Traceback (most recent call last): | |
| 1781 ... | |
| 1782 pyasn1.type.error.ValueConstraintError: | |
| 1783 ConstraintsUnion(PermittedAlphabetConstraint('A', 'B', 'C'), | |
| 1784 PermittedAlphabetConstraint('a', 'b', 'c')) failed at: failed for "Abba" | |
| 1785 >>> | |
| 1786 </pre> | |
| 1787 </td></tr></table> | |
| 1788 | |
| 1789 <p> | |
| 1790 Finally, the exclusion constraint simply negates the logic of value | |
| 1791 verification at a constraint. In the following example, any integer value | |
| 1792 is allowed in a type but not zero. | |
| 1793 </p> | |
| 1794 | |
| 1795 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1796 <pre> | |
| 1797 NoZero ::= INTEGER (ALL EXCEPT 0) | |
| 1798 </pre> | |
| 1799 </td></tr></table> | |
| 1800 | |
| 1801 <p> | |
| 1802 In pyasn1 the above definition would read: | |
| 1803 </p> | |
| 1804 | |
| 1805 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1806 <pre> | |
| 1807 >>> from pyasn1.type import univ, constraint | |
| 1808 >>> class NoZero(univ.Integer): | |
| 1809 ... subtypeSpec = constraint.ConstraintsExclusion( | |
| 1810 ... constraint.SingleValueConstraint(0) | |
| 1811 ... ) | |
| 1812 >>> NoZero(1) | |
| 1813 NoZero(1) | |
| 1814 >>> NoZero(0) | |
| 1815 Traceback (most recent call last): | |
| 1816 ... | |
| 1817 pyasn1.type.error.ValueConstraintError: | |
| 1818 ConstraintsExclusion(SingleValueConstraint(0)) failed at: 0 | |
| 1819 >>> | |
| 1820 </pre> | |
| 1821 </td></tr></table> | |
| 1822 | |
| 1823 <p> | |
| 1824 The depth of such a constraints tree, built with constraint combination objects | |
| 1825 at its nodes, has not explicit limit. Value verification is performed in a | |
| 1826 recursive manner till a definite solution is found. | |
| 1827 </p> | |
| 1828 | |
| 1829 <a name="1.5"></a> | |
| 1830 <h4> | |
| 1831 1.5 Types relationships | |
| 1832 </h4> | |
| 1833 | |
| 1834 <p> | |
| 1835 In the course of data processing in an application, it is sometimes | |
| 1836 convenient to figure out the type relationships between pyasn1 type or | |
| 1837 value objects. Formally, two things influence pyasn1 types relationship: | |
| 1838 <i>tag set</i> and <i>subtype constraints</i>. One pyasn1 type is considered | |
| 1839 to be a derivative of another if their TagSet and Constraint objects are | |
| 1840 a derivation of one another. | |
| 1841 </p> | |
| 1842 | |
| 1843 <p> | |
| 1844 The following example illustrates the concept (we use the same tagset but | |
| 1845 different constraints for simplicity): | |
| 1846 </p> | |
| 1847 | |
| 1848 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1849 <pre> | |
| 1850 >>> from pyasn1.type import univ, constraint | |
| 1851 >>> i1 = univ.Integer(subtypeSpec=constraint.ValueRangeConstraint(3,8)) | |
| 1852 >>> i2 = univ.Integer(subtypeSpec=constraint.ConstraintsIntersection( | |
| 1853 ... constraint.ValueRangeConstraint(3,8), | |
| 1854 ... constraint.ValueRangeConstraint(4,7) | |
| 1855 ... ) ) | |
| 1856 >>> i1.isSameTypeWith(i2) | |
| 1857 False | |
| 1858 >>> i1.isSuperTypeOf(i2) | |
| 1859 True | |
| 1860 >>> i1.isSuperTypeOf(i1) | |
| 1861 True | |
| 1862 >>> i2.isSuperTypeOf(i1) | |
| 1863 False | |
| 1864 >>> | |
| 1865 </pre> | |
| 1866 </td></tr></table> | |
| 1867 | |
| 1868 <p> | |
| 1869 As can be seen in the above code snippet, there are two methods of any pyasn1 | |
| 1870 type/value object that test types for their relationship: | |
| 1871 <b>isSameTypeWith</b>() and <b>isSuperTypeOf</b>(). The former is | |
| 1872 self-descriptive while the latter yields true if the argument appears | |
| 1873 to be a pyasn1 object which has tagset and constraints derived from those | |
| 1874 of the object being called. | |
| 1875 </p> | |
| 1876 | |
| 1877 <a name="2"></a> | |
| 1878 <h3> | |
| 1879 2. Codecs | |
| 1880 </h3> | |
| 1881 | |
| 1882 <p> | |
| 1883 In ASN.1 context, | |
| 1884 <a href=http://en.wikipedia.org/wiki/Codec>codec</a> | |
| 1885 is a program that transforms between concrete data structures and a stream | |
| 1886 of octets, suitable for transmission over the wire. This serialized form of | |
| 1887 data is sometimes called <i>substrate</i> or <i>essence</i>. | |
| 1888 </p> | |
| 1889 | |
| 1890 <p> | |
| 1891 In pyasn1 implementation, substrate takes shape of Python 3 bytes or | |
| 1892 Python 2 string objects. | |
| 1893 </p> | |
| 1894 | |
| 1895 <p> | |
| 1896 One of the properties of a codec is its ability to cope with incomplete | |
| 1897 data and/or substrate what implies codec to be stateful. In other words, | |
| 1898 when decoder runs out of substrate and data item being recovered is still | |
| 1899 incomplete, stateful codec would suspend and complete data item recovery | |
| 1900 whenever the rest of substrate becomes available. Similarly, stateful encoder | |
| 1901 would encode data items in multiple steps waiting for source data to | |
| 1902 arrive. Codec restartability is especially important when application deals | |
| 1903 with large volumes of data and/or runs on low RAM. For an interesting | |
| 1904 discussion on codecs options and design choices, refer to | |
| 1905 <a href=http://directory.apache.org/subprojects/asn1/>Apache ASN.1 project</a> | |
| 1906 . | |
| 1907 </p> | |
| 1908 | |
| 1909 <p> | |
| 1910 As of this writing, codecs implemented in pyasn1 are all stateless, mostly | |
| 1911 to keep the code simple. | |
| 1912 </p> | |
| 1913 | |
| 1914 <p> | |
| 1915 The pyasn1 package currently supports | |
| 1916 <a href=http://en.wikipedia.org/wiki/Basic_encoding_rules>BER</a> codec and | |
| 1917 its variations -- | |
| 1918 <a href=http://en.wikipedia.org/wiki/Canonical_encoding_rules>CER</a> and | |
| 1919 <a href=http://en.wikipedia.org/wiki/Distinguished_encoding_rules>DER</a>. | |
| 1920 More ASN.1 codecs are planned for implementation in the future. | |
| 1921 </p> | |
| 1922 | |
| 1923 <a name="2.1"></a> | |
| 1924 <h4> | |
| 1925 2.1 Encoders | |
| 1926 </h4> | |
| 1927 | |
| 1928 <p> | |
| 1929 Encoder is used for transforming pyasn1 value objects into substrate. Only | |
| 1930 pyasn1 value objects could be serialized, attempts to process pyasn1 type | |
| 1931 objects will cause encoder failure. | |
| 1932 </p> | |
| 1933 | |
| 1934 <p> | |
| 1935 The following code will create a pyasn1 Integer object and serialize it with | |
| 1936 BER encoder: | |
| 1937 </p> | |
| 1938 | |
| 1939 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1940 <pre> | |
| 1941 >>> from pyasn1.type import univ | |
| 1942 >>> from pyasn1.codec.ber import encoder | |
| 1943 >>> encoder.encode(univ.Integer(123456)) | |
| 1944 b'\x02\x03\x01\xe2@' | |
| 1945 >>> | |
| 1946 </pre> | |
| 1947 </td></tr></table> | |
| 1948 | |
| 1949 <p> | |
| 1950 BER standard also defines a so-called <i>indefinite length</i> encoding form | |
| 1951 which makes large data items processing more memory efficient. It is mostly | |
| 1952 useful when encoder does not have the whole value all at once and the | |
| 1953 length of the value can not be determined at the beginning of encoding. | |
| 1954 </p> | |
| 1955 | |
| 1956 <p> | |
| 1957 <i>Constructed encoding</i> is another feature of BER closely related to the | |
| 1958 indefinite length form. In essence, a large scalar value (such as ASN.1 | |
| 1959 character BitString type) could be chopped into smaller chunks by encoder | |
| 1960 and transmitted incrementally to limit memory consumption. Unlike indefinite | |
| 1961 length case, the length of the whole value must be known in advance when | |
| 1962 using constructed, definite length encoding form. | |
| 1963 </p> | |
| 1964 | |
| 1965 <p> | |
| 1966 Since pyasn1 codecs are not restartable, pyasn1 encoder may only encode data | |
| 1967 item all at once. However, even in this case, generating indefinite length | |
| 1968 encoding may help a low-memory receiver, running a restartable decoder, | |
| 1969 to process a large data item. | |
| 1970 </p> | |
| 1971 | |
| 1972 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 1973 <pre> | |
| 1974 >>> from pyasn1.type import univ | |
| 1975 >>> from pyasn1.codec.ber import encoder | |
| 1976 >>> encoder.encode( | |
| 1977 ... univ.OctetString('The quick brown fox jumps over the lazy dog'), | |
| 1978 ... defMode=False, | |
| 1979 ... maxChunkSize=8 | |
| 1980 ... ) | |
| 1981 b'$\x80\x04\x08The quic\x04\x08k brown \x04\x08fox jump\x04\x08s over \ | |
| 1982 t\x04\x08he lazy \x04\x03dog\x00\x00' | |
| 1983 >>> | |
| 1984 >>> encoder.encode( | |
| 1985 ... univ.OctetString('The quick brown fox jumps over the lazy dog'), | |
| 1986 ... maxChunkSize=8 | |
| 1987 ... ) | |
| 1988 b'$7\x04\x08The quic\x04\x08k brown \x04\x08fox jump\x04\x08s over \ | |
| 1989 t\x04\x08he lazy \x04\x03dog' | |
| 1990 </pre> | |
| 1991 </td></tr></table> | |
| 1992 | |
| 1993 <p> | |
| 1994 The <b>defMode</b> encoder parameter disables definite length encoding mode, | |
| 1995 while the optional <b>maxChunkSize</b> parameter specifies desired | |
| 1996 substrate chunk size that influences memory requirements at the decoder's end. | |
| 1997 </p> | |
| 1998 | |
| 1999 <p> | |
| 2000 To use CER or DER encoders one needs to explicitly import and call them - the | |
| 2001 APIs are all compatible. | |
| 2002 </p> | |
| 2003 | |
| 2004 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2005 <pre> | |
| 2006 >>> from pyasn1.type import univ | |
| 2007 >>> from pyasn1.codec.ber import encoder as ber_encoder | |
| 2008 >>> from pyasn1.codec.cer import encoder as cer_encoder | |
| 2009 >>> from pyasn1.codec.der import encoder as der_encoder | |
| 2010 >>> ber_encoder.encode(univ.Boolean(True)) | |
| 2011 b'\x01\x01\x01' | |
| 2012 >>> cer_encoder.encode(univ.Boolean(True)) | |
| 2013 b'\x01\x01\xff' | |
| 2014 >>> der_encoder.encode(univ.Boolean(True)) | |
| 2015 b'\x01\x01\xff' | |
| 2016 >>> | |
| 2017 </pre> | |
| 2018 </td></tr></table> | |
| 2019 | |
| 2020 <a name="2.2"></a> | |
| 2021 <h4> | |
| 2022 2.2 Decoders | |
| 2023 </h4> | |
| 2024 | |
| 2025 <p> | |
| 2026 In the process of decoding, pyasn1 value objects are created and linked to | |
| 2027 each other, based on the information containted in the substrate. Thus, | |
| 2028 the original pyasn1 value object(s) are recovered. | |
| 2029 </p> | |
| 2030 | |
| 2031 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2032 <pre> | |
| 2033 >>> from pyasn1.type import univ | |
| 2034 >>> from pyasn1.codec.ber import encoder, decoder | |
| 2035 >>> substrate = encoder.encode(univ.Boolean(True)) | |
| 2036 >>> decoder.decode(substrate) | |
| 2037 (Boolean('True(1)'), b'') | |
| 2038 >>> | |
| 2039 </pre> | |
| 2040 </td></tr></table> | |
| 2041 | |
| 2042 <p> | |
| 2043 Commenting on the code snippet above, pyasn1 decoder accepts substrate | |
| 2044 as an argument and returns a tuple of pyasn1 value object (possibly | |
| 2045 a top-level one in case of constructed object) and unprocessed part | |
| 2046 of input substrate. | |
| 2047 </p> | |
| 2048 | |
| 2049 <p> | |
| 2050 All pyasn1 decoders can handle both definite and indefinite length | |
| 2051 encoding modes automatically, explicit switching into one mode | |
| 2052 to another is not required. | |
| 2053 </p> | |
| 2054 | |
| 2055 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2056 <pre> | |
| 2057 >>> from pyasn1.type import univ | |
| 2058 >>> from pyasn1.codec.ber import encoder, decoder | |
| 2059 >>> substrate = encoder.encode( | |
| 2060 ... univ.OctetString('The quick brown fox jumps over the lazy dog'), | |
| 2061 ... defMode=False, | |
| 2062 ... maxChunkSize=8 | |
| 2063 ... ) | |
| 2064 >>> decoder.decode(substrate) | |
| 2065 (OctetString(b'The quick brown fox jumps over the lazy dog'), b'') | |
| 2066 >>> | |
| 2067 </pre> | |
| 2068 </td></tr></table> | |
| 2069 | |
| 2070 <p> | |
| 2071 Speaking of BER/CER/DER encoding, in many situations substrate may not contain | |
| 2072 all necessary information needed for complete and accurate ASN.1 values | |
| 2073 recovery. The most obvious cases include implicitly tagged ASN.1 types | |
| 2074 and constrained types. | |
| 2075 </p> | |
| 2076 | |
| 2077 <p> | |
| 2078 As discussed earlier in this handbook, when an ASN.1 type is implicitly | |
| 2079 tagged, previous outermost tag is lost and never appears in substrate. | |
| 2080 If it is the base tag that gets lost, decoder is unable to pick type-specific | |
| 2081 value decoder at its table of built-in types, and therefore recover | |
| 2082 the value part, based only on the information contained in substrate. The | |
| 2083 approach taken by pyasn1 decoder is to use a prototype pyasn1 type object (or | |
| 2084 a set of them) to <i>guide</i> the decoding process by matching [possibly | |
| 2085 incomplete] tags recovered from substrate with those found in prototype pyasn1 | |
| 2086 type objects (also called pyasn1 specification object further in this paper). | |
| 2087 </p> | |
| 2088 | |
| 2089 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2090 <pre> | |
| 2091 >>> from pyasn1.codec.ber import decoder | |
| 2092 >>> decoder.decode(b'\x02\x01\x0c', asn1Spec=univ.Integer()) | |
| 2093 Integer(12), b'' | |
| 2094 >>> | |
| 2095 </pre> | |
| 2096 </td></tr></table> | |
| 2097 | |
| 2098 <p> | |
| 2099 Decoder would neither modify pyasn1 specification object nor use | |
| 2100 its current values (if it's a pyasn1 value object), but rather use it as | |
| 2101 a hint for choosing proper decoder and as a pattern for creating new objects: | |
| 2102 </p> | |
| 2103 | |
| 2104 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2105 <pre> | |
| 2106 >>> from pyasn1.type import univ, tag | |
| 2107 >>> from pyasn1.codec.ber import encoder, decoder | |
| 2108 >>> i = univ.Integer(12345).subtype( | |
| 2109 ... implicitTag=tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 40) | |
| 2110 ... ) | |
| 2111 >>> substrate = encoder.encode(i) | |
| 2112 >>> substrate | |
| 2113 b'\x9f(\x0209' | |
| 2114 >>> decoder.decode(substrate) | |
| 2115 Traceback (most recent call last): | |
| 2116 ... | |
| 2117 pyasn1.error.PyAsn1Error: | |
| 2118 TagSet(Tag(tagClass=128, tagFormat=0, tagId=40)) not in asn1Spec | |
| 2119 >>> decoder.decode(substrate, asn1Spec=i) | |
| 2120 (Integer(12345), b'') | |
| 2121 >>> | |
| 2122 </pre> | |
| 2123 </td></tr></table> | |
| 2124 | |
| 2125 <p> | |
| 2126 Notice in the example above, that an attempt to run decoder without passing | |
| 2127 pyasn1 specification object fails because recovered tag does not belong | |
| 2128 to any of the built-in types. | |
| 2129 </p> | |
| 2130 | |
| 2131 <p> | |
| 2132 Another important feature of guided decoder operation is the use of | |
| 2133 values constraints possibly present in pyasn1 specification object. | |
| 2134 To explain this, we will decode a random integer object into generic Integer | |
| 2135 and the constrained one. | |
| 2136 </p> | |
| 2137 | |
| 2138 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2139 <pre> | |
| 2140 >>> from pyasn1.type import univ, constraint | |
| 2141 >>> from pyasn1.codec.ber import encoder, decoder | |
| 2142 >>> class DialDigit(univ.Integer): | |
| 2143 ... subtypeSpec = constraint.ValueRangeConstraint(0,9) | |
| 2144 >>> substrate = encoder.encode(univ.Integer(13)) | |
| 2145 >>> decoder.decode(substrate) | |
| 2146 (Integer(13), b'') | |
| 2147 >>> decoder.decode(substrate, asn1Spec=DialDigit()) | |
| 2148 Traceback (most recent call last): | |
| 2149 ... | |
| 2150 pyasn1.type.error.ValueConstraintError: | |
| 2151 ValueRangeConstraint(0, 9) failed at: 13 | |
| 2152 >>> | |
| 2153 </pre> | |
| 2154 </td></tr></table> | |
| 2155 | |
| 2156 <p> | |
| 2157 Similarily to encoders, to use CER or DER decoders application has to | |
| 2158 explicitly import and call them - all APIs are compatible. | |
| 2159 </p> | |
| 2160 | |
| 2161 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2162 <pre> | |
| 2163 >>> from pyasn1.type import univ | |
| 2164 >>> from pyasn1.codec.ber import encoder as ber_encoder | |
| 2165 >>> substrate = ber_encoder.encode(univ.OctetString('http://pyasn1.sf.net')) | |
| 2166 >>> | |
| 2167 >>> from pyasn1.codec.ber import decoder as ber_decoder | |
| 2168 >>> from pyasn1.codec.cer import decoder as cer_decoder | |
| 2169 >>> from pyasn1.codec.der import decoder as der_decoder | |
| 2170 >>> | |
| 2171 >>> ber_decoder.decode(substrate) | |
| 2172 (OctetString(b'http://pyasn1.sf.net'), b'') | |
| 2173 >>> cer_decoder.decode(substrate) | |
| 2174 (OctetString(b'http://pyasn1.sf.net'), b'') | |
| 2175 >>> der_decoder.decode(substrate) | |
| 2176 (OctetString(b'http://pyasn1.sf.net'), b'') | |
| 2177 >>> | |
| 2178 </pre> | |
| 2179 </td></tr></table> | |
| 2180 | |
| 2181 <a name="2.2.1"></a> | |
| 2182 <h4> | |
| 2183 2.2.1 Decoding untagged types | |
| 2184 </h4> | |
| 2185 | |
| 2186 <p> | |
| 2187 It has already been mentioned, that ASN.1 has two "special case" types: | |
| 2188 CHOICE and ANY. They are different from other types in part of | |
| 2189 tagging - unless these two are additionally tagged, neither of them will | |
| 2190 have their own tag. Therefore these types become invisible in substrate | |
| 2191 and can not be recovered without passing pyasn1 specification object to | |
| 2192 decoder. | |
| 2193 </p> | |
| 2194 | |
| 2195 <p> | |
| 2196 To explain the issue, we will first prepare a Choice object to deal with: | |
| 2197 </p> | |
| 2198 | |
| 2199 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2200 <pre> | |
| 2201 >>> from pyasn1.type import univ, namedtype | |
| 2202 >>> class CodeOrMessage(univ.Choice): | |
| 2203 ... componentType = namedtype.NamedTypes( | |
| 2204 ... namedtype.NamedType('code', univ.Integer()), | |
| 2205 ... namedtype.NamedType('message', univ.OctetString()) | |
| 2206 ... ) | |
| 2207 >>> | |
| 2208 >>> codeOrMessage = CodeOrMessage() | |
| 2209 >>> codeOrMessage.setComponentByName('message', 'my string value') | |
| 2210 >>> print(codeOrMessage.prettyPrint()) | |
| 2211 CodeOrMessage: | |
| 2212 message=b'my string value' | |
| 2213 >>> | |
| 2214 </pre> | |
| 2215 </td></tr></table> | |
| 2216 | |
| 2217 <p> | |
| 2218 Let's now encode this Choice object and then decode its substrate | |
| 2219 with and without pyasn1 specification object: | |
| 2220 </p> | |
| 2221 | |
| 2222 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2223 <pre> | |
| 2224 >>> from pyasn1.codec.ber import encoder, decoder | |
| 2225 >>> substrate = encoder.encode(codeOrMessage) | |
| 2226 >>> substrate | |
| 2227 b'\x04\x0fmy string value' | |
| 2228 >>> encoder.encode(univ.OctetString('my string value')) | |
| 2229 b'\x04\x0fmy string value' | |
| 2230 >>> | |
| 2231 >>> decoder.decode(substrate) | |
| 2232 (OctetString(b'my string value'), b'') | |
| 2233 >>> codeOrMessage, substrate = decoder.decode(substrate, asn1Spec=CodeOrMessage(
)) | |
| 2234 >>> print(codeOrMessage.prettyPrint()) | |
| 2235 CodeOrMessage: | |
| 2236 message=b'my string value' | |
| 2237 >>> | |
| 2238 </pre> | |
| 2239 </td></tr></table> | |
| 2240 | |
| 2241 <p> | |
| 2242 First thing to notice in the listing above is that the substrate produced | |
| 2243 for our Choice value object is equivalent to the substrate for an OctetString | |
| 2244 object initialized to the same value. In other words, any information about | |
| 2245 the Choice component is absent in encoding. | |
| 2246 </p> | |
| 2247 | |
| 2248 <p> | |
| 2249 Sure enough, that kind of substrate will decode into an OctetString object, | |
| 2250 unless original Choice type object is passed to decoder to guide the decoding | |
| 2251 process. | |
| 2252 </p> | |
| 2253 | |
| 2254 <p> | |
| 2255 Similarily untagged ANY type behaves differently on decoding phase - when | |
| 2256 decoder bumps into an Any object in pyasn1 specification, it stops decoding | |
| 2257 and puts all the substrate into a new Any value object in form of an octet | |
| 2258 string. Concerned application could then re-run decoder with an additional, | |
| 2259 more exact pyasn1 specification object to recover the contents of Any | |
| 2260 object. | |
| 2261 </p> | |
| 2262 | |
| 2263 <p> | |
| 2264 As it was mentioned elsewhere in this paper, Any type allows for incomplete | |
| 2265 or changing ASN.1 specification to be handled gracefully by decoder and | |
| 2266 applications. | |
| 2267 </p> | |
| 2268 | |
| 2269 <p> | |
| 2270 To illustrate the working of Any type, we'll have to make the stage | |
| 2271 by encoding a pyasn1 object and then putting its substrate into an any | |
| 2272 object. | |
| 2273 </p> | |
| 2274 | |
| 2275 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2276 <pre> | |
| 2277 >>> from pyasn1.type import univ | |
| 2278 >>> from pyasn1.codec.ber import encoder, decoder | |
| 2279 >>> innerSubstrate = encoder.encode(univ.Integer(1234)) | |
| 2280 >>> innerSubstrate | |
| 2281 b'\x02\x02\x04\xd2' | |
| 2282 >>> any = univ.Any(innerSubstrate) | |
| 2283 >>> any | |
| 2284 Any(b'\x02\x02\x04\xd2') | |
| 2285 >>> substrate = encoder.encode(any) | |
| 2286 >>> substrate | |
| 2287 b'\x02\x02\x04\xd2' | |
| 2288 >>> | |
| 2289 </pre> | |
| 2290 </td></tr></table> | |
| 2291 | |
| 2292 <p> | |
| 2293 As with Choice type encoding, there is no traces of Any type in substrate. | |
| 2294 Obviously, the substrate we are dealing with, will decode into the inner | |
| 2295 [Integer] component, unless pyasn1 specification is given to guide the | |
| 2296 decoder. Continuing previous code: | |
| 2297 </p> | |
| 2298 | |
| 2299 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2300 <pre> | |
| 2301 >>> from pyasn1.type import univ | |
| 2302 >>> from pyasn1.codec.ber import encoder, decoder | |
| 2303 | |
| 2304 >>> decoder.decode(substrate) | |
| 2305 (Integer(1234), b'') | |
| 2306 >>> any, substrate = decoder.decode(substrate, asn1Spec=univ.Any()) | |
| 2307 >>> any | |
| 2308 Any(b'\x02\x02\x04\xd2') | |
| 2309 >>> decoder.decode(str(any)) | |
| 2310 (Integer(1234), b'') | |
| 2311 >>> | |
| 2312 </pre> | |
| 2313 </td></tr></table> | |
| 2314 | |
| 2315 <p> | |
| 2316 Both CHOICE and ANY types are widely used in practice. Reader is welcome to | |
| 2317 take a look at | |
| 2318 <a href=http://www.cs.auckland.ac.nz/~pgut001/pubs/x509guide.txt> | |
| 2319 ASN.1 specifications of X.509 applications</a> for more information. | |
| 2320 </p> | |
| 2321 | |
| 2322 <a name="2.2.2"></a> | |
| 2323 <h4> | |
| 2324 2.2.2 Ignoring unknown types | |
| 2325 </h4> | |
| 2326 | |
| 2327 <p> | |
| 2328 When dealing with a loosely specified ASN.1 structure, the receiving | |
| 2329 end may not be aware of some types present in the substrate. It may be | |
| 2330 convenient then to turn decoder into a recovery mode. Whilst there, decoder | |
| 2331 will not bail out when hit an unknown tag but rather treat it as an Any | |
| 2332 type. | |
| 2333 </p> | |
| 2334 | |
| 2335 <table bgcolor="lightgray" border=0 width=100%><TR><TD> | |
| 2336 <pre> | |
| 2337 >>> from pyasn1.type import univ, tag | |
| 2338 >>> from pyasn1.codec.ber import encoder, decoder | |
| 2339 >>> taggedInt = univ.Integer(12345).subtype( | |
| 2340 ... implicitTag=tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 40) | |
| 2341 ... ) | |
| 2342 >>> substrate = encoder.encode(taggedInt) | |
| 2343 >>> decoder.decode(substrate) | |
| 2344 Traceback (most recent call last): | |
| 2345 ... | |
| 2346 pyasn1.error.PyAsn1Error: TagSet(Tag(tagClass=128, tagFormat=0, tagId=40)) not i
n asn1Spec | |
| 2347 >>> | |
| 2348 >>> decoder.decode.defaultErrorState = decoder.stDumpRawValue | |
| 2349 >>> decoder.decode(substrate) | |
| 2350 (Any(b'\x9f(\x0209'), '') | |
| 2351 >>> | |
| 2352 </pre> | |
| 2353 </td></tr></table> | |
| 2354 | |
| 2355 <p> | |
| 2356 It's also possible to configure a custom decoder, to handle unknown tags | |
| 2357 found in substrate. This can be done by means of <b>defaultRawDecoder</b> | |
| 2358 attribute holding a reference to type decoder object. Refer to the source | |
| 2359 for API details. | |
| 2360 </p> | |
| 2361 | |
| 2362 <a name="3"></a> | |
| 2363 <h3> | |
| 2364 3. Feedback and getting help | |
| 2365 </h3> | |
| 2366 | |
| 2367 <p> | |
| 2368 Although pyasn1 software is almost a decade old and used in many production | |
| 2369 environments, it still may have bugs and non-implemented pieces. Anyone | |
| 2370 who happens to run into such defect is welcome to complain to | |
| 2371 <a href=mailto:pyasn1-users@lists.sourceforge.net>pyasn1 mailing list</a> | |
| 2372 or better yet fix the issue and send | |
| 2373 <a href=mailto:ilya@glas.net>me</a> the patch. | |
| 2374 </p> | |
| 2375 | |
| 2376 <p> | |
| 2377 Typically, pyasn1 is used for building arbitrary protocol support into | |
| 2378 various applications. This involves manual translation of ASN.1 data | |
| 2379 structures into their pyasn1 implementations. To save time and effort, | |
| 2380 data structures for some of the popular protocols are pre-programmed | |
| 2381 and kept for further re-use in form of the | |
| 2382 <a href=http://sourceforge.net/projects/pyasn1/files/pyasn1-modules/> | |
| 2383 pyasn1-modules package</a>. For instance, many structures for PKI (X.509, | |
| 2384 PKCS#*, CRMF, OCSP), LDAP and SNMP are present. | |
| 2385 Applications authors are advised to import and use relevant modules | |
| 2386 from that package whenever needed protocol structures are already | |
| 2387 there. New protocol modules contributions are welcome. | |
| 2388 </p> | |
| 2389 | |
| 2390 <p> | |
| 2391 And finally, the latest pyasn1 package revision is available for free | |
| 2392 download from | |
| 2393 <a href=http://sourceforge.net/projects/pyasn1/>project home</a> and | |
| 2394 also from the | |
| 2395 <a href=http://pypi.python.org/pypi>Python package repository</a>. | |
| 2396 </p> | |
| 2397 | |
| 2398 <hr> | |
| 2399 | |
| 2400 </td> | |
| 2401 </tr> | |
| 2402 </table> | |
| 2403 </center> | |
| 2404 </body> | |
| 2405 </html> | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 1493973002:
Remove telemetry/third_party/gsutilz (Closed)
Base URL: https://chromium.googlesource.com/chromium/src.git@gsutil_changes