scalar.html 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794
  1. <html>
  2. <title>
  3. PyASN1 data model and scalar types
  4. </title>
  5. <head>
  6. </head>
  7. <body>
  8. <center>
  9. <table width=60%>
  10. <tr>
  11. <td>
  12. <h3>
  13. 1. Data model for ASN.1 types
  14. </h3>
  15. <p>
  16. All ASN.1 types could be categorized into two groups: scalar (also called
  17. simple or primitive) and constructed. The first group is populated by
  18. well-known types like Integer or String. Members of constructed group
  19. hold other types (simple or constructed) as their inner components, thus
  20. they are semantically close to a programming language records or lists.
  21. </p>
  22. <p>
  23. In pyasn1, all ASN.1 types and values are implemented as Python objects.
  24. The same pyasn1 object can represent either ASN.1 type and/or value
  25. depending of the presense of value initializer on object instantiation.
  26. We will further refer to these as <i>pyasn1 type object</i> versus <i>pyasn1
  27. value object</i>.
  28. </p>
  29. <p>
  30. Primitive ASN.1 types are implemented as immutable scalar objects. There values
  31. could be used just like corresponding native Python values (integers,
  32. strings/bytes etc) and freely mixed with them in expressions.
  33. </p>
  34. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  35. <pre>
  36. >>> from pyasn1.type import univ
  37. >>> asn1IntegerValue = univ.Integer(12)
  38. >>> asn1IntegerValue - 2
  39. 10
  40. >>> univ.OctetString('abc') == 'abc'
  41. True # Python 2
  42. >>> univ.OctetString(b'abc') == b'abc'
  43. True # Python 3
  44. </pre>
  45. </td></tr></table>
  46. <p>
  47. It would be an error to perform an operation on a pyasn1 type object
  48. as it holds no value to deal with:
  49. </p>
  50. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  51. <pre>
  52. >>> from pyasn1.type import univ
  53. >>> asn1IntegerType = univ.Integer()
  54. >>> asn1IntegerType - 2
  55. ...
  56. pyasn1.error.PyAsn1Error: No value for __coerce__()
  57. </pre>
  58. </td></tr></table>
  59. <a name="1.1"></a>
  60. <h4>
  61. 1.1 Scalar types
  62. </h4>
  63. <p>
  64. In the sub-sections that follow we will explain pyasn1 mapping to those
  65. primitive ASN.1 types. Both, ASN.1 notation and corresponding pyasn1
  66. syntax will be given in each case.
  67. </p>
  68. <a name="1.1.1"></a>
  69. <h4>
  70. 1.1.1 Boolean type
  71. </h4>
  72. <p>
  73. This is the simplest type those values could be either True or False.
  74. </p>
  75. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  76. <pre>
  77. ;; type specification
  78. FunFactorPresent ::= BOOLEAN
  79. ;; values declaration and assignment
  80. pythonFunFactor FunFactorPresent ::= TRUE
  81. cobolFunFactor FunFactorPresent :: FALSE
  82. </pre>
  83. </td></tr></table>
  84. <p>
  85. And here's pyasn1 version of it:
  86. </p>
  87. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  88. <pre>
  89. >>> from pyasn1.type import univ
  90. >>> class FunFactorPresent(univ.Boolean): pass
  91. ...
  92. >>> pythonFunFactor = FunFactorPresent(True)
  93. >>> cobolFunFactor = FunFactorPresent(False)
  94. >>> pythonFunFactor
  95. FunFactorPresent('True(1)')
  96. >>> cobolFunFactor
  97. FunFactorPresent('False(0)')
  98. >>> pythonFunFactor == cobolFunFactor
  99. False
  100. >>>
  101. </pre>
  102. </td></tr></table>
  103. <a name="1.1.2"></a>
  104. <h4>
  105. 1.1.2 Null type
  106. </h4>
  107. <p>
  108. The NULL type is sometimes used to express the absense of any information.
  109. </p>
  110. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  111. <pre>
  112. ;; type specification
  113. Vote ::= CHOICE {
  114. agreed BOOLEAN,
  115. skip NULL
  116. }
  117. </td></tr></table>
  118. ;; value declaration and assignment
  119. myVote Vote ::= skip:NULL
  120. </pre>
  121. <p>
  122. We will explain the CHOICE type later in this paper, meanwhile the NULL
  123. type:
  124. </p>
  125. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  126. <pre>
  127. >>> from pyasn1.type import univ
  128. >>> skip = univ.Null()
  129. >>> skip
  130. Null('')
  131. >>>
  132. </pre>
  133. </td></tr></table>
  134. <a name="1.1.3"></a>
  135. <h4>
  136. 1.1.3 Integer type
  137. </h4>
  138. <p>
  139. ASN.1 defines the values of Integer type as negative or positive of whatever
  140. length. This definition plays nicely with Python as the latter places no
  141. limit on Integers. However, some ASN.1 implementations may impose certain
  142. limits of integer value ranges. Keep that in mind when designing new
  143. data structures.
  144. </p>
  145. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  146. <pre>
  147. ;; values specification
  148. age-of-universe INTEGER ::= 13750000000
  149. mean-martian-surface-temperature INTEGER ::= -63
  150. </pre>
  151. </td></tr></table>
  152. <p>
  153. A rather strigntforward mapping into pyasn1:
  154. </p>
  155. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  156. <pre>
  157. >>> from pyasn1.type import univ
  158. >>> ageOfUniverse = univ.Integer(13750000000)
  159. >>> ageOfUniverse
  160. Integer(13750000000)
  161. >>>
  162. >>> meanMartianSurfaceTemperature = univ.Integer(-63)
  163. >>> meanMartianSurfaceTemperature
  164. Integer(-63)
  165. >>>
  166. </pre>
  167. </td></tr></table>
  168. <p>
  169. ASN.1 allows to assign human-friendly names to particular values of
  170. an INTEGER type.
  171. </p>
  172. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  173. <pre>
  174. Temperature ::= INTEGER {
  175. freezing(0),
  176. boiling(100)
  177. }
  178. </pre>
  179. </td></tr></table>
  180. <p>
  181. The Temperature type expressed in pyasn1:
  182. </p>
  183. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  184. <pre>
  185. >>> from pyasn1.type import univ, namedval
  186. >>> class Temperature(univ.Integer):
  187. ... namedValues = namedval.NamedValues(('freezing', 0), ('boiling', 100))
  188. ...
  189. >>> t = Temperature(0)
  190. >>> t
  191. Temperature('freezing(0)')
  192. >>> t + 1
  193. Temperature(1)
  194. >>> t + 100
  195. Temperature('boiling(100)')
  196. >>> t = Temperature('boiling')
  197. >>> t
  198. Temperature('boiling(100)')
  199. >>> Temperature('boiling') / 2
  200. Temperature(50)
  201. >>> -1 < Temperature('freezing')
  202. True
  203. >>> 47 > Temperature('boiling')
  204. False
  205. >>>
  206. </pre>
  207. </td></tr></table>
  208. <p>
  209. These values labels have no effect on Integer type operations, any value
  210. still could be assigned to a type (information on value constraints will
  211. follow further in this paper).
  212. </p>
  213. <a name="1.1.4"></a>
  214. <h4>
  215. 1.1.4 Enumerated type
  216. </h4>
  217. <p>
  218. ASN.1 Enumerated type differs from an Integer type in a number of ways.
  219. Most important is that its instance can only hold a value that belongs
  220. to a set of values specified on type declaration.
  221. </p>
  222. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  223. <pre>
  224. error-status ::= ENUMERATED {
  225. no-error(0),
  226. authentication-error(10),
  227. authorization-error(20),
  228. general-failure(51)
  229. }
  230. </pre>
  231. </td></tr></table>
  232. <p>
  233. When constructing Enumerated type we will use two pyasn1 features: values
  234. labels (as mentioned above) and value constraint (will be described in
  235. more details later on).
  236. </p>
  237. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  238. <pre>
  239. >>> from pyasn1.type import univ, namedval, constraint
  240. >>> class ErrorStatus(univ.Enumerated):
  241. ... namedValues = namedval.NamedValues(
  242. ... ('no-error', 0),
  243. ... ('authentication-error', 10),
  244. ... ('authorization-error', 20),
  245. ... ('general-failure', 51)
  246. ... )
  247. ... subtypeSpec = univ.Enumerated.subtypeSpec + \
  248. ... constraint.SingleValueConstraint(0, 10, 20, 51)
  249. ...
  250. >>> errorStatus = univ.ErrorStatus('no-error')
  251. >>> errorStatus
  252. ErrorStatus('no-error(0)')
  253. >>> errorStatus == univ.ErrorStatus('general-failure')
  254. False
  255. >>> univ.ErrorStatus('non-existing-state')
  256. Traceback (most recent call last):
  257. ...
  258. pyasn1.error.PyAsn1Error: Can't coerce non-existing-state into integer
  259. >>>
  260. </pre>
  261. </td></tr></table>
  262. <p>
  263. Particular integer values associated with Enumerated value states
  264. have no meaning. They should not be used as such or in any kind of
  265. math operation. Those integer values are only used by codecs to
  266. transfer state from one entity to another.
  267. </p>
  268. <a name="1.1.5"></a>
  269. <h4>
  270. 1.1.5 Real type
  271. </h4>
  272. <p>
  273. Values of the Real type are a three-component tuple of mantissa, base and
  274. exponent. All three are integers.
  275. </p>
  276. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  277. <pre>
  278. pi ::= REAL { mantissa 314159, base 10, exponent -5 }
  279. </pre>
  280. </td></tr></table>
  281. <p>
  282. Corresponding pyasn1 objects can be initialized with either a three-component
  283. tuple or a Python float. Infinite values could be expressed in a way,
  284. compatible with Python float type.
  285. </p>
  286. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  287. <pre>
  288. >>> from pyasn1.type import univ
  289. >>> pi = univ.Real((314159, 10, -5))
  290. >>> pi
  291. Real((314159, 10,-5))
  292. >>> float(pi)
  293. 3.14159
  294. >>> pi == univ.Real(3.14159)
  295. True
  296. >>> univ.Real('inf')
  297. Real('inf')
  298. >>> univ.Real('-inf') == float('-inf')
  299. True
  300. >>>
  301. </pre>
  302. </td></tr></table>
  303. <p>
  304. If a Real object is initialized from a Python float or yielded by a math
  305. operation, the base is set to decimal 10 (what affects encoding).
  306. </p>
  307. <a name="1.1.6"></a>
  308. <h4>
  309. 1.1.6 Bit string type
  310. </h4>
  311. <p>
  312. ASN.1 BIT STRING type holds opaque binary data of an arbitrarily length.
  313. A BIT STRING value could be initialized by either a binary (base 2) or
  314. hex (base 16) value.
  315. </p>
  316. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  317. <pre>
  318. public-key BIT STRING ::= '1010111011110001010110101101101
  319. 1011000101010000010110101100010
  320. 0110101010000111101010111111110'B
  321. signature BIT STRING ::= 'AF01330CD932093392100B39FF00DE0'H
  322. </pre>
  323. </td></tr></table>
  324. <p>
  325. The pyasn1 BitString objects can initialize from native ASN.1 notation
  326. (base 2 or base 16 strings) or from a Python tuple of binary components.
  327. </p>
  328. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  329. <pre>
  330. >>> from pyasn1.type import univ
  331. >>> publicKey = univ.BitString(
  332. ... "'1010111011110001010110101101101"
  333. ... "1011000101010000010110101100010"
  334. ... "0110101010000111101010111111110'B"
  335. )
  336. >>> publicKey
  337. BitString("'10101110111100010101101011011011011000101010000010110101100010\
  338. 0110101010000111101010111111110'B")
  339. >>> signature = univ.BitString(
  340. ... "'AF01330CD932093392100B39FF00DE0'H"
  341. ... )
  342. >>> signature
  343. BitString("'101011110000000100110011000011001101100100110010000010010011001\
  344. 1100100100001000000001011001110011111111100000000110111100000'B")
  345. >>> fingerprint = univ.BitString(
  346. ... (1, 0, 1, 1 ,0, 1, 1, 1, 0, 1, 0, 1)
  347. ... )
  348. >>> fingerprint
  349. BitString("'101101110101'B")
  350. >>>
  351. </pre>
  352. </td></tr></table>
  353. <p>
  354. Another BIT STRING initialization method supported by ASN.1 notation
  355. is to specify only 1-th bits along with their human-friendly label
  356. and bit offset relative to the beginning of the bit string. With this
  357. method, all not explicitly mentioned bits are doomed to be zeros.
  358. </p>
  359. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  360. <pre>
  361. bit-mask BIT STRING ::= {
  362. read-flag(0),
  363. write-flag(2),
  364. run-flag(4)
  365. }
  366. </pre>
  367. </td></tr></table>
  368. <p>
  369. To express this in pyasn1, we will employ the named values feature (as with
  370. Enumeration type).
  371. </p>
  372. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  373. <pre>
  374. >>> from pyasn1.type import univ, namedval
  375. >>> class BitMask(univ.BitString):
  376. ... namedValues = namedval.NamedValues(
  377. ... ('read-flag', 0),
  378. ... ('write-flag', 2),
  379. ... ('run-flag', 4)
  380. ... )
  381. >>> bitMask = BitMask('read-flag,run-flag')
  382. >>> bitMask
  383. BitMask("'10001'B")
  384. >>> tuple(bitMask)
  385. (1, 0, 0, 0, 1)
  386. >>> bitMask[4]
  387. 1
  388. >>>
  389. </pre>
  390. </td></tr></table>
  391. <p>
  392. The BitString objects mimic the properties of Python tuple type in part
  393. of immutable sequence object protocol support.
  394. </p>
  395. <a name="1.1.7"></a>
  396. <h4>
  397. 1.1.7 OctetString type
  398. </h4>
  399. <p>
  400. The OCTET STRING type is a confusing subject. According to ASN.1
  401. specification, this type is similar to BIT STRING, the major difference
  402. is that the former operates in 8-bit chunks of data. What is important
  403. to note, is that OCTET STRING was NOT designed to handle text strings - the
  404. standard provides many other types specialized for text content. For that
  405. reason, ASN.1 forbids to initialize OCTET STRING values with "quoted text
  406. strings", only binary or hex initializers, similar to BIT STRING ones,
  407. are allowed.
  408. </p>
  409. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  410. <pre>
  411. thumbnail OCTET STRING ::= '1000010111101110101111000000111011'B
  412. thumbnail OCTET STRING ::= 'FA9823C43E43510DE3422'H
  413. </pre>
  414. </td></tr></table>
  415. <p>
  416. However, ASN.1 users (e.g. protocols designers) seem to ignore the original
  417. purpose of the OCTET STRING type - they used it for handling all kinds of
  418. data, including text strings.
  419. </p>
  420. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  421. <pre>
  422. welcome-message OCTET STRING ::= "Welcome to ASN.1 wilderness!"
  423. </pre>
  424. </td></tr></table>
  425. <p>
  426. In pyasn1, we have taken a liberal approach and allowed both BIT STRING
  427. style and quoted text initializers for the OctetString objects. To avoid
  428. possible collisions, quoted text is the default initialization syntax.
  429. </p>
  430. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  431. <pre>
  432. >>> from pyasn1.type import univ
  433. >>> thumbnail = univ.OctetString(
  434. ... binValue='1000010111101110101111000000111011'
  435. ... )
  436. >>> thumbnail
  437. OctetString(hexValue='85eebcec0')
  438. >>> thumbnail = univ.OctetString(
  439. ... hexValue='FA9823C43E43510DE3422'
  440. ... )
  441. >>> thumbnail
  442. OctetString(hexValue='fa9823c43e4351de34220')
  443. >>>
  444. </pre>
  445. </td></tr></table>
  446. <p>
  447. Most frequent usage of the OctetString class is to instantiate it with
  448. a text string.
  449. </p>
  450. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  451. <pre>
  452. >>> from pyasn1.type import univ
  453. >>> welcomeMessage = univ.OctetString('Welcome to ASN.1 wilderness!')
  454. >>> welcomeMessage
  455. OctetString(b'Welcome to ASN.1 wilderness!')
  456. >>> print('%s' % welcomeMessage)
  457. Welcome to ASN.1 wilderness!
  458. >>> welcomeMessage[11:16]
  459. OctetString(b'ASN.1')
  460. >>>
  461. </pre>
  462. </td></tr></table>
  463. <p>
  464. OctetString objects support the immutable sequence object protocol.
  465. In other words, they behave like Python 3 bytes (or Python 2 strings).
  466. </p>
  467. <p>
  468. When running pyasn1 on Python 3, it's better to use the bytes objects for
  469. OctetString instantiation, as it's more reliable and efficient.
  470. </p>
  471. <p>
  472. Additionally, OctetString's can also be instantiated with a sequence of
  473. 8-bit integers (ASCII codes).
  474. </p>
  475. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  476. <pre>
  477. >>> univ.OctetString((77, 101, 101, 103, 111))
  478. OctetString(b'Meego')
  479. </pre>
  480. </td></tr></table>
  481. <p>
  482. It is sometimes convenient to express OctetString instances as 8-bit
  483. characters (Python 3 bytes or Python 2 strings) or 8-bit integers.
  484. </p>
  485. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  486. <pre>
  487. >>> octetString = univ.OctetString('ABCDEF')
  488. >>> octetString.asNumbers()
  489. (65, 66, 67, 68, 69, 70)
  490. >>> octetString.asOctets()
  491. b'ABCDEF'
  492. </pre>
  493. </td></tr></table>
  494. <a name="1.1.8"></a>
  495. <h4>
  496. 1.1.8 ObjectIdentifier type
  497. </h4>
  498. <p>
  499. Values of the OBJECT IDENTIFIER type are sequences of integers that could
  500. be used to identify virtually anything in the world. Various ASN.1-based
  501. protocols employ OBJECT IDENTIFIERs for their own identification needs.
  502. </p>
  503. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  504. <pre>
  505. internet-id OBJECT IDENTIFIER ::= {
  506. iso(1) identified-organization(3) dod(6) internet(1)
  507. }
  508. </pre>
  509. </td></tr></table>
  510. <p>
  511. One of the natural ways to map OBJECT IDENTIFIER type into a Python
  512. one is to use Python tuples of integers. So this approach is taken by
  513. pyasn1.
  514. </p>
  515. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  516. <pre>
  517. >>> from pyasn1.type import univ
  518. >>> internetId = univ.ObjectIdentifier((1, 3, 6, 1))
  519. >>> internetId
  520. ObjectIdentifier('1.3.6.1')
  521. >>> internetId[2]
  522. 6
  523. >>> internetId[1:3]
  524. ObjectIdentifier('3.6')
  525. </pre>
  526. </td></tr></table>
  527. <p>
  528. A more human-friendly "dotted" notation is also supported.
  529. </p>
  530. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  531. <pre>
  532. >>> from pyasn1.type import univ
  533. >>> univ.ObjectIdentifier('1.3.6.1')
  534. ObjectIdentifier('1.3.6.1')
  535. </pre>
  536. </td></tr></table>
  537. <p>
  538. Symbolic names of the arcs of object identifier, sometimes present in
  539. ASN.1 specifications, are not preserved and used in pyasn1 objects.
  540. </p>
  541. <p>
  542. The ObjectIdentifier objects mimic the properties of Python tuple type in
  543. part of immutable sequence object protocol support.
  544. </p>
  545. <a name="1.1.9"></a>
  546. <h4>
  547. 1.1.9 Character string types
  548. </h4>
  549. <p>
  550. ASN.1 standard introduces a diverse set of text-specific types. All of them
  551. were designed to handle various types of characters. Some of these types seem
  552. be obsolete nowdays, as their target technologies are gone. Another issue
  553. to be aware of is that raw OCTET STRING type is sometimes used in practice
  554. by ASN.1 users instead of specialized character string types, despite
  555. explicit prohibition imposed by ASN.1 specification.
  556. </p>
  557. <p>
  558. The two types are specific to ASN.1 are NumericString and PrintableString.
  559. </p>
  560. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  561. <pre>
  562. welcome-message ::= PrintableString {
  563. "Welcome to ASN.1 text types"
  564. }
  565. dial-pad-numbers ::= NumericString {
  566. "0", "1", "2", "3", "4", "5", "6", "7", "8", "9"
  567. }
  568. </pre>
  569. </td></tr></table>
  570. <p>
  571. Their pyasn1 implementations are:
  572. </p>
  573. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  574. <pre>
  575. >>> from pyasn1.type import char
  576. >>> '%s' % char.PrintableString("Welcome to ASN.1 text types")
  577. 'Welcome to ASN.1 text types'
  578. >>> dialPadNumbers = char.NumericString(
  579. "0" "1" "2" "3" "4" "5" "6" "7" "8" "9"
  580. )
  581. >>> dialPadNumbers
  582. NumericString(b'0123456789')
  583. >>>
  584. </pre>
  585. </td></tr></table>
  586. <p>
  587. The following types came to ASN.1 from ISO standards on character sets.
  588. </p>
  589. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  590. <pre>
  591. >>> from pyasn1.type import char
  592. >>> char.VisibleString("abc")
  593. VisibleString(b'abc')
  594. >>> char.IA5String('abc')
  595. IA5String(b'abc')
  596. >>> char.TeletexString('abc')
  597. TeletexString(b'abc')
  598. >>> char.VideotexString('abc')
  599. VideotexString(b'abc')
  600. >>> char.GraphicString('abc')
  601. GraphicString(b'abc')
  602. >>> char.GeneralString('abc')
  603. GeneralString(b'abc')
  604. >>>
  605. </pre>
  606. </td></tr></table>
  607. <p>
  608. The last three types are relatively recent addition to the family of
  609. character string types: UniversalString, BMPString, UTF8String.
  610. </p>
  611. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  612. <pre>
  613. >>> from pyasn1.type import char
  614. >>> char.UniversalString("abc")
  615. UniversalString(b'abc')
  616. >>> char.BMPString('abc')
  617. BMPString(b'abc')
  618. >>> char.UTF8String('abc')
  619. UTF8String(b'abc')
  620. >>> utf8String = char.UTF8String('У попа была собака')
  621. >>> utf8String
  622. UTF8String(b'\xd0\xa3 \xd0\xbf\xd0\xbe\xd0\xbf\xd0\xb0 \xd0\xb1\xd1\x8b\xd0\xbb\xd0\xb0 \
  623. \xd1\x81\xd0\xbe\xd0\xb1\xd0\xb0\xd0\xba\xd0\xb0')
  624. >>> print(utf8String)
  625. У попа была собака
  626. >>>
  627. </pre>
  628. </td></tr></table>
  629. <p>
  630. In pyasn1, all character type objects behave like Python strings. None of
  631. them is currently constrained in terms of valid alphabet so it's up to
  632. the data source to keep an eye on data validation for these types.
  633. </p>
  634. <a name="1.1.10"></a>
  635. <h4>
  636. 1.1.10 Useful types
  637. </h4>
  638. <p>
  639. There are three so-called useful types defined in the standard:
  640. ObjectDescriptor, GeneralizedTime, UTCTime. They all are subtypes
  641. of GraphicString or VisibleString types therefore useful types are
  642. character string types.
  643. </p>
  644. <p>
  645. It's advised by the ASN.1 standard to have an instance of ObjectDescriptor
  646. type holding a human-readable description of corresponding instance of
  647. OBJECT IDENTIFIER type. There are no formal linkage between these instances
  648. and provision for ObjectDescriptor uniqueness in the standard.
  649. </p>
  650. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  651. <pre>
  652. >>> from pyasn1.type import useful
  653. >>> descrBER = useful.ObjectDescriptor(
  654. "Basic encoding of a single ASN.1 type"
  655. )
  656. >>>
  657. </pre>
  658. </td></tr></table>
  659. <p>
  660. GeneralizedTime and UTCTime types are designed to hold a human-readable
  661. timestamp in a universal and unambiguous form. The former provides
  662. more flexibility in notation while the latter is more strict but has
  663. Y2K issues.
  664. </p>
  665. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  666. <pre>
  667. ;; Mar 8 2010 12:00:00 MSK
  668. moscow-time GeneralizedTime ::= "20110308120000.0"
  669. ;; Mar 8 2010 12:00:00 UTC
  670. utc-time GeneralizedTime ::= "201103081200Z"
  671. ;; Mar 8 1999 12:00:00 UTC
  672. utc-time UTCTime ::= "9803081200Z"
  673. </pre>
  674. </td></tr></table>
  675. <table bgcolor="lightgray" border=0 width=100%><TR><TD>
  676. <pre>
  677. >>> from pyasn1.type import useful
  678. >>> moscowTime = useful.GeneralizedTime("20110308120000.0")
  679. >>> utcTime = useful.UTCTime("9803081200Z")
  680. >>>
  681. </pre>
  682. </td></tr></table>
  683. <p>
  684. Despite their intended use, these types possess no special, time-related,
  685. handling in pyasn1. They are just printable strings.
  686. </p>
  687. <hr>
  688. </td>
  689. </tr>
  690. </table>
  691. </center>
  692. </body>
  693. </html>