idnits 2.17.1 draft-ietf-pkix-asn1-translation-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 366: '... signedAttrs [0] IMPLICIT SignedAttributes OPTIONAL,...' RFC 2119 keyword, line 370: '... {{UnsignedAttributes}} OPTIONAL }...' RFC 2119 keyword, line 448: '...s({AlgorithmSet}{@algorithm}) OPTIONAL...' RFC 2119 keyword, line 567: '... ({AlgorithmSet}{@algorithm}) OPTIONAL...' RFC 2119 keyword, line 572: '... &Params OPTIONAL,...' (10 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (August 26, 2010) is 4986 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '0' on line 650 -- Looks like a reference, but probably isn't: '1' on line 660 -- Looks like a reference, but probably isn't: '2' on line 661 -- Looks like a reference, but probably isn't: '3' on line 664 -- Obsolete informational reference (is this intentional?): RFC 2560 (Obsoleted by RFC 6960) -- Obsolete informational reference (is this intentional?): RFC 3852 (Obsoleted by RFC 5652) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Wallace 3 Internet-Draft Cygnacom Solutions 4 Intended status: Informational C. Gardiner 5 Expires: February 27, 2011 BBN Technologies 6 August 26, 2010 8 ASN.1 Translation 9 draft-ietf-pkix-asn1-translation-03 11 Abstract 13 Abstract Syntax Notation One (ASN.1) is widely used throughout the 14 IETF security area and has been for many years. Some specifications 15 were written using a now deprecated version of ASN.1 and some were 16 written using the current version of ASN.1. Not all ASN.1 compilers 17 support both older and current syntax. This document is intended to 18 provide guidance to specification authors and to implementers 19 converting ASN.1 modules written using one version of ASN.1 to 20 another version without causing changes to the "bits on the wire". 21 This document does not provide a comprehensive tutorial of any 22 version of ASN.1. Instead, it addresses ASN.1 features that are used 23 in IETF security area specifications with focus on items that vary 24 with the ASN.1 version. 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on February 27, 2011. 43 Copyright Notice 45 Copyright (c) 2010 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. ASN.1 design elements . . . . . . . . . . . . . . . . . . . . 4 63 2.1. Open types . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2.1.1. ANY DEFINED BY . . . . . . . . . . . . . . . . . . . . 4 65 2.1.2. OCTET STRINGs and BIT STRINGs . . . . . . . . . . . . 5 66 2.1.3. Information Object Classes . . . . . . . . . . . . . . 6 67 2.2. Constraints . . . . . . . . . . . . . . . . . . . . . . . 8 68 2.2.1. Simple table constraints . . . . . . . . . . . . . . . 9 69 2.2.2. Component relation constraints . . . . . . . . . . . . 9 70 2.2.3. Content constraints . . . . . . . . . . . . . . . . . 12 71 2.3. Parameterization . . . . . . . . . . . . . . . . . . . . . 13 72 2.4. Versioning and Extensibility . . . . . . . . . . . . . . . 15 73 2.4.1. Extension markers . . . . . . . . . . . . . . . . . . 15 74 2.4.2. Version brackets . . . . . . . . . . . . . . . . . . . 15 75 3. Character set differences . . . . . . . . . . . . . . . . . . 17 76 4. ASN.1 translation . . . . . . . . . . . . . . . . . . . . . . 18 77 4.1. Downgrading from X.68x to X.208 . . . . . . . . . . . . . 18 78 4.2. Upgrading from X.208 to X.68x . . . . . . . . . . . . . . 18 79 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 80 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 81 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 22 82 7.1. Normative References . . . . . . . . . . . . . . . . . . . 22 83 7.2. Informative References . . . . . . . . . . . . . . . . . . 22 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 24 86 1. Introduction 88 This document is intended to serve as a tutorial for converting ASN.1 89 modules written using [CCITT.X208.1988] to [CCITT.X680.2002], or vice 90 versa. Preparation of this document was motivated by 91 [I-D.ietf-pkix-new-asn1] and [I-D.ietf-smime-new-asn1], which provide 92 updated ASN.1 modules for a number of RFCs. 94 The intent of this specification is to assist with translation of 95 ASN.1 from one version to another without resulting in any changes to 96 the encoded results when using the Basic Encoding Rules or 97 Distinguished Encoding Rules [CCITT.X209.1988][CCITT.X690.2002]. 98 Other encoding rules were not considered. 100 Transforming a new ASN.1 module to an older ASN.1 module can be 101 performed in a fairly mechanical manner, much of the transformation 102 consists of deleting new constructs. Transforming an older ASN.1 103 module to a newer ASN.1 module can also be done fairly mechanically, 104 if one does not wish to move many of the constraints that are 105 contained in the prose into the ASN.1 module. If the constraints are 106 to be added, then the conversion can be a complex process. 108 1.1. Terminology 110 This document addresses two different versions of ASN.1. The old 111 (1988) version was defined in a single document (X.208) and the newer 112 (1998, 2002) version is defined in a series of documents (X.680, 113 X.681, X.682 and X.683). For convenience, the series of documents is 114 henceforth referred to as X.68x. Specific documents from the series 115 are referenced by name where appropriate. 117 2. ASN.1 design elements 119 When translating an ASN.1 module from X.208 syntax to X.68x syntax, 120 or vice versa, many definitions do not require or benefit from 121 change. Review of the original ASN.1 modules updated by 122 [I-D.ietf-pkix-new-asn1] and [I-D.ietf-smime-new-asn1] and the 123 revised modules included in those documents indicates that most 124 changes can be sorted into one of a few categories. This section 125 describes these categories. 127 2.1. Open types 129 Protocols often feature flexible designs that enable other (later) 130 specifications to define the syntax and semantics of some features. 131 For example, [RFC5280] includes the definition of the Extension 132 structure. There are many instances of extensions defined in other 133 specifications. Several mechanisms are available in X.208, X.68x or 134 both to accommodate this practice, as described below. 136 2.1.1. ANY DEFINED BY 138 X.208 defines the ANY DEFINED BY production for specifying open 139 types. This typically appears in a SEQUENCE along with an OBJECT 140 IDENTIFIER that indicates the type of object that is encoded. The 141 ContentInfo structure, shown below from [RFC3852], uses ANY DEFINED 142 BY along with an OBJECT IDENTIFIER field to identify and convey 143 arbitrary types of data. Each content type to be wrapped in a 144 ContentInfo is assigned a unique OBJECT IDENTIFIER, such as the id- 145 signedData shown below. However, X.208 does not provide a formal 146 means for establishing a relationship between a type and the type 147 identifier. Any associations are done in the comments of the module 148 and/or the text of the associated document. 150 -- from RFC 3852 151 ContentInfo ::= SEQUENCE { 152 contentType ContentType, 153 content [0] EXPLICIT ANY DEFINED BY contentType } 155 ContentType ::= OBJECT IDENTIFIER 157 id-signedData OBJECT IDENTIFIER ::= { iso(1) member-body(2) 158 us(840) rsadsi(113549) pkcs(1) pkcs7(7) 2 } 160 ANY DEFINED BY may also appear using an INTEGER to indicate the type 161 of object that is encoded, as shown in the following example from 162 [RFC5280]. 164 -- from RFC 5280 165 ExtensionAttribute ::= SEQUENCE { 166 extension-attribute-type [0] IMPLICIT INTEGER 167 (0..ub-extension-attributes), 168 extension-attribute-value [1] 169 ANY DEFINED BY extension-attribute-type } 171 Though the usage of ANY DEFINED BY was deprecated in 1994, it appears 172 in some active specifications. The AttributeValue definition in 173 [RFC5280] uses ANY with a DEFINED BY comment to bind the value to a 174 type identifier field. 176 -- from RFC 5280 177 AttributeTypeAndValue ::= SEQUENCE { 178 type AttributeType, 179 value AttributeValue } 181 AttributeType ::= OBJECT IDENTIFIER 183 AttributeValue ::= ANY -- DEFINED BY AttributeType 185 2.1.2. OCTET STRINGs and BIT STRINGs 187 Both X.208 and X.68x allow open types to be implemented using OCTET 188 STRINGs and BIT STRINGs as containers. The definitions of Extension 189 and SubjectPublicKeyInfo in [RFC5280] demonstrate the usage of OCTET 190 STRING and BIT STRING, respectively, to convey information that is 191 further defined using ASN.1. 193 -- from RFC 5280 194 Extension ::= SEQUENCE { 195 extnID OBJECT IDENTIFIER, 196 critical BOOLEAN DEFAULT FALSE, 197 extnValue OCTET STRING 198 -- contains the DER encoding of an ASN.1 value 199 -- corresponding to the extension type identified 200 -- by extnID 201 } 203 SubjectPublicKeyInfo ::= SEQUENCE { 204 algorithm AlgorithmIdentifier, 205 subjectPublicKey BIT STRING } 207 In both cases, the prose of the specification indicates that the 208 adjacent OBJECT IDENTIFIER value indicates the type of structure 209 within the value of the primitive OCTET STRING or BIT STRING type. 210 For example, where an extnID field contains the value id-ce- 211 basicConstraints, the extnValue field contains an encoded 212 BasicConstraints as the value of the OCTET STRING, as shown in the 213 dump of an encoded extension below. 215 Tag Length Value 216 30 15: SEQUENCE { 217 06 3: OBJECT IDENTIFIER basicConstraints (2 5 29 19) 218 01 1: BOOLEAN TRUE 219 04 5: OCTET STRING, encapsulates { 220 30 3: SEQUENCE { 221 01 1: BOOLEAN TRUE 222 : } 223 : } 224 : } 226 2.1.3. Information Object Classes 228 Information object classes are defined in [CCITT.X681.2002]. Object 229 classes allow protocol designers to relate pieces of data that are in 230 some way associated. In the most generic of terms, an Information 231 Object class can be thought of as a database schema, with Information 232 Object Sets being instances of the databases. 234 Unlike type definitions, object classes with the same structure are 235 not equivalent. Thus if you have: 237 FOO ::= TYPE-IDENTIFIER 239 BAR ::= TYPE-IDENTIFIER 241 FOO and BAR are not interchangeable. 243 TYPE-IDENTIFIER is one of the predefined information object classes 244 in Annex A of [CCITT.X681.2002]. This provides for a simple mapping 245 from an OBJECT IDENTIFIER to a data type. The tag UNIQUE on &id 246 means that this value may appear only once in an Information Object 247 Set, however multiple objects can be defined with the same &id value. 249 [I-D.ietf-smime-new-asn1] uses the TYPE-IDENTIFIER construction to 250 update the definition of ContentInfo, as shown below. 252 -- TYPE-IDENTIFIER definition from X.681 253 TYPE-IDENTIFIER ::= CLASS 254 { 255 &id OBJECT IDENTIFIER UNIQUE, 256 &Type 257 } 258 WITH SYNTAX {&Type IDENTIFIED BY &id} 260 -- from updated RFC 3852 module in [I-D.ietf-smime-new-asn1] 261 CONTENT-TYPE ::= TYPE-IDENTIFIER 262 ContentType ::= CONTENT-TYPE.&id 264 ContentInfo ::= SEQUENCE { 265 contentType CONTENT-TYPE. 266 &id({ContentSet}), 267 content [0] EXPLICIT CONTENT-TYPE. 268 &Type({ContentSet}{@contentType})} 270 ContentSet CONTENT-TYPE ::= { 271 -- Define the set of content types to be recognized. 272 ct-Data | ct-SignedData | ct-EncryptedData | ct-EnvelopedData | 273 ct-AuthenticatedData | ct-DigestedData, ... } 275 -- other CONTENT-TYPE instances not shown for brevity 276 ct-SignedData CONTENT-TYPE ::= 277 { SignedData IDENTIFIED BY id-signedData} 279 This example illustrates the following: 281 o Definition of an information object class: TYPE-IDENITIFIER and 282 CONTENT-TYPE are information object classes. 284 o Definition of an information object, or an instance of an 285 information object class: ct-SignedData is an information object. 287 o Definition of an information object set: ContentSet is an 288 information object set. 290 o Usage of an information object: The definition of ContentInfo uses 291 information from the CONTENT-TYPE information object class. 293 o Defining constraints using an object set: Both the contentType and 294 content fields are constrained by ContentSet. 296 As noted above, TYPE-IDENTIFIER simply associates an OBJECT 297 IDENTIFIER with an arbitrary data type. CONTENT-TYPE is a TYPE- 298 IDENTIFIER. The WITH SYNTAX component allows for a more natural 299 language expression of information object definitions. 301 ct-SignedData is the name of an information object that associated 302 the identifier id-signedData with the data type SignedData. It is an 303 instance of the CONTENT-TYPE information object class. The &Type 304 field is assigned the value SignedData and the &id field is assigned 305 the value id-signedData. The example above uses the syntax provided 306 by the WITH SYNTAX component of the TYPE-IDENTIFIER definition. An 307 equivalent definition not using the provided syntax is as follows: 309 ct-SignedData CONTENT-TYPE ::= 310 { 311 &id id-signedData, 312 &Type SignedData 313 } 315 ContentSet is the name of a set of information objects derived from 316 the CONTENT-TYPE information object class. The set contains six 317 information objects and is extensible, as indicated by the ellipsis 318 (see the Versioning and Extensibility section below). 320 ContentInfo is defined using type information from an information 321 object, i.e., the type of the contentType field is that of the &id 322 field from CONTENT-TYPE. An equivalent definition is as follows: 324 ContentType ::= OBJECT IDENTIFIER 326 Both fields in ContentInfo are constrained. The contentType field is 327 constrained using a simple table constraint that restricts the values 328 to those from the corresponding field of the objects in ContentSet. 329 The content field is constrained using a component relationship 330 constraint. Constraints are discussed in the next section. 332 2.2. Constraints 334 The X.68x versions of the ASN.1 specifications introduced the ability 335 to use the object information sets as part of the constraint on the 336 values that a field can take. Simple table constraints are used to 337 restrict the set of values that can occur in a field. Component 338 relation constraints allow for the restriction of a field based on 339 contents of other fields in the type. 341 2.2.1. Simple table constraints 343 Simple table constraints are widely used in [I-D.ietf-pkix-new-asn1] 344 and [I-D.ietf-smime-new-asn1] to limit implementer options (although 345 the constraints are almost always followed by or include 346 extensibility markers making the parameters serve an informational 347 purpose not as a limitation). Table constraints are defined in 348 [CCITT.X682.2002]. 350 Some ASN.1 compilers have the ability to use the simple table 351 constraint to check that a field contains one of the legal values. 353 The following example from [I-D.ietf-smime-new-asn1] provides two 354 examples of using table constraints to clarify the intended usage of 355 a particular field. The parameters indicate the types of attributes 356 that are typically found in the signedAttrs and unsignedAttrs fields. 357 In this example, the object sets are disjoint but this is not 358 required. For example, in [I-D.ietf-pkix-new-asn1], there is some 359 overlap between the CertExtensions and CrlExtensions sets. 361 -- from updated RFC 3852 module in [I-D.ietf-smime-new-asn1] 362 SignerInfo ::= SEQUENCE { 363 version CMSVersion, 364 sid SignerIdentifier, 365 digestAlgorithm DigestAlgorithmIdentifier, 366 signedAttrs [0] IMPLICIT SignedAttributes OPTIONAL, 367 signatureAlgorithm SignatureAlgorithmIdentifier, 368 signature SignatureValue, 369 unsignedAttrs [1] IMPLICIT Attributes 370 {{UnsignedAttributes}} OPTIONAL } 372 SignedAttributes ::= Attributes {{ SignedAttributesSet }} 374 SignedAttributesSet ATTRIBUTE ::= 375 { aa-signingTime | aa-messageDigest | aa-contentType, ... } 377 UnsignedAttributes ATTRIBUTE ::= { aa-countersignature, ... } 379 2.2.2. Component relation constraints 381 Component relation constraints are often used to bind the type field 382 of an open type to the identifier field. Using the binding in this 383 way allows for a compiler to immediately decode the associated type 384 when the containing structure is defined. The following example from 385 [RFC2560] as updated [I-D.ietf-pkix-new-asn1] demonstrates this 386 usage. 388 -- from updated RFC 2560 module in [I-D.ietf-pkix-new-asn1] 389 RESPONSE ::= TYPE-IDENTIFIER 391 ResponseSet RESPONSE ::= {basicResponse, ...} 393 ResponseBytes ::= SEQUENCE { 394 responseType RESPONSE. 395 &id ({ResponseSet}), 396 response OCTET STRING (CONTAINING RESPONSE. 397 &Type({ResponseSet}{@responseType}))} 399 In this example, the response field is constrained to contain a type 400 identified by the responseType field. The controlling field is 401 identified using atNotation, e.g., "@responseType". atNotation can be 402 defined relative to the outermost SEQUENCE, SET or CHOICE or relative 403 to the field with which the atNotation is associated. When there is 404 no '.' immediately after the '@', the field appears as a member of 405 the outermost SEQUENCE, SET or CHOICE. When there is a '.' 406 immediately after the '@', each '.' represents a SEQUENCE, SET or 407 CHOICE starting with the SEQUENCE, SET or CHOICE that contains the 408 field with which the atNotation is associated. For example, 409 ResponseBytes could have been written as shown below. In this case, 410 the syntax is very similar since the innermost and outermost 411 SEQUENCE, SET or CHOICE are the same. 413 ResponseBytes ::= SEQUENCE { 414 responseType RESPONSE. 415 &id ({ResponseSet}), 416 response OCTET STRING (CONTAINING RESPONSE. 417 &Type({ResponseSet}{@.responseType}))} 419 The TaggedRequest example from [I-D.ietf-pkix-new-asn1] provides an 420 example where the outermost and innermost SEQUENCE, SET or CHOICE are 421 different. Relative to the atNotation included in the definition of 422 the requestMessageValue field, the outermost SEQUENCE, SET or CHOICE 423 is TaggedRequest and the innermost is the SEQUENCE used to define the 424 orm field. 426 TaggedRequest ::= CHOICE { 427 tcr [0] TaggedCertificationRequest, 428 crm [1] CertReqMsg, 429 orm [2] SEQUENCE { 430 bodyPartID BodyPartID, 431 requestMessageType OTHER-REQUEST.&id({OtherRequests}), 432 requestMessageValue OTHER-REQUEST.&Type({OtherRequests} 433 {@.requestMessageType}) 434 } 435 } 437 When referencing a field using atNotation, the definition of the 438 field must be included within the outermost SEQUENCE, SET or CHOICE. 439 References to fields within structures that are defined separately 440 are not allowed. For example, the following example includes invalid 441 atNotation in the definition of the signature field within the SIGNED 442 parameterized type. 444 AlgorithmIdentifier{ALGORITHM-TYPE, ALGORITHM-TYPE:AlgorithmSet} ::= 445 SEQUENCE { 446 algorithm ALGORITHM-TYPE.&id({AlgorithmSet}), 447 parameters ALGORITHM-TYPE. 448 &Params({AlgorithmSet}{@algorithm}) OPTIONAL 449 } 451 -- example containing invalid atNotation 452 SIGNED{ToBeSigned} ::= SEQUENCE { 453 toBeSigned ToBeSigned, 454 algorithmIdentifier AlgorithmIdentifier 455 { SIGNATURE-ALGORITHM, {...}} 456 }, 457 signature BIT STRING (CONTAINING SIGNATURE-ALGORITHM.&Value( 458 {SignatureAlgorithms} 459 {@algorithmIdentifier.algorithm})) 460 } 462 The above example could be alternatively written with correct 463 atNotation as follows, with the definition of the algorithm field 464 included within ToBeSigned. 466 SIGNED{ToBeSigned} ::= SEQUENCE { 467 toBeSigned ToBeSigned, 468 algorithmIdentifier SEQUENCE { 469 algorithm SIGNATURE-ALGORITHM. 470 &id({SignatureAlgorithms}), 471 parameters SIGNATURE-ALGORITHM. 472 &Params({SignatureAlgorithms} 473 {@algorithmIdentifier.algorithm}) 474 }, 475 signature BIT STRING (CONTAINING SIGNATURE-ALGORITHM.&Value( 476 {SignatureAlgorithms} 477 {@algorithmIdentifier.algorithm})) 478 } 480 In the above example, the outermost SEQUENCE, SET or CHOICE relative 481 to the parameters field is the SIGNED parameterized type. The 482 innermost structure is the SEQUENCE used as the type for the 483 algorithmIdentifier field. The atNotation for the parameters field 484 could be expressed using any of the following representations: 486 @algorithmIdentifier.algorithm 488 @.algorithm 490 The atNotation for the signature field has only one representation. 492 2.2.3. Content constraints 494 Open types implemented as OCTET STRINGs or BIT STRINGs can be 495 constrained using contents constraints syntax defined in 496 [CCITT.X682.2002]. Below are the revised definitions from 497 [I-D.ietf-pkix-new-asn1] and [I-D.ietf-smime-new-asn1]. These show 498 usage of OCTET STRING and BIT STRING along with constrained sets of 499 identifiers. The Extension definition uses a content constraint that 500 requires the value of the OCTET STRING to be an encoding the type 501 associated with the information object selected from the ExtensionSet 502 object set using the value of the extnID field. For reasons 503 described above in the "Component relation constraints" section, the 504 SubjectPublicKeyInfo definition relies on prose to bind the BIT 505 STRING to the type identifier because it is not possible to express a 506 content constraint that includes a component relationship constraint 507 to bind the type value within the algorithm field to the 508 subjectPublicKey field. 510 -- from updated RFC 5280 module in [I-D.ietf-pkix-new-asn1] 511 Extension{EXTENSION:ExtensionSet} ::= SEQUENCE { 512 extnID EXTENSION.&id({ExtensionSet}), 513 critical BOOLEAN 514 -- (EXTENSION.&Critical({ExtensionSet}{@extnID})) 515 DEFAULT FALSE, 516 extnValue OCTET STRING (CONTAINING 517 EXTENSION.&ExtnType({ExtensionSet}{@extnID})) 518 -- contains the DER encding of the ASN.1 value 519 -- corresponding to the extension type identified 520 -- by extnID 521 } 523 SubjectPublicKeyInfo ::= SEQUENCE { 524 algorithm AlgorithmIdentifier{PUBLIC-KEY, 525 {PublicKeyAlgorithms}}, 526 subjectPublicKey BIT STRING 527 } 529 2.3. Parameterization 531 Parameterization is defined in [CCITT.X683.2002] and can also be used 532 to define new types in a way similar to the macro notation described 533 in Annex A of X.208. The following example from 534 [I-D.ietf-pkix-new-asn1] shows this usage. The toBeSigned field 535 takes the type passed as a parameter. 537 -- from [I-D.ietf-pkix-new-asn1] 538 SIGNED{ToBeSigned} ::= SEQUENCE { 539 toBeSigned ToBeSigned, 540 algorithm AlgorithmIdentifier{SIGNATURE-ALGORITHM, 541 {SignatureAlgorithms}}, 542 signature BIT STRING 543 } 545 -- from updated RFC5280 module in [I-D.ietf-pkix-new-asn1] 546 Certificate ::= SIGNED{TBSCertificate} 548 Parameters need not be simple types. The following example 549 demonstrates the usage of an information object class and an 550 information object set as parameters. The first parameter in the 551 definition of AlgorithmIdentifier is an information object class. 552 Information object classes used for this parameter must have &id and 553 &Params fields, which determine the type of the algorithm and 554 parameters fields. Other fields may be present in the information 555 object class but they are not used by the definition of 556 AlgorithmIdentifier, as demonstrated by the SIGNATURE-ALGORITHM class 557 shown below. The second parameter is an information object set that 558 is used to constrain the values that appear in the algorithm and 559 parameters fields. 561 -- from [I-D.ietf-pkix-new-asn1] 562 AlgorithmIdentifier{ALGORITHM-TYPE, ALGORITHM-TYPE:AlgorithmSet} 563 ::= SEQUENCE 564 { 565 algorithm ALGORITHM-TYPE.&id({AlgorithmSet}), 566 parameters ALGORITHM-TYPE.&Params 567 ({AlgorithmSet}{@algorithm}) OPTIONAL 568 } 570 SIGNATURE-ALGORITHM ::= CLASS { 571 &id OBJECT IDENTIFIER, 572 &Params OPTIONAL, 573 &Value OPTIONAL, 574 ¶mPresence ParamOptions DEFAULT absent, 575 &HashSet DIGEST-ALGORITHM OPTIONAL, 576 &PublicKeySet PUBLIC-KEY OPTIONAL, 577 &smimeCaps SMIME-CAPS OPTIONAL 578 } WITH SYNTAX { 579 IDENTIFIER &id 580 [VALUE &Value] 581 [PARAMS [TYPE &Params] ARE ¶mPresence ] 582 [HASHES &HashSet] 583 [PUBLIC KEYS &PublicKeySet] 584 [SMIME CAPS &smimeCaps] 585 } 587 -- from updated RFC 2560 module in [I-D.ietf-pkix-new-asn1] 588 BasicOCSPResponse ::= SEQUENCE { 589 tbsResponseData ResponseData, 590 signatureAlgorithm AlgorithmIdentifier{SIGNATURE-ALGORITHM, 591 {sa-dsaWithSHA1 | sa-rsaWithSHA1 | 592 sa-rsaWithMD5 | sa-rsaWithMD2, ...}}, 593 signature BIT STRING, 594 certs [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL 595 } 597 2.4. Versioning and Extensibility 599 Specifications are often revised and ASN.1 modules updated to include 600 new components. [CCITT.X681.2002] provides two mechanisms useful in 601 supporting extensibility: extension markers and version brackets. 603 2.4.1. Extension markers 605 An extension marker is represented by an ellipsis (i.e., three 606 adjacent periods). Extension markers are included in specifications 607 at points where the protocol designer anticipates future changes. 608 This can also be achieved by including EXTENSIBILITY IMPLIED in the 609 ASN.1 module definition. EXTENSIBILITY IMPLIED is the equivalent to 610 including an extension marker in each type defined in the ASN.1 611 module. Extensibility markers are used throughout 612 [I-D.ietf-pkix-new-asn1] and [I-D.ietf-smime-new-asn1] where object 613 sets are defined. In other instances, the updated modules 614 retroactively added extension markers where fields were added to an 615 earlier version by an update, as shown in the CertificateChoices 616 example below. 618 Examples: 620 -- from updated RFC 3370 621 KeyAgreementAlgs KEY-AGREE ::= { kaa-esdh | kaa-ssdh, ...} 623 -- from updated RFC 3852 624 CertificateChoices ::= CHOICE { 625 certificate Certificate, 626 extendedCertificate [0] IMPLICIT ExtendedCertificate, 627 -- Obsolete 628 ..., 629 [[3: v1AttrCert [1] IMPLICIT AttributeCertificateV1]], 630 -- Obsolete 631 [[4: v2AttrCert [2] IMPLICIT AttributeCertificateV2]], 632 [[5: other [3] IMPLICIT OtherCertificateFormat]] 633 } 635 Protocol designers should use extension markers within definitions 636 that are likely to change. For example, extensibility markers should 637 be used when enumerating error values. 639 2.4.2. Version brackets 641 Version brackets can be used to indicate features that are available 642 in later versions of an ASN.1 module but not in earlier versions. 644 [I-D.ietf-pkix-new-asn1] added version brackets to the definition of 645 TBSCertificate to illustrate the addition of the issuerUniqueID, 646 subjectUniqueID and extensions fields, as shown below. 648 -- from updated RFC 5280 module in [I-D.ietf-pkix-new-asn1] 649 TBSCertificate ::= SEQUENCE { 650 version [0] Version DEFAULT v1, 651 serialNumber CertificateSerialNumber, 652 signature AlgorithmIdentifier{SIGNATURE-ALGORITHM, 653 {SignatureAlgorithms}}, 654 issuer Name, 655 validity Validity, 656 subject Name, 657 subjectPublicKeyInfo SubjectPublicKeyInfo, 658 ... , 659 [[2: -- If present, version MUST be v2 660 issuerUniqueID [1] IMPLICIT UniqueIdentifier OPTIONAL, 661 subjectUniqueID [2] IMPLICIT UniqueIdentifier OPTIONAL 662 ]], 663 [[3: -- If present, version MUST be v3 -- 664 extensions [3] ExtensionSet{{CertExtensions}} OPTIONAL 665 ]], ... } 667 3. Character set differences 669 X.68s uses a character set that is a superset of the character set 670 defined in X.208. The character set defined in X.208 includes the 671 following: 673 A to Z 675 a to z 677 0 to 9 679 :=,{}<. 681 ()[]-'" 683 The character set in X.68x additionally includes the following: 685 !&*/;>@^_| 687 The > and | characters can also be used in X.208 syntax in macro 688 definitions. 690 4. ASN.1 translation 692 4.1. Downgrading from X.68x to X.208 694 At a minimum, downgrading an ASN.1 module from X.68x syntax to X.208 695 requires the removal of features not supported by X.208. As 696 indicated above, the features most commonly used in IETF security 697 area ASN.1 modules are information object classes (and object sets), 698 content constraints, parameterization, version brackets and extension 699 markers. Extension markers and version brackets can simply be 700 deleted (or commented out). The definitions for information object 701 classes and object sets can also be deleted or commented out, as 702 these will not be used. The following checklist can be used in most 703 cases: 705 o Remove all Information Set Class, Information Set Object and 706 Information Set Object Set definitions and imports from the file. 708 o Replace all fixed Type Information Set Class element references 709 with the fixed type. (I.e. Replace FOO.&id with OBJECT 710 IDENTIFIER.) 712 o Delete all simple constraints. 714 o Delete all CONTAINING statements. 716 o Replace all variable Type Information Set Class element references 717 with either ANY or ANY DEFINED BY statements. 719 o Remove version and extension markers. 721 o Hand instantiate all instances of parameterized types. 723 4.2. Upgrading from X.208 to X.68x 725 The amount of change associated with upgrading from X.208 syntax to 726 X.68x syntax is dependent on the reasons for changing and personal 727 style. A minimalist approach could consist of altering any 728 deprecated features, most commonly ANY DEFINED BY, and adding any 729 necessary extensibility markers. A more comprehensive approach may 730 include of the introduction of constraints, parameterization, 731 versioning, extensibility, etc. 733 The following checklist can be used when upgrading a module without 734 introducing constraints: 736 Use TYPE-IDENTIFIER.&Type for "ANY". 738 Use TYPE-IDENTIFIER.&Type for "ANY DEFINED BY ...". 740 When constraints are introducing during an upgrade, additional steps 741 are necessary: 743 1. Identify each unique class that should be defined based on what 744 types of things exist. 746 2. Define an Information Object Class for each of the classes above 747 with the appropriate elements. 749 3. Define the all of appropriate Information Object Sets based on 750 the classes defined in step 2 along with the different places 751 that they should be used. 753 4. Replace ANY by the appropriate class and variable type element. 755 5. Replace ANY DEFINED BY with the appropriate variable type element 756 and the components constraint. Replace the element used in the 757 constraint with the appropriate fixed type element and simple 758 constraint. 760 6. Add any simple constraints as appropriate. 762 7. Define any objects and fill in elements for object sets as 763 appropriate. 765 5. IANA Considerations 767 There are no IANA considerations. Please delete this section prior 768 to RFC publication. 770 6. Security Considerations 772 Where a module is downgraded from X.68x syntax to X.208 there is loss 773 of potential automated enforcement of constraints expressed by the 774 author of the module being downgraded. These constraints should be 775 captured in prose or ASN.1 comments and enforced through other means, 776 as necessary. 778 Depending on the feature set of the ASN.1 compiler being used, the 779 code to enforce and use constraints may be generated automatically or 780 may require the programmer to do this independently. It is the 781 responsibility of the programmer to ensure that the constraints on 782 the ASN.1 expressed either in prose or in the ASN.1 module are 783 actually enforced. 785 7. References 787 7.1. Normative References 789 [CCITT.X208.1988] 790 International International Telephone and Telegraph 791 Consultative Committee, "Specification of Abstract Syntax 792 Notation One (ASN.1)", CCITT Recommendation X.208, 793 November 1988. 795 [CCITT.X680.2002] 796 International International Telephone and Telegraph 797 Consultative Committee, "Abstract Syntax Notation One 798 (ASN.1): Specification of basic notation", 799 CCITT Recommendation X.680, July 2002. 801 [CCITT.X681.2002] 802 International International Telephone and Telegraph 803 Consultative Committee, "Abstract Syntax Notation One 804 (ASN.1): Information object specification", 805 CCITT Recommendation X.681, July 2002. 807 [CCITT.X682.2002] 808 International International Telephone and Telegraph 809 Consultative Committee, "Abstract Syntax Notation One 810 (ASN.1): Constraint specification", CCITT Recommendation 811 X.682, July 2002. 813 [CCITT.X683.2002] 814 International International Telephone and Telegraph 815 Consultative Committee, "Abstract Syntax Notation One 816 (ASN.1): Parameterization of ASN.1 specifications", 817 CCITT Recommendation X.683, July 2002. 819 7.2. Informative References 821 [CCITT.X209.1988] 822 International Telephone and Telegraph Consultative 823 Committee, "Specification of Basic Encoding Rules for 824 Abstract Syntax Notation One (ASN.1)", 825 CCITT Recommendation X.209, 1988. 827 [CCITT.X690.2002] 828 International International Telephone and Telegraph 829 Consultative Committee, "ASN.1 encoding rules: 830 Specification of basic encoding Rules (BER), Canonical 831 encoding rules (CER) and Distinguished encoding rules 832 (DER)", CCITT Recommendation X.690, July 2002. 834 [I-D.ietf-pkix-new-asn1] 835 Hoffman, P. and J. Schaad, "New ASN.1 Modules for PKIX", 836 draft-ietf-pkix-new-asn1-08 (work in progress), 837 March 2010. 839 [I-D.ietf-smime-new-asn1] 840 Hoffman, P. and J. Schaad, "New ASN.1 Modules for CMS and 841 S/MIME", draft-ietf-smime-new-asn1-07 (work in progress), 842 August 2009. 844 [RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C. 845 Adams, "X.509 Internet Public Key Infrastructure Online 846 Certificate Status Protocol - OCSP", RFC 2560, June 1999. 848 [RFC3852] Housley, R., "Cryptographic Message Syntax (CMS)", 849 RFC 3852, July 2004. 851 [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., 852 Housley, R., and W. Polk, "Internet X.509 Public Key 853 Infrastructure Certificate and Certificate Revocation List 854 (CRL) Profile", RFC 5280, May 2008. 856 Authors' Addresses 858 Carl Wallace 859 Cygnacom Solutions 860 Suite 5400 861 7925 Jones Branch Drive 862 McLean, VA 22102 864 Email: cwallace@cygnacom.com 866 Charles Gardiner 867 BBN Technologies 868 10 Moulton Street 869 Cambridge, MA 02138 871 Email: gardiner@bbn.com