Improve GTK-DOC coverage.
[gnutls.git] / doc / protocol / draft-ietf-tls-rfc4366-bis-02.txt
blob943d4121e621dda06760321668dbd1a11eddcfc4
1 \r
2 TLS Working Group                                    Donald Eastlake 3rd\r
3 INTERNET-DRAFT                                     Motorola Laboratories\r
4 Obsoletes: RFC 4366\r
5 Intended status: Proposed Standard\r
6 Expires: August 2008                                   February 20, 2008\r
7 \r
8 \r
9     Transport Layer Security (TLS) Extensions: Extension Definitions\r
11                   <draft-ietf-tls-rfc4366-bis-02.txt>\r
14 Status of This Document\r
16    By submitting this Internet-Draft, each author represents that any\r
17    applicable patent or other IPR claims of which he or she is aware\r
18    have been or will be disclosed, and any of which he or she becomes\r
19    aware will be disclosed, in accordance with Section 6 of BCP 79.\r
21    Distribution of this document is unlimited.  Comments should be sent\r
22    to the TLS working group mailing list <tls@ietf.org>.\r
24    Internet-Drafts are working documents of the Internet Engineering\r
25    Task Force (IETF), its areas, and its working groups.  Note that\r
26    other groups may also distribute working documents as Internet-\r
27    Drafts.\r
29    Internet-Drafts are draft documents valid for a maximum of six months\r
30    and may be updated, replaced, or obsoleted by other documents at any\r
31    time.  It is inappropriate to use Internet-Drafts as reference\r
32    material or to cite them other than as "work in progress."\r
34    The list of current Internet-Drafts can be accessed at\r
35    http://www.ietf.org/1id-abstracts.html\r
37    The list of Internet-Draft Shadow Directories can be accessed at\r
38    http://www.ietf.org/shadow.html\r
41 Abstract\r
43    This document provides documentation for existing specific TLS\r
44    extensions. It is a companion document for the TLS 1.2 specification,\r
45    draft-ietf-tls-rfc4346-bis-07.txt.\r
57 Donald Eastlake 3rd                                             [Page 1]\r
58 \f\r
59 INTERNET-DRAFT                                 TLS Extension Definitions\r
62 Acknowledgements\r
64    This draft is based on material from RFC 4366 for which the authors\r
65    were S. Blake-Wilson, M. Nystron, D. Hopwood, J. Mikkelsen, and T.\r
66    Wright.\r
70 Table of Contents\r
72       Status of This Document....................................1\r
73       Abstract...................................................1\r
75       Acknowledgements...........................................2\r
76       Table of Contents..........................................2\r
78       1. Introduction............................................3\r
79       1.1 Specific Extensions Covered............................3\r
80       1.2 Conventions Used in This Document......................4\r
82       2. Extensions to the Handshake Protocol....................5\r
84       3. Server Name Indication..................................6\r
85       4. Maximum Fragment Length Negotiation.....................7\r
86       5. Client Certificate URLs.................................8\r
87       6. Trusted CA Indication..................................11\r
88       7. Truncated HMAC.........................................12\r
89       8. Certificate Status Request.............................13\r
91       9. Error Alerts...........................................16\r
93       10. IANA Considerations...................................17\r
94       11. Security Considerations...............................17\r
95       11.1 Security Considerations for server_name..............17\r
96       11.2 Security Considerations for max_fragment_length......17\r
97       11.3 Security Considerations for client_certificate_url...18\r
98       11.4 Security Considerations for trusted_ca_keys..........19\r
99       11.5 Security Considerations for truncated_hmac...........19\r
100       11.6 Security Considerations for status_request...........20\r
102       12. Normative References..................................21\r
103       13. Informative References................................21\r
105       Copyright, Disclaimer, and Additional IPR Provisions......22\r
107       Author's Address..........................................23\r
108       Expiration and File Name..................................23\r
114 Donald Eastlake 3rd                                             [Page 2]\r
115 \f\r
116 INTERNET-DRAFT                                 TLS Extension Definitions\r
119 1. Introduction\r
121    The TLS (Transport Layer Security) Protocol Version 1.2 is specified\r
122    in [RFCTLS]. That specification includes the framework for extensions\r
123    to TLS, considerations in designing such extensions (see Section\r
124    7.4.1.4 of [RFCTLS]), and IANA Considerations for the allocation of\r
125    new extension code points; however, it does not specify any\r
126    particular extensions other than Signature Algorithms (see Section\r
127    7.4.1.4.1 of [RFCTLS]).\r
129    This document provides the specifications for existing TLS\r
130    extensions. It is, for the most part, the adaptation and editing of\r
131    material from [RFC4366], which covered TLS extensions for TLS 1.0\r
132    [RFC2246] and TLS 1.1 [RFC4346].\r
136 1.1 Specific Extensions Covered\r
138    The extensions described here focus on extending the functionality\r
139    provided by the TLS protocol message formats. Other issues, such as\r
140    the addition of new cipher suites, are deferred.\r
142    Specifically, the extensions described in this document:\r
144    -  Allow TLS clients to provide to the TLS server the name of the\r
145       server they are contacting. This functionality is desirable in\r
146       order to facilitate secure connections to servers that host\r
147       multiple 'virtual' servers at a single underlying network address.\r
149    -  Allow TLS clients and servers to negotiate the maximum fragment\r
150       length to be sent. This functionality is desirable as a result of\r
151       memory constraints among some clients, and bandwidth constraints\r
152       among some access networks.\r
154    -  Allow TLS clients and servers to negotiate the use of client\r
155       certificate URLs. This functionality is desirable in order to\r
156       conserve memory on constrained clients.\r
158    -  Allow TLS clients to indicate to TLS servers which CA root keys\r
159       they possess. This functionality is desirable in order to prevent\r
160       multiple handshake failures involving TLS clients that are only\r
161       able to store a small number of CA root keys due to memory\r
162       limitations.\r
164    -  Allow TLS clients and servers to negotiate the use of truncated\r
165       MACs. This functionality is desirable in order to conserve\r
166       bandwidth in constrained access networks.\r
168    -  Allow TLS clients and servers to negotiate that the server sends\r
171 Donald Eastlake 3rd                                             [Page 3]\r
172 \f\r
173 INTERNET-DRAFT                                 TLS Extension Definitions\r
176       the client certificate status information (e.g., an Online\r
177       Certificate Status Protocol (OCSP) [RFC2560] response) during a\r
178       TLS handshake. This functionality is desirable in order to avoid\r
179       sending a Certificate Revocation List (CRL) over a constrained\r
180       access network and therefore save bandwidth.\r
182    The extensions described in this document may be used by TLS clients\r
183    and servers. The extensions are designed to be backwards compatible,\r
184    meaning that TLS clients that support the extensions can talk to TLS\r
185    servers that do not support the extensions, and vice versa.\r
189 1.2 Conventions Used in This Document\r
191    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",\r
192    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this\r
193    document are to be interpreted as described in [RFC2119].\r
228 Donald Eastlake 3rd                                             [Page 4]\r
229 \f\r
230 INTERNET-DRAFT                                 TLS Extension Definitions\r
233 2. Extensions to the Handshake Protocol\r
235    This document specifies the use of two new handshake messages,\r
236    "CertificateURL" and "CertificateStatus".  These messages are\r
237    described in Section 5 and Section 8, respectively.  The new\r
238    handshake message structure therefore becomes:\r
240       enum {\r
241           hello_request(0), client_hello(1), server_hello(2),\r
242           certificate(11), server_key_exchange (12),\r
243           certificate_request(13), server_hello_done(14),\r
244           certificate_verify(15), client_key_exchange(16),\r
245           finished(20), certificate_url(21), certificate_status(22),\r
246           (255)\r
247       } HandshakeType;\r
249       struct {\r
250           HandshakeType msg_type;    /* handshake type */\r
251           uint24 length;             /* bytes in message */\r
252           select (HandshakeType) {\r
253               case hello_request:       HelloRequest;\r
254               case client_hello:        ClientHello;\r
255               case server_hello:        ServerHello;\r
256               case certificate:         Certificate;\r
257               case server_key_exchange: ServerKeyExchange;\r
258               case certificate_request: CertificateRequest;\r
259               case server_hello_done:   ServerHelloDone;\r
260               case certificate_verify:  CertificateVerify;\r
261               case client_key_exchange: ClientKeyExchange;\r
262               case finished:            Finished;\r
263               case certificate_url:     CertificateURL;\r
264               case certificate_status:  CertificateStatus;\r
265           } body;\r
266       } Handshake;\r
285 Donald Eastlake 3rd                                             [Page 5]\r
286 \f\r
287 INTERNET-DRAFT                                 TLS Extension Definitions\r
290 3. Server Name Indication\r
292    TLS does not provide a mechanism for a client to tell a server the\r
293    name of the server it is contacting. It may be desirable for clients\r
294    to provide this information to facilitate secure connections to\r
295    servers that host multiple 'virtual' servers at a single underlying\r
296    network address.\r
298    In order to provide the server name, clients MAY include an extension\r
299    of type "server_name" in the (extended) client hello. The\r
300    "extension_data" field of this extension SHALL contain\r
301    "ServerNameList" where:\r
303       struct {\r
304           NameType name_type;\r
305           select (name_type) {\r
306               case host_name: HostName;\r
307           } name;\r
308       } ServerName;\r
310       enum {\r
311           host_name(0), (255)\r
312       } NameType;\r
314       opaque HostName<1..2^16-1>;\r
316       struct {\r
317           ServerName server_name_list<1..2^16-1>\r
318       } ServerNameList;\r
320    If the server understood the client hello extension but does not\r
321    recognize any of the server names, it SHOULD send an\r
322    unrecognized_name(112) alert (which MAY be fatal).\r
324    Currently, the only server names supported are DNS hostnames;\r
325    however, this does not imply any dependency of TLS on DNS, and other\r
326    name types may be added in the future (by an RFC that updates this\r
327    document). TLS MAY treat provided server names as opaque data and\r
328    pass the names and types to the application.\r
330    "HostName" contains the fully qualified DNS hostname of the server,\r
331    as understood by the client. The hostname is represented as a byte\r
332    string using ASCII encoding without a trailing dot.\r
334    Literal IPv4 and IPv6 addresses are not permitted in "HostName".\r
336    It is RECOMMENDED that clients include an extension of type\r
337    "server_name" in the client hello whenever they locate a server by a\r
338    supported name type.\r
342 Donald Eastlake 3rd                                             [Page 6]\r
343 \f\r
344 INTERNET-DRAFT                                 TLS Extension Definitions\r
347    A server that receives a client hello containing the "server_name"\r
348    extension MAY use the information contained in the extension to guide\r
349    its selection of an appropriate certificate to return to the client,\r
350    and/or other aspects of security policy. In this event, the server\r
351    SHALL include an extension of type "server_name" in the (extended)\r
352    server hello. The "extension_data" field of this extension SHALL be\r
353    empty.\r
355    If the server understood the client hello extension but does not\r
356    recognize the server name, it SHOULD send an "unrecognized_name"\r
357    alert (which MAY be fatal).\r
359    If an application negotiates a server name using an application\r
360    protocol and then upgrades to TLS, and if a server_name extension is\r
361    sent, then the extension SHOULD contain the same name that was\r
362    negotiated in the application protocol. If the server_name is\r
363    established in the TLS session handshake, the client SHOULD NOT\r
364    attempt to request a different server name at the application layer.\r
368 4. Maximum Fragment Length Negotiation\r
370    Without this extension, TLS specifies a fixed maximum plaintext\r
371    fragment length of 2^14 bytes. It may be desirable for constrained\r
372    clients to negotiate a smaller maximum fragment length due to memory\r
373    limitations or bandwidth limitations.\r
375    In order to negotiate smaller maximum fragment lengths, clients MAY\r
376    include an extension of type "max_fragment_length" in the (extended)\r
377    client hello. The "extension_data" field of this extension SHALL\r
378    contain:\r
380       enum{\r
381           2^9(1), 2^10(2), 2^11(3), 2^12(4), (255)\r
382       } MaxFragmentLength;\r
384    whose value is the desired maximum fragment length. The allowed\r
385    values for this field are: 2^9, 2^10, 2^11, and 2^12.\r
387    Servers that receive an extended client hello containing a\r
388    "max_fragment_length" extension MAY accept the requested maximum\r
389    fragment length by including an extension of type\r
390    "max_fragment_length" in the (extended) server hello. The\r
391    "extension_data" field of this extension SHALL contain a\r
392    "MaxFragmentLength" whose value is the same as the requested maximum\r
393    fragment length.\r
395    If a server receives a maximum fragment length negotiation request\r
396    for a value other than the allowed values, it MUST abort the\r
399 Donald Eastlake 3rd                                             [Page 7]\r
400 \f\r
401 INTERNET-DRAFT                                 TLS Extension Definitions\r
404    handshake with an "illegal_parameter" alert. Similarly, if a client\r
405    receives a maximum fragment length negotiation response that differs\r
406    from the length it requested, it MUST also abort the handshake with\r
407    an "illegal_parameter" alert.\r
409    Once a maximum fragment length other than 2^14 has been successfully\r
410    negotiated, the client and server MUST immediately begin fragmenting\r
411    messages (including handshake messages), to ensure that no fragment\r
412    larger than the negotiated length is sent. Note that TLS already\r
413    requires clients and servers to support fragmentation of handshake\r
414    messages.\r
416    The negotiated length applies for the duration of the session\r
417    including session resumptions.\r
419    The negotiated length limits the input that the record layer may\r
420    process without fragmentation (that is, the maximum value of\r
421    TLSPlaintext.length; see [RFCTLS], Section 6.2.1). Note that the\r
422    output of the record layer may be larger. For example, if the\r
423    negotiated length is 2^9=512, then for currently defined cipher\r
424    suites (those defined in [RFCTLS], [RFC2712], and [RFC3268]), and\r
425    when null compression is used, the record layer output can be at most\r
426    805 bytes: 5 bytes of headers, 512 bytes of application data, 256\r
427    bytes of padding, and 32 bytes of MAC. This means that in this event\r
428    a TLS record layer peer receiving a TLS record layer message larger\r
429    than 805 bytes may discard the message and send a "record_overflow"\r
430    alert, without decrypting the message.\r
434 5. Client Certificate URLs\r
436    Without this extension, TLS specifies that when client authentication\r
437    is performed, client certificates are sent by clients to servers\r
438    during the TLS handshake. It may be desirable for constrained clients\r
439    to send certificate URLs in place of certificates, so that they do\r
440    not need to store their certificates and can therefore save memory.\r
442    In order to negotiate sending certificate URLs to a server, clients\r
443    MAY include an extension of type "client_certificate_url" in the\r
444    (extended) client hello. The "extension_data" field of this extension\r
445    SHALL be empty.\r
447    (Note that it is necessary to negotiate use of client certificate\r
448    URLs in order to avoid "breaking" existing TLS servers.)\r
450    Servers that receive an extended client hello containing a\r
451    "client_certificate_url" extension MAY indicate that they are willing\r
452    to accept certificate URLs by including an extension of type\r
453    "client_certificate_url" in the (extended) server hello. The\r
456 Donald Eastlake 3rd                                             [Page 8]\r
457 \f\r
458 INTERNET-DRAFT                                 TLS Extension Definitions\r
461    "extension_data" field of this extension SHALL be empty.\r
463    After negotiation of the use of client certificate URLs has been\r
464    successfully completed (by exchanging hellos including\r
465    "client_certificate_url" extensions), clients MAY send a\r
466    "CertificateURL" message in place of a "Certificate" message as\r
467    follows (see also Section 2):\r
469       enum {\r
470           individual_certs(0), pkipath(1), (255)\r
471       } CertChainType;\r
473       enum {\r
474           false(0), true(1)\r
475       } Boolean;\r
477       struct {\r
478           CertChainType type;\r
479           URLAndOptionalHash url_and_hash_list<1..2^16-1>;\r
480       } CertificateURL;\r
482       struct {\r
483           opaque url<1..2^16-1>;\r
484           Boolean hash_present;\r
485           select (hash_present) {\r
486               case false: struct {};\r
487               case true: SHA1Hash;\r
488           } hash;\r
489       } URLAndOptionalHash;\r
491       opaque SHA1Hash[20];\r
493    Here "url_and_hash_list" contains a sequence of URLs and optional\r
494    hashes.\r
496    When X.509 certificates are used, there are two possibilities:\r
498    -  If CertificateURL.type is "individual_certs", each URL refers to a\r
499    single DER-encoded X.509v3 certificate, with the URL for the client's\r
500    certificate first.\r
502    -  If CertificateURL.type is "pkipath", the list contains a single\r
503    URL referring to a DER-encoded certificate chain, using the type\r
504    PkiPath described in Section 8 of [RFCTLS].\r
506    When any other certificate format is used, the specification that\r
507    describes use of that format in TLS should define the encoding format\r
508    of certificates or certificate chains, and any constraint on their\r
509    ordering.\r
513 Donald Eastlake 3rd                                             [Page 9]\r
514 \f\r
515 INTERNET-DRAFT                                 TLS Extension Definitions\r
518    The hash corresponding to each URL at the client's discretion either\r
519    is not present or is the SHA-1 hash of the certificate or certificate\r
520    chain (in the case of X.509 certificates, the DER-encoded certificate\r
521    or the DER-encoded PkiPath).\r
523    Note that when a list of URLs for X.509 certificates is used, the\r
524    ordering of URLs is the same as that used in the TLS Certificate\r
525    message (see [RFCTLS], Section 7.4.2), but opposite to the order in\r
526    which certificates are encoded in PkiPath. In either case, the self-\r
527    signed root certificate MAY be omitted from the chain, under the\r
528    assumption that the server must already possess it in order to\r
529    validate it.\r
531    Servers receiving "CertificateURL" SHALL attempt to retrieve the\r
532    client's certificate chain from the URLs and then process the\r
533    certificate chain as usual. A cached copy of the content of any URL\r
534    in the chain MAY be used, provided that a SHA-1 hash is present for\r
535    that URL and it matches the hash of the cached copy.\r
537    Servers that support this extension MUST support the http: URL scheme\r
538    for certificate URLs, and MAY support other schemes. Use of other\r
539    schemes than "http", "https", or "ftp" may create unexpected\r
540    problems.\r
542    If the protocol used is HTTP, then the HTTP server can be configured\r
543    to use the Cache-Control and Expires directives described in\r
544    [RFC2616] to specify whether and for how long certificates or\r
545    certificate chains should be cached.\r
547    The TLS server is not required to follow HTTP redirects when\r
548    retrieving the certificates or certificate chain. The URLs used in\r
549    this extension SHOULD therefore be chosen not to depend on such\r
550    redirects.\r
552    If the protocol used to retrieve certificates or certificate chains\r
553    returns a MIME-formatted response (as HTTP does), then the following\r
554    MIME Content-Types SHALL be used: when a single X.509v3 certificate\r
555    is returned, the Content-Type is "application/pkix-cert" [RFC2585],\r
556    and when a chain of X.509v3 certificates is returned, the Content-\r
557    Type is "application/pkix-pkipath" (see Section 8 of [RFCTLS]).\r
559    If a SHA-1 hash is present for an URL, then the server MUST check\r
560    that the SHA-1 hash of the contents of the object retrieved from that\r
561    URL (after decoding any MIME Content-Transfer-Encoding) matches the\r
562    given hash. If any retrieved object does not have the correct SHA-1\r
563    hash, the server MUST abort the handshake with a\r
564    bad_certificate_hash_value(114) alert. This alert is always fatal.\r
566    Clients may choose to send either "Certificate" or "CertificateURL"\r
567    after successfully negotiating the option to send certificate URLs.\r
570 Donald Eastlake 3rd                                            [Page 10]\r
571 \f\r
572 INTERNET-DRAFT                                 TLS Extension Definitions\r
575    The option to send a certificate is included to provide flexibility\r
576    to clients possessing multiple certificates.\r
578    If a server encounters an unreasonable delay in obtaining\r
579    certificates in a given CertificateURL, it SHOULD time out and signal\r
580    a certificate_unobtainable(111) error alert. This alert MAY be fatal;\r
581    for example, if client authentication is required by the server for\r
582    the handshake to continue.\r
586 6. Trusted CA Indication\r
588    Constrained clients that, due to memory limitations, possess only a\r
589    small number of CA root keys may wish to indicate to servers which\r
590    root keys they possess, in order to avoid repeated handshake\r
591    failures.\r
593    In order to indicate which CA root keys they possess, clients MAY\r
594    include an extension of type "trusted_ca_keys" in the (extended)\r
595    client hello. The "extension_data" field of this extension SHALL\r
596    contain "TrustedAuthorities" where:\r
598       struct {\r
599           TrustedAuthority trusted_authorities_list<0..2^16-1>;\r
600       } TrustedAuthorities;\r
602       struct {\r
603           IdentifierType identifier_type;\r
604           select (identifier_type) {\r
605               case pre_agreed: struct {};\r
606               case key_sha1_hash: SHA1Hash;\r
607               case x509_name: DistinguishedName;\r
608               case cert_sha1_hash: SHA1Hash;\r
609           } identifier;\r
610       } TrustedAuthority;\r
612       enum {\r
613           pre_agreed(0), key_sha1_hash(1), x509_name(2),\r
614           cert_sha1_hash(3), (255)\r
615       } IdentifierType;\r
617       opaque DistinguishedName<1..2^16-1>;\r
619    Here "TrustedAuthorities" provides a list of CA root key identifiers\r
620    that the client possesses. Each CA root key is identified via either:\r
622    -  "pre_agreed": no CA root key identity supplied.\r
624    -  "key_sha1_hash": contains the SHA-1 hash of the CA root key. For\r
627 Donald Eastlake 3rd                                            [Page 11]\r
628 \f\r
629 INTERNET-DRAFT                                 TLS Extension Definitions\r
632       Digital Signature Algorithm (DSA) and Elliptic Curve Digital\r
633       Signature Algorithm (ECDSA) keys, this is the hash of the\r
634       "subjectPublicKey" value. For RSA keys, the hash is of the big-\r
635       endian byte string representation of the modulus without any\r
636       initial 0-valued bytes. (This copies the key hash formats deployed\r
637       in other environments.)\r
639    -  "x509_name": contains the DER-encoded X.509 DistinguishedName of\r
640       the CA.\r
642    -  "cert_sha1_hash": contains the SHA-1 hash of a DER-encoded\r
643       Certificate containing the CA root key.\r
645    Note that clients may include none, some, or all of the CA root keys\r
646    they possess in this extension.\r
648    Note also that it is possible that a key hash or a Distinguished Name\r
649    alone may not uniquely identify a certificate issuer (for example, if\r
650    a particular CA has multiple key pairs). However, here we assume this\r
651    is the case following the use of Distinguished Names to identify\r
652    certificate issuers in TLS.\r
654    The option to include no CA root keys is included to allow the client\r
655    to indicate possession of some pre-defined set of CA root keys.\r
657    Servers that receive a client hello containing the "trusted_ca_keys"\r
658    extension MAY use the information contained in the extension to guide\r
659    their selection of an appropriate certificate chain to return to the\r
660    client. In this event, the server SHALL include an extension of type\r
661    "trusted_ca_keys" in the (extended) server hello. The\r
662    "extension_data" field of this extension SHALL be empty.\r
666 7. Truncated HMAC\r
668    Currently defined TLS cipher suites use the MAC construction HMAC\r
669    with either MD5 or SHA-1 [RFC2104] to authenticate record layer\r
670    communications. In TLS, the entire output of the hash function is\r
671    used as the MAC tag. However, it may be desirable in constrained\r
672    environments to save bandwidth by truncating the output of the hash\r
673    function to 80 bits when forming MAC tags.\r
675    In order to negotiate the use of 80-bit truncated HMAC, clients MAY\r
676    include an extension of type "truncated_hmac" in the extended client\r
677    hello. The "extension_data" field of this extension SHALL be empty.\r
679    Servers that receive an extended hello containing a "truncated_hmac"\r
680    extension MAY agree to use a truncated HMAC by including an extension\r
681    of type "truncated_hmac", with empty "extension_data", in the\r
684 Donald Eastlake 3rd                                            [Page 12]\r
685 \f\r
686 INTERNET-DRAFT                                 TLS Extension Definitions\r
689    extended server hello.\r
691    Note that if new cipher suites are added that do not use HMAC, and\r
692    the session negotiates one of these cipher suites, this extension\r
693    will have no effect. It is strongly recommended that any new cipher\r
694    suites using other MACs consider the MAC size an integral part of the\r
695    cipher suite definition, taking into account both security and\r
696    bandwidth considerations.\r
698    If HMAC truncation has been successfully negotiated during a TLS\r
699    handshake, and the negotiated cipher suite uses HMAC, both the client\r
700    and the server pass this fact to the TLS record layer along with the\r
701    other negotiated security parameters. Subsequently during the\r
702    session, clients and servers MUST use truncated HMACs, calculated as\r
703    specified in [RFC2104]. That is, SecurityParameters.mac_length is 10\r
704    bytes, and only the first 10 bytes of the HMAC output are transmitted\r
705    and checked. Note that this extension does not affect the calculation\r
706    of the pseudo-random function (PRF) as part of handshaking or key\r
707    derivation.\r
709    The negotiated HMAC truncation size applies for the duration of the\r
710    session including session resumptions.\r
714 8. Certificate Status Request\r
716    Constrained clients may wish to use a certificate-status protocol\r
717    such as OCSP [RFC2560] to check the validity of server certificates,\r
718    in order to avoid transmission of CRLs and therefore save bandwidth\r
719    on constrained networks. This extension allows for such information\r
720    to be sent in the TLS handshake, saving roundtrips and resources.\r
722    In order to indicate their desire to receive certificate status\r
723    information, clients MAY include an extension of type\r
724    "status_request" in the (extended) client hello. The "extension_data"\r
725    field of this extension SHALL contain "CertificateStatusRequest"\r
726    where:\r
728       struct {\r
729           CertificateStatusType status_type;\r
730           select (status_type) {\r
731               case ocsp: OCSPStatusRequest;\r
732           } request;\r
733       } CertificateStatusRequest;\r
735       enum { ocsp(1), (255) } CertificateStatusType;\r
737       struct {\r
738           ResponderID responder_id_list<0..2^16-1>;\r
741 Donald Eastlake 3rd                                            [Page 13]\r
742 \f\r
743 INTERNET-DRAFT                                 TLS Extension Definitions\r
746           Extensions  request_extensions;\r
747       } OCSPStatusRequest;\r
749       opaque ResponderID<1..2^16-1>;\r
750       opaque Extensions<0..2^16-1>;\r
752    In the OCSPStatusRequest, the "ResponderIDs" provides a list of OCSP\r
753    responders that the client trusts. A zero-length "responder_id_list"\r
754    sequence has the special meaning that the responders are implicitly\r
755    known to the server, e.g., by prior arrangement. "Extensions" is a\r
756    DER encoding of OCSP request extensions.\r
758    Both "ResponderID" and "Extensions" are DER-encoded ASN.1 types as\r
759    defined in [RFC2560]. "Extensions" is imported from [RFC3280].  A\r
760    zero-length "request_extensions" value means that there are no\r
761    extensions (as opposed to a zero-length ASN.1 SEQUENCE, which is not\r
762    valid for the "Extensions" type).\r
764    In the case of the "id-pkix-ocsp-nonce" OCSP extension, [RFC2560] is\r
765    unclear about its encoding; for clarification, the nonce MUST be a\r
766    DER-encoded OCTET STRING, which is encapsulated as another OCTET\r
767    STRING (note that implementations based on an existing OCSP client\r
768    will need to be checked for conformance to this requirement).\r
770    Servers that receive a client hello containing the "status_request"\r
771    extension MAY return a suitable certificate status response to the\r
772    client along with their certificate. If OCSP is requested, they\r
773    SHOULD use the information contained in the extension when selecting\r
774    an OCSP responder and SHOULD include request_extensions in the OCSP\r
775    request.\r
777    Servers return a certificate response along with their certificate by\r
778    sending a "CertificateStatus" message immediately after the\r
779    "Certificate" message (and before any "ServerKeyExchange" or\r
780    "CertificateRequest" messages). If a server returns a\r
781    "CertificateStatus" message, then the server MUST have included an\r
782    extension of type "status_request" with empty "extension_data" in the\r
783    extended server hello. The "CertificateStatus" message is conveyed\r
784    using the handshake message type "certificate_status" as follows (see\r
785    also Section 2):\r
787       struct {\r
788           CertificateStatusType status_type;\r
789           select (status_type) {\r
790               case ocsp: OCSPResponse;\r
791           } response;\r
792       } CertificateStatus;\r
794       opaque OCSPResponse<1..2^24-1>;\r
798 Donald Eastlake 3rd                                            [Page 14]\r
799 \f\r
800 INTERNET-DRAFT                                 TLS Extension Definitions\r
803    An "ocsp_response" contains a complete, DER-encoded OCSP response\r
804    (using the ASN.1 type OCSPResponse defined in [RFC2560]).  Only one\r
805    OCSP response may be sent.\r
807    Note that a server MAY also choose not to send a "CertificateStatus"\r
808    message, even if it receives a "status_request" extension in the\r
809    client hello message.\r
811    Note in addition that servers MUST NOT send the "CertificateStatus"\r
812    message unless it received a "status_request" extension in the client\r
813    hello message.\r
815    Clients requesting an OCSP response and receiving an OCSP response in\r
816    a "CertificateStatus" message MUST check the OCSP response and abort\r
817    the handshake if the response is not satisfactory with\r
818    bad_certificate_status_response(113) alert. This alert is always\r
819    fatal.\r
855 Donald Eastlake 3rd                                            [Page 15]\r
856 \f\r
857 INTERNET-DRAFT                                 TLS Extension Definitions\r
860 9. Error Alerts\r
862    This section defines new error alerts for use with the TLS extensions\r
863    defined in this document.\r
865    Four new error alerts are defined.  To avoid "breaking" existing\r
866    clients and servers, these alerts MUST NOT be sent unless the sending\r
867    party has received an extended hello message from the party they are\r
868    communicating with.  These error alerts are conveyed using the\r
869    following syntax:\r
871       enum {\r
872           close_notify(0),\r
873           unexpected_message(10),\r
874           bad_record_mac(20),\r
875           decryption_failed(21),\r
876           record_overflow(22),\r
877           decompression_failure(30),\r
878           handshake_failure(40),\r
879           /* 41 is not defined, for historical reasons */\r
880           bad_certificate(42),\r
881           unsupported_certificate(43),\r
882           certificate_revoked(44),\r
883           certificate_expired(45),\r
884           certificate_unknown(46),\r
885           illegal_parameter(47),\r
886           unknown_ca(48),\r
887           access_denied(49),\r
888           decode_error(50),\r
889           decrypt_error(51),\r
890           export_restriction(60),\r
891           protocol_version(70),\r
892           insufficient_security(71),\r
893           internal_error(80),\r
894           user_canceled(90),\r
895           no_renegotiation(100),\r
896           unsupported_extension(110),\r
897           certificate_unobtainable(111),        /* new */\r
898           unrecognized_name(112),               /* new */\r
899           bad_certificate_status_response(113), /* new */\r
900           bad_certificate_hash_value(114),      /* new */\r
901           (255)\r
902       } AlertDescription;\r
912 Donald Eastlake 3rd                                            [Page 16]\r
913 \f\r
914 INTERNET-DRAFT                                 TLS Extension Definitions\r
917 10. IANA Considerations\r
919    IANA Considerations for TLS Extensions and the creation of a Registry\r
920    therefore are all covered in Section 12 of [RFCTLS]..\r
924 11. Security Considerations\r
926    General Security Considerations for TLS Extensions are covered in\r
927    [RFCTLS]. Security Considerations for particular extensions specified\r
928    in this document are given below.\r
930    In general, implementers should continue to monitor the state of the\r
931    art and address any weaknesses identified.\r
933    Additional security considerations are described in the TLS 1.0 RFC\r
934    [RFC2246] and the TLS 1.1 RFC [RFC4346].\r
938 11.1 Security Considerations for server_name\r
940    If a single server hosts several domains, then clearly it is\r
941    necessary for the owners of each domain to ensure that this satisfies\r
942    their security needs. Apart from this, server_name does not appear to\r
943    introduce significant security issues.\r
945    Implementations MUST ensure that a buffer overflow does not occur,\r
946    whatever the values of the length fields in server_name.\r
948    Although this document specifies an encoding for internationalized\r
949    hostnames in the server_name extension, it does not address any\r
950    security issues associated with the use of internationalized\r
951    hostnames in TLS (in particular, the consequences of "spoofed" names\r
952    that are indistinguishable from another name when displayed or\r
953    printed). It is recommended that server certificates not be issued\r
954    for internationalized hostnames unless procedures are in place to\r
955    mitigate the risk of spoofed hostnames.\r
959 11.2 Security Considerations for max_fragment_length\r
961    The maximum fragment length takes effect immediately, including for\r
962    handshake messages. However, that does not introduce any security\r
963    complications that are not already present in TLS, since TLS requires\r
964    implementations to be able to handle fragmented handshake messages.\r
966    Note that as described in Section 4, once a non-null cipher suite has\r
969 Donald Eastlake 3rd                                            [Page 17]\r
970 \f\r
971 INTERNET-DRAFT                                 TLS Extension Definitions\r
974    been activated, the effective maximum fragment length depends on the\r
975    cipher suite and compression method, as well as on the negotiated\r
976    max_fragment_length. This must be taken into account when sizing\r
977    buffers, and checking for buffer overflow.\r
981 11.3 Security Considerations for client_certificate_url\r
983    There are two major issues with this extension.\r
985    The first major issue is whether or not clients should include\r
986    certificate hashes when they send certificate URLs.\r
988    When client authentication is used *without* the\r
989    client_certificate_url extension, the client certificate chain is\r
990    covered by the Finished message hashes. The purpose of including\r
991    hashes and checking them against the retrieved certificate chain is\r
992    to ensure that the same property holds when this extension is used,\r
993    i.e., that all of the information in the certificate chain retrieved\r
994    by the server is as the client intended.\r
996    On the other hand, omitting certificate hashes enables functionality\r
997    that is desirable in some circumstances; for example, clients can be\r
998    issued daily certificates that are stored at a fixed URL and need not\r
999    be provided to the client. Clients that choose to omit certificate\r
1000    hashes should be aware of the possibility of an attack in which the\r
1001    attacker obtains a valid certificate on the client's key that is\r
1002    different from the certificate the client intended to provide.\r
1003    Although TLS uses both MD5 and SHA-1 hashes in several other places,\r
1004    this was not believed to be necessary here. The property required of\r
1005    SHA-1 is second pre-image resistance.\r
1007    The second major issue is that support for client_certificate_url\r
1008    involves the server's acting as a client in another URL protocol.\r
1009    The server therefore becomes subject to many of the same security\r
1010    concerns that clients of the URL scheme are subject to, with the\r
1011    added concern that the client can attempt to prompt the server to\r
1012    connect to some (possibly weird-looking) URL.\r
1014    In general, this issue means that an attacker might use the server to\r
1015    indirectly attack another host that is vulnerable to some security\r
1016    flaw. It also introduces the possibility of denial of service attacks\r
1017    in which an attacker makes many connections to the server, each of\r
1018    which results in the server's attempting a connection to the target\r
1019    of the attack.\r
1021    Note that the server may be behind a firewall or otherwise able to\r
1022    access hosts that would not be directly accessible from the public\r
1023    Internet. This could exacerbate the potential security and denial of\r
1026 Donald Eastlake 3rd                                            [Page 18]\r
1027 \f\r
1028 INTERNET-DRAFT                                 TLS Extension Definitions\r
1031    service problems described above, as well as allow the existence of\r
1032    internal hosts to be confirmed when they would otherwise be hidden.\r
1034    The detailed security concerns involved will depend on the URL\r
1035    schemes supported by the server. In the case of HTTP, the concerns\r
1036    are similar to those that apply to a publicly accessible HTTP proxy\r
1037    server. In the case of HTTPS, loops and deadlocks may be created, and\r
1038    this should be addressed. In the case of FTP, attacks arise that are\r
1039    similar to FTP bounce attacks.\r
1041    As a result of this issue, it is RECOMMENDED that the\r
1042    client_certificate_url extension should have to be specifically\r
1043    enabled by a server administrator, rather than be enabled by default.\r
1044    It is also RECOMMENDED that URI protocols be enabled by the\r
1045    administrator individually, and only a minimal set of protocols be\r
1046    enabled. Unusual protocols that offer limited security or whose\r
1047    security is not well-understood SHOULD be avoided.\r
1049    As discussed in [RFC3986], URLs that specify ports other than the\r
1050    default may cause problems, as may very long URLs (which are more\r
1051    likely to be useful in exploiting buffer overflow bugs).\r
1053    Also note that HTTP caching proxies are common on the Internet, and\r
1054    some proxies do not check for the latest version of an object\r
1055    correctly. If a request using HTTP (or another caching protocol) goes\r
1056    through a misconfigured or otherwise broken proxy, the proxy may\r
1057    return an out-of-date response.\r
1061 11.4 Security Considerations for trusted_ca_keys\r
1063    It is possible that which CA root keys a client possesses could be\r
1064    regarded as confidential information. As a result, the CA root key\r
1065    indication extension should be used with care.\r
1067    The use of the SHA-1 certificate hash alternative ensures that each\r
1068    certificate is specified unambiguously. As for the previous\r
1069    extension, it was not believed necessary to use both MD5 and SHA-1\r
1070    hashes.\r
1074 11.5 Security Considerations for truncated_hmac\r
1076    It is possible that truncated MACs are weaker than "un-truncated"\r
1077    MACs. However, no significant weaknesses are currently known or\r
1078    expected to exist for HMAC with MD5 or SHA-1, truncated to 80 bits.\r
1080    Note that the output length of a MAC need not be as long as the\r
1083 Donald Eastlake 3rd                                            [Page 19]\r
1084 \f\r
1085 INTERNET-DRAFT                                 TLS Extension Definitions\r
1088    length of a symmetric cipher key, since forging of MAC values cannot\r
1089    be done off-line: in TLS, a single failed MAC guess will cause the\r
1090    immediate termination of the TLS session.\r
1092    Since the MAC algorithm only takes effect after all handshake\r
1093    messages that affect extension parameters have been authenticated by\r
1094    the hashes in the Finished messages, it is not possible for an active\r
1095    attacker to force negotiation of the truncated HMAC extension where\r
1096    it would not otherwise be used (to the extent that the handshake\r
1097    authentication is secure). Therefore, in the event that any security\r
1098    problem were found with truncated HMAC in the future, if either the\r
1099    client or the server for a given session were updated to take the\r
1100    problem into account, it would be able to veto use of this extension.\r
1104 11.6 Security Considerations for status_request\r
1106    If a client requests an OCSP response, it must take into account that\r
1107    an attacker's server using a compromised key could (and probably\r
1108    would) pretend not to support the extension. In this case, a client\r
1109    that requires OCSP validation of certificates SHOULD either contact\r
1110    the OCSP server directly or abort the handshake.\r
1112    Use of the OCSP nonce request extension (id-pkix-ocsp-nonce) may\r
1113    improve security against attacks that attempt to replay OCSP\r
1114    responses; see Section 4.4.1 of [RFC2560] for further details.\r
1140 Donald Eastlake 3rd                                            [Page 20]\r
1141 \f\r
1142 INTERNET-DRAFT                                 TLS Extension Definitions\r
1145 12. Normative References\r
1147    [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-\r
1148    Hashing for Message Authentication", RFC 2104, February 1997.\r
1150    [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate\r
1151    Requirement Levels", BCP 14, RFC 2119, March 1997.\r
1153    [RFC2560] Myers, M., Ankney, R., Malpani, A., Galperin, S., and C.\r
1154    Adams, "X.509 Internet Public Key Infrastructure Online Certificate\r
1155    Status Protocol - OCSP", RFC 2560, June 1999.\r
1157    [RFC2585] Housley, R. and P. Hoffman, "Internet X.509 Public Key\r
1158    Infrastructure Operational Protocols: FTP and HTTP", RFC 2585, May\r
1159    1999.\r
1161    [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter,\r
1162    L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol --\r
1163    HTTP/1.1", RFC 2616, June 1999.\r
1165    [RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet\r
1166    X.509 Public Key Infrastructure Certificate and Certificate\r
1167    Revocation List (CRL) Profile", RFC 3280, April 2002.\r
1169    [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform\r
1170    Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January\r
1171    2005.\r
1173    [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security\r
1174    (TLS) Protocol Version 1.1", RFC 4346, April 2006.\r
1176    [RFCTLS] Dierks, T. and E. Rescorla, "The TLS Protocol Version 1.2",\r
1177    draft-ietf-tls-rfc4346-bis-*.txt, March 2007.\r
1181 13. Informative References\r
1183    [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",\r
1184    RFC 2246, January 1999.\r
1186    [RFC2712] Medvinsky, A. and M. Hur, "Addition of Kerberos Cipher\r
1187    Suites to Transport Layer Security (TLS)", RFC 2712, October 1999.\r
1189    [RFC3268] Chown, P., "Advanced Encryption Standard (AES) Ciphersuites\r
1190    for Transport Layer Security (TLS)", RFC 3268, June 2002.\r
1192    [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J.,\r
1193    and T. Wright, "Transport Layer Security (TLS) Extensions", RFC 4366,\r
1194    April 2006.\r
1197 Donald Eastlake 3rd                                            [Page 21]\r
1198 \f\r
1199 INTERNET-DRAFT                                 TLS Extension Definitions\r
1202 Copyright, Disclaimer, and Additional IPR Provisions\r
1204    Copyright (C) The IETF Trust (2008).\r
1206    This document is subject to the rights, licenses and restrictions\r
1207    contained in BCP 78, and except as set forth therein, the authors\r
1208    retain all their rights.\r
1211    This document and the information contained herein are provided on an\r
1212    "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS\r
1213    OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND\r
1214    THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS\r
1215    OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF\r
1216    THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED\r
1217    WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.\r
1219    The IETF takes no position regarding the validity or scope of any\r
1220    Intellectual Property Rights or other rights that might be claimed to\r
1221    pertain to the implementation or use of the technology described in\r
1222    this document or the extent to which any license under such rights\r
1223    might or might not be available; nor does it represent that it has\r
1224    made any independent effort to identify any such rights.  Information\r
1225    on the procedures with respect to rights in RFC documents can be\r
1226    found in BCP 78 and BCP 79.\r
1228    Copies of IPR disclosures made to the IETF Secretariat and any\r
1229    assurances of licenses to be made available, or the result of an\r
1230    attempt made to obtain a general license or permission for the use of\r
1231    such proprietary rights by implementers or users of this\r
1232    specification can be obtained from the IETF on-line IPR repository at\r
1233    http://www.ietf.org/ipr.\r
1235    The IETF invites any interested party to bring to its attention any\r
1236    copyrights, patents or patent applications, or other proprietary\r
1237    rights that may cover technology that may be required to implement\r
1238    this standard.  Please address the information to the IETF at ietf-\r
1239    ipr@ietf.org.\r
1254 Donald Eastlake 3rd                                            [Page 22]\r
1255 \f\r
1256 INTERNET-DRAFT                                 TLS Extension Definitions\r
1259 Author's Address\r
1261    Donald Eastlake 3rd\r
1262    Motorola Laboratories\r
1263    111 Locke Drive\r
1264    Marlborough, MA 01752\r
1266    Tel:   +1-508-786-7554\r
1267    Email: Donald.Eastlake@motorola.com\r
1271 Expiration and File Name\r
1273    This draft expires in August 2008.\r
1275    Its file name is draft-ietf-tls-rfc4366-bis-02.txt.\r
1311 Donald Eastlake 3rd                                            [Page 23]\r
1312 \f\r