Guile: Fix `x509-certificate-dn-oid' and related functions.
[gnutls.git] / doc / protocol / rfc2986.txt
blobec8f1e3318797edf7a305155c30350d94711f6c7
7 Network Working Group                                         M. Nystrom
8 Request for Comments: 2986                                    B. Kaliski
9 Obsoletes: 2314                                             RSA Security
10 Category: Informational                                    November 2000
13           PKCS #10: Certification Request Syntax Specification
14                               Version 1.7
16 Status of this Memo
18    This memo provides information for the Internet community.  It does
19    not specify an Internet standard of any kind.  Distribution of this
20    memo is unlimited.
22 Copyright Notice
24    Copyright (C) The Internet Society (2000).  All Rights Reserved.
26 Abstract
28    This memo represents a republication of PKCS #10 v1.7 from RSA
29    Laboratories' Public-Key Cryptography Standards (PKCS) series, and
30    change control is retained within the PKCS process.  The body of this
31    document, except for the security considerations section, is taken
32    directly from the PKCS #9 v2.0 or the PKCS #10 v1.7 document.
34    This memo describes a syntax for certification requests.
36 Table of Contents
38    1.  Introduction ................................................. 2
39    2.  Definitions and notation ..................................... 2
40    2.1  Definitions ................................................. 2
41    2.2  Notation .................................................... 4
42    3.  Overview ..................................................... 4
43    4.  Certification request syntax ................................. 5
44    4.1  CertificationRequestInfo .................................... 5
45    4.2  CertificationRequest ........................................ 7
46    5.  Security Considerations ...................................... 8
47    6.  Authors' Addresses ........................................... 8
48    A.  ASN.1 module ................................................. 9
49    B.  Intellectual property considerations ........................ 10
50    C.  Revision history ............................................ 10
51    D.  References .................................................. 11
52    E.  Contact information & About PKCS ............................ 12
53    Full Copyright Statement ........................................ 14
58 Nystrom & Kaliski            Informational                      [Page 1]
60 RFC 2986       Certification Request Syntax Specification  November 2000
63 1. Introduction
65    This document describes syntax for certification requests.  A
66    certification request consists of a distinguished name, a public key,
67    and optionally a set of attributes, collectively signed by the entity
68    requesting certification.  Certification requests are sent to a
69    certification authority, which transforms the request into an X.509
70    [9] public-key certificate.  (In what form the certification
71    authority returns the newly signed certificate is outside the scope
72    of this document.  A PKCS #7 [2] message is one possibility.)
74    The intention of including a set of attributes is twofold: to provide
75    other information about a given entity , or a "challenge password" by
76    which the entity may later request certificate revocation; and to
77    provide attributes for inclusion in X.509 certificates.  A non-
78    exhaustive list of attributes is given in PKCS #9 [3].
80    Certification authorities may also require non-electronic forms of
81    request and may return non-electronic replies.  It is expected that
82    descriptions of such forms, which are outside the scope of this
83    document, will be available from certification authorities.
85    The preliminary intended application of this document is to support
86    PKCS #7 cryptographic messages, but it is expected that other
87    applications will be developed (see e.g. [4]).
89 2. Definitions and notation
91  2.1 Definitions
93    For the purposes of this document, the following definitions apply.
95    ALGORITHM       An information object class defined in X.509 to
96                    describe objects composed of an algorithm (a unique
97                    object identifier) and its parameters (any ASN.1
98                    type).  The values of objects in this class can be
99                    represented by the ASN.1 type AlgorithmIdentifier{}.
100                    ALGORITHM is defined as the "useful" information
101                    object class TYPE-IDENTIFIER, specified in [11],
102                    Annex A.
104    AlgorithmIdentifier{}
105                    A useful parameterized version of X.509 type
106                    AlgorithmIdentifier is defined in this document.
107                    This type tightly binds pairs of algorithm object
108                    identifiers to their associated parameter types.
109                    When referenced, the single parameter of
110                    AlgorithmIdentifier{} specifies a constraint on the
114 Nystrom & Kaliski            Informational                      [Page 2]
116 RFC 2986       Certification Request Syntax Specification  November 2000
119                    pairs of values that may appear in that instance of
120                    the type.  The encoded values of
121                    AlgorithmIdentifier{} are equivalent to those of type
122                    AlgorithmIdentifier.
124    ASN.1           Abstract Syntax Notation One, as defined in the ASN.1
125                    standards ([10], [11], [12], and [13]).
127    ATTRIBUTE       This class describes objects composed of an attribute
128                    (a unique object identifier) and an associated set of
129                    attribute values (any ASN.1 type).  The values of
130                    objects in this class can be represented by type
131                    Attribute{}.
133    Attribute{}     A useful parameterized version of X.501 [8] type
134                    Attribute is defined in this document.  This type
135                    tightly binds pairs of attribute type object
136                    identifiers to one or more attribute values types.
137                    In the ASN.1 open type notation, an attribute type is
138                    defined as ATTRIBUTE.&id and an attribute value as
139                    ATTRIBUTE.&Type.  When referenced, the single
140                    parameter of Attribute{} specifies a constraint on
141                    the pairs of values that may appear in an instance of
142                    the type.  The encoded values of Attribute{} are
143                    equivalent to those of type Attribute.
145    BER             Basic Encoding Rules for ASN.1, as defined in X.690
146                    ([14]).
148    Certificate     A type that binds a subject entity's distinguished
149                    name to a public key with a digital signature.  This
150                    type is defined in X.509.  This type also contains
151                    the distinguished name of the certificate issuer (the
152                    signer), an issuer-specific serial number, the
153                    issuer's signature algorithm identifier, a validity
154                    period, and an optional set of certificate
155                    extensions.
157    DER             Distinguished Encoding Rules for ASN.1, as defined in
158                    X.690.  DER is a subset of BER.
160    Name            A type that uniquely identifies or "distinguishes"
161                    objects in an X.500 [7] directory.  This type is
162                    defined in X.501.  In an X.509 certificate, the type
163                    identifies the certificate issuer and the certificate
164                    subject, the entity whose public key is certified.
170 Nystrom & Kaliski            Informational                      [Page 3]
172 RFC 2986       Certification Request Syntax Specification  November 2000
175   2.2 Notation
177    No special notation is used in this document.
179 3. Overview
181    A certification request consists of three parts: "certification
182    request information," a signature algorithm identifier, and a digital
183    signature on the certification request information.  The
184    certification request information consists of the entity's
185    distinguished name, the entity's public key, and a set of attributes
186    providing other information about the entity.
188    The process by which a certification request is constructed involves
189    the following steps:
191         1. A CertificationRequestInfo value containing a subject
192            distinguished name, a subject public key, and optionally a
193            set of attributes is constructed by an entity requesting
194            certification.
196         2. The CertificationRequestInfo value is signed with the subject
197            entity's private key.  (See Section 4.2.)
199         3. The CertificationRequestInfo value, a signature algorithm
200            identifier, and the entity's signature are collected together
201            into a CertificationRequest value, defined below.
203    A certification authority fulfills the request by authenticating the
204    requesting entity and verifying the entity's signature, and, if the
205    request is valid, constructing an X.509 certificate from the
206    distinguished name and public key, the issuer name, and the
207    certification authority's choice of serial number, validity period,
208    and signature algorithm.  If the certification request contains any
209    PKCS #9 attributes, the certification authority may also use the
210    values in these attributes as well as other information known to the
211    certification authority to construct X.509 certificate extensions.
213    In what form the certification authority returns the new certificate
214    is outside the scope of this document.  One possibility is a PKCS #7
215    cryptographic message with content type signedData, following the
216    degenerate case where there are no signers.  The return message may
217    include a certification path from the new certificate to the
218    certification authority.  It may also include other certificates such
219    as cross-certificates that the certification authority considers
220    helpful, and it may include certificate-revocation lists (CRLs).
221    Another possibility is that the certification authority inserts the
222    new certificate into a central database.
226 Nystrom & Kaliski            Informational                      [Page 4]
228 RFC 2986       Certification Request Syntax Specification  November 2000
231    Note 1 - An entity would typically send a certification request after
232    generating a public-key/private-key pair, but may also do so after a
233    change in the entity's distinguished name.
235    Note 2 - The signature on the certification request prevents an
236    entity from requesting a certificate with another party's public key.
237    Such an attack would give the entity the minor ability to pretend to
238    be the originator of any message signed by the other party.  This
239    attack is significant only if the entity does not know the message
240    being signed and the signed part of the message does not identify the
241    signer.  The entity would still not be able to decrypt messages
242    intended for the other party, of course.
244    Note 3 - How the entity sends the certification request to a
245    certification authority is outside the scope of this document.  Both
246    paper and electronic forms are possible.
248    Note 4 - This document is not compatible with the certification
249    request syntax for Privacy-Enhanced Mail, as described in RFC 1424
250    [5].  The syntax here differs in three respects: It allows a set of
251    attributes; it does not include issuer name, serial number, or
252    validity period; and it does not require an "innocuous" message to be
253    signed.  This document is designed to minimize request size, an
254    important feature for certification authorities accepting requests on
255    paper.
257 4. Certification request syntax
259    This section is divided into two parts.  The first part describes the
260    certification-request-information type CertificationRequestInfo, and
261    the second part describes the top-level type CertificationRequest.
263  4.1 CertificationRequestInfo
265    Certification request information shall have ASN.1 type
266    CertificationRequestInfo:
268    CertificationRequestInfo ::= SEQUENCE {
269         version       INTEGER { v1(0) } (v1,...),
270         subject       Name,
271         subjectPKInfo SubjectPublicKeyInfo{{ PKInfoAlgorithms }},
272         attributes    [0] Attributes{{ CRIAttributes }}
273    }
275    SubjectPublicKeyInfo { ALGORITHM : IOSet} ::= SEQUENCE {
276         algorithm        AlgorithmIdentifier {{IOSet}},
277         subjectPublicKey BIT STRING
278    }
282 Nystrom & Kaliski            Informational                      [Page 5]
284 RFC 2986       Certification Request Syntax Specification  November 2000
287    PKInfoAlgorithms ALGORITHM ::= {
288         ...  -- add any locally defined algorithms here -- }
290    Attributes { ATTRIBUTE:IOSet } ::= SET OF Attribute{{ IOSet }}
292    CRIAttributes  ATTRIBUTE  ::= {
293         ... -- add any locally defined attributes here -- }
295    Attribute { ATTRIBUTE:IOSet } ::= SEQUENCE {
296         type   ATTRIBUTE.&id({IOSet}),
297         values SET SIZE(1..MAX) OF ATTRIBUTE.&Type({IOSet}{@type})
298    }
300    The components of type CertificationRequestInfo have the following
301    meanings:
303         version is the version number, for compatibility with future
304           revisions of this document.  It shall be 0 for this version of
305           the standard.
307         subject is the distinguished name of the certificate subject
308           (the entity whose public key is to be certified).
310         subjectPublicKeyInfo contains information about the public key
311           being certified.  The information identifies the entity's
312           public-key algorithm (and any associated parameters); examples
313           of public-key algorithms include the rsaEncryption object
314           identifier from PKCS #1 [1].  The information also includes a
315           bit-string representation of the entity's public key.  For the
316           public-key algorithm just mentioned, the bit string contains
317           the DER encoding of a value of PKCS #1 type RSAPublicKey.  The
318           values of type SubjectPublicKeyInfo{} allowed for
319           subjectPKInfo are constrained to the values specified by the
320           information object set PKInfoAlgorithms, which includes the
321           extension marker (...).  Definitions of specific algorithm
322           objects are left to specifications that reference this
323           document.  Such specifications will be interoperable with
324           their future versions if any additional algorithm objects are
325           added after the extension marker.
327         attributes is a collection of attributes providing additional
328           information about the subject of the certificate.  Some
329           attribute types that might be useful here are defined in PKCS
330           #9.  An example is the challenge-password attribute, which
331           specifies a password by which the entity may request
332           certificate revocation.  Another example is information to
333           appear in X.509 certificate extensions (e.g. the
334           extensionRequest attribute from PKCS #9).  The values of type
338 Nystrom & Kaliski            Informational                      [Page 6]
340 RFC 2986       Certification Request Syntax Specification  November 2000
343           Attributes{} allowed for attributes are constrained to the
344           values specified by the information object set CRIAttributes.
345           Definitions of specific attribute objects are left to
346           specifications that reference this document.  Such
347           specifications will be interoperable with their future
348           versions if any additional attribute objects are added after
349           the extension marker.
351  4.2 CertificationRequest
353    A certification request shall have ASN.1 type CertificationRequest:
355    CertificationRequest ::= SEQUENCE {
356         certificationRequestInfo CertificationRequestInfo,
357         signatureAlgorithm AlgorithmIdentifier{{ SignatureAlgorithms }},
358         signature          BIT STRING
359    }
361    AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE {
362         algorithm          ALGORITHM.&id({IOSet}),
363         parameters         ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL
364    }
366    SignatureAlgorithms ALGORITHM ::= {
367         ... -- add any locally defined algorithms here -- }
369    The components of type CertificationRequest have the following
370    meanings:
372         certificateRequestInfo is the "certification request
373           information." It is the value being signed.
375         signatureAlgorithm identifies the signature algorithm (and any
376           associated parameters) under which the certification-request
377           information is signed.  For example, a specification might
378           include an ALGORITHM object for PKCS #1's
379           md5WithRSAEncryption in the information object set
380           SignatureAlgorithms:
382           SignatureAlgorithms ALGORITHM ::= {
383                ...,
384                { NULL IDENTIFIED BY md5WithRSAEncryption }
385           }
387         signature is the result of signing the certification request
388           information with the certification request subject's private
389           key.
394 Nystrom & Kaliski            Informational                      [Page 7]
396 RFC 2986       Certification Request Syntax Specification  November 2000
399    The signature process consists of two steps:
401         1. The value of the certificationRequestInfo component is DER
402            encoded, yielding an octet string.
404         2. The result of step 1 is signed with the certification request
405            subject's private key under the specified signature
406            algorithm, yielding a bit string, the signature.
408    Note - An equivalent syntax for CertificationRequest could be
409    written:
411    CertificationRequest ::= SIGNED { EncodedCertificationRequestInfo }
412         (CONSTRAINED BY { -- Verify or sign encoded
413          -- CertificationRequestInfo -- })
415    EncodedCertificationRequestInfo ::=
416         TYPE-IDENTIFIER.&Type(CertificationRequestInfo)
418    SIGNED { ToBeSigned } ::= SEQUENCE {
419         toBeSigned ToBeSigned,
420         algorithm  AlgorithmIdentifier { {SignatureAlgorithms} },
421         signature  BIT STRING
422    }
424 5. Security Considerations
426    Security issues are discussed throughout this memo.
428 6. Authors' Addresses
430    Magnus Nystrom
431    RSA Security
432    Box 10704
433    S-121 29 Stockholm
434    Sweden
436    EMail: magnus@rsasecurity.com
439    Burt Kaliski
440    RSA Security
441    20 Crosby Drive
442    Bedford, MA 01730 USA
444    EMail: bkaliski@rsasecurity.com
450 Nystrom & Kaliski            Informational                      [Page 8]
452 RFC 2986       Certification Request Syntax Specification  November 2000
455 APPENDICES
457 A. ASN.1 Module
459    This appendix includes all of the ASN.1 type and value definitions
460    contained in this document in the form of the ASN.1 module PKCS-10.
462    PKCS-10 {iso(1) member-body(2) us(840) rsadsi(113549) pkcs(1)
463    pkcs-10(10) modules(1) pkcs-10(1)}
465    DEFINITIONS IMPLICIT TAGS ::=
467    BEGIN
469    -- EXPORTS All --
471    -- All types and values defined in this module are exported for use
472    -- in other ASN.1 modules.
474    IMPORTS
476    informationFramework, authenticationFramework
477         FROM UsefulDefinitions {joint-iso-itu-t(2) ds(5) module(1)
478         usefulDefinitions(0) 3}
480    ATTRIBUTE, Name
481         FROM InformationFramework informationFramework
483    ALGORITHM
484         FROM AuthenticationFramework authenticationFramework;
486    -- Certificate requests
487    CertificationRequestInfo ::= SEQUENCE {
488         version       INTEGER { v1(0) } (v1,...),
489         subject       Name,
490         subjectPKInfo SubjectPublicKeyInfo{{ PKInfoAlgorithms }},
491         attributes    [0] Attributes{{ CRIAttributes }}
492    }
494    SubjectPublicKeyInfo {ALGORITHM: IOSet} ::= SEQUENCE {
495         algorithm        AlgorithmIdentifier {{IOSet}},
496         subjectPublicKey BIT STRING
497    }
499    PKInfoAlgorithms ALGORITHM ::= {
500         ...  -- add any locally defined algorithms here -- }
502    Attributes { ATTRIBUTE:IOSet } ::= SET OF Attribute{{ IOSet }}
506 Nystrom & Kaliski            Informational                      [Page 9]
508 RFC 2986       Certification Request Syntax Specification  November 2000
511    CRIAttributes  ATTRIBUTE  ::= {
512         ... -- add any locally defined attributes here -- }
514    Attribute { ATTRIBUTE:IOSet } ::= SEQUENCE {
515         type   ATTRIBUTE.&id({IOSet}),
516         values SET SIZE(1..MAX) OF ATTRIBUTE.&Type({IOSet}{@type})
517    }
519    CertificationRequest ::= SEQUENCE {
520         certificationRequestInfo CertificationRequestInfo,
521         signatureAlgorithm AlgorithmIdentifier{{ SignatureAlgorithms }},
522         signature          BIT STRING
523    }
525    AlgorithmIdentifier {ALGORITHM:IOSet } ::= SEQUENCE {
526         algorithm  ALGORITHM.&id({IOSet}),
527         parameters ALGORITHM.&Type({IOSet}{@algorithm}) OPTIONAL
528    }
530    SignatureAlgorithms ALGORITHM ::= {
531         ... -- add any locally defined algorithms here -- }
533    END
535 B. Intellectual property considerations
537    RSA Security makes no patent claims on the general constructions
538    described in this document, although specific underlying techniques
539    may be covered.
541    License to copy this document is granted provided that it is
542    identified as "RSA Security Inc.  Public-Key Cryptography Standards
543    (PKCS)" in all material mentioning or referencing this document.
545    RSA Security makes no representations regarding intellectual property
546    claims by other parties.  Such determination is the responsibility of
547    the user.
549 C. Revision history
551    Version 1.0
553          Version 1.0 was the previous version of this document (also
554          published as "version 1.5" in [6]).
562 Nystrom & Kaliski            Informational                     [Page 10]
564 RFC 2986       Certification Request Syntax Specification  November 2000
567    Version 1.7
569          This version incorporates several editorial changes, including
570          updates to the references, and changes to ASN.1 type
571          definitions.  The following substantive changes have been made:
573          - This version refers to X.680-X.690, the current international
574            standards for ASN.1 and its encoding rules.  All references
575            to X.208 and X.209 have been eliminated.
577          - The X.690 standard requires that the encoded values of SET OF
578            components be sorted in ascending order under DER.
579            Regardless of this, applications should not rely on the
580            ordering of attribute components.
582          - All references to PKCS #6 Extended-Certificate Syntax
583            Standard have been removed.  With the addition of extensions
584            to X.509 version 3 certificates, RSA Laboratories is
585            withdrawing support for PKCS #6.
587    Note - The reason for using version 1.7 for this document is to avoid
588    confusion with [6], which is named version 1.5, and an unsupported
589    PKCS #10 version named Version 1.6.
591 D. References
593    [1]  RSA Laboratories. PKCS #1: RSA Encryption Standard. Version 2.0,
594         October 1998.
596    [2]  RSA Laboratories. PKCS #7: Cryptographic Message Syntax
597         Standard.  Version 1.5, November 1993.
599    [3]  RSA Laboratories. PKCS #9: Selected Attribute Types. Version
600         2.0, February 2000.
602    [4]  Adams, C. and S. Farrell, "Internet X.509 Public Key
603         Infrastructure - Certificate Management Protocols", RFC 2510,
604         March 1999.
606    [5]  Kaliski, B., "Privacy Enhancement for Internet Electronic Mail:
607         Part IV: Key Certification and Related Services", RFC 1424,
608         February 1993.
610    [6]  Kaliski, B., "PKCS #10: Certification Request Syntax Version
611         1.5", RFC 2314, March 1998.
618 Nystrom & Kaliski            Informational                     [Page 11]
620 RFC 2986       Certification Request Syntax Specification  November 2000
623    [7]  ITU-T Recommendation X.500 (1997) | ISO/IEC 9594-1:1998,
624         Information technology - Open Systems Interconnection - The
625         Directory: Overview of concepts, models and services.
627    [8]  ITU-T Recommendation X.501 (1993) | ISO/IEC 9594-2:1995,
628         Information technology - Open Systems Interconnection - The
629         Directory: Models.
631    [9]  ITU-T Recommendation X.509 (1997) | ISO/IEC 9594-8:1998,
632         Information technology - Open Systems Interconnection -The
633         Directory:  Authentication framework.
635    [10] ITU-T Recommendation X.680 (1997) | ISO/IEC 8824-1:1998,
636         Information Technology - Abstract Syntax Notation One (ASN.1):
637         Specification of Basic Notation.
639    [11] ITU-T Recommendation X.681 (1997) | ISO/IEC 8824-2:1998,
640         Information Technology - Abstract Syntax Notation One (ASN.1):
641         Information Object Specification.
643    [12] ITU-T Recommendation X.682 (1997) | ISO/IEC 8824-3:1998,
644         Information Technology - Abstract Syntax Notation One (ASN.1):
645         Constraint Specification.
647    [13] ITU-T Recommendation X.683 (1997) | ISO/IEC 8824-4:1998,
648         Information Technology - Abstract Syntax Notation One (ASN.1):
649         Parameterization of ASN.1 Specifications.
651    [14] ITU-T Recommendation X.690 (1997) | ISO/IEC 8825-1:1998,
652         Information Technology - ASN.1 Encoding Rules: Specification of
653         Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and
654         Distinguished Encoding Rules (DER).
656 E. Contact Information & About PKCS
658    The Public-Key Cryptography Standards are specifications produced by
659    RSA Laboratories in cooperation with secure systems developers
660    worldwide for the purpose of accelerating the deployment of public-
661    key cryptography.  First published in 1991 as a result of meetings
662    with a small group of early adopters of public-key technology, the
663    PKCS documents have become widely referenced and implemented.
664    Contributions from the PKCS series have become part of many formal
665    and de facto standards, including ANSI X9 documents, PKIX, SET,
666    S/MIME, and SSL.
674 Nystrom & Kaliski            Informational                     [Page 12]
676 RFC 2986       Certification Request Syntax Specification  November 2000
679    Further development of PKCS occurs through mailing list discussions
680    and occasional workshops, and suggestions for improvement are
681    welcome.  For more information, contact:
683         PKCS Editor
684         RSA Laboratories
685         20 Crosby Drive
686         Bedford, MA  01730 USA
687         pkcs-editor@rsasecurity.com
688         http://www.rsasecurity.com/rsalabs/pkcs
730 Nystrom & Kaliski            Informational                     [Page 13]
732 RFC 2986       Certification Request Syntax Specification  November 2000
735 Full Copyright Statement
737    Copyright (C) The Internet Society 2000. All Rights Reserved.
739    This document and translations of it may be copied and furnished to
740    others provided that the above copyright notice and this paragraph
741    are included on all such copies.  However, this document itself may
742    not be modified in any way, such as by removing the copyright notice
743    or references to the Internet Society or other Internet
744    organizations, except as required to translate it into languages
745    other than English.
747    The limited permissions granted above are perpetual and will not be
748    revoked by the Internet Society or its successors or assigns.
750    This document and the information contained herein is provided on an
751    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
752    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR  IMPLIED, INCLUDING
753    BUT NOT  LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
754    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY  IMPLIED WARRANTIES OF
755    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
757 Acknowledgement
759    Funding for the RFC Editor function is currently provided by the
760    Internet Society.
786 Nystrom & Kaliski            Informational                     [Page 14]