3. Specific Extensions
This section describes the specific TLS extensions specified in this
document.
Note that any messages associated with these extensions that are sent
during the TLS handshake MUST be included in the hash calculations
involved in "Finished" messages.
Note also that all the extensions defined in this section are
relevant only when a session is initiated. When a client includes
one or more of the defined extension types in an extended client
hello while requesting session resumption:
- If the resumption request is denied, the use of the extensions is
negotiated as normal.
- If, on the other hand, the older session is resumed, then the
server MUST ignore the extensions and send a server hello
containing none of the extension types. In this case, the
functionality of these extensions negotiated during the original
session initiation is applied to the resumed session.
Section 3.1 describes the extension of TLS to allow a client to
indicate which server it is contacting. Section 3.2 describes the
extension that provides maximum fragment length negotiation. Section
3.3 describes the extension that allows client certificate URLs.
Section 3.4 describes the extension that allows a client to indicate
which CA root keys it possesses. Section 3.5 describes the extension
that allows the use of truncated HMAC. Section 3.6 describes the
extension that supports integration of certificate status information
messages into TLS handshakes.
TLS does not provide a mechanism for a client to tell a server the
name of the server it is contacting. It may be desirable for clients
to provide this information to facilitate secure connections to
servers that host multiple 'virtual' servers at a single underlying
network address.
In order to provide the server name, clients MAY include an extension
of type "server_name" in the (extended) client hello. The
"extension_data" field of this extension SHALL contain
"ServerNameList" where:
struct {
NameType name_type;
select (name_type) {
case host_name: HostName;
} name;
} ServerName;
enum {
host_name(0), (255)
} NameType;
opaque HostName<1..2^16-1>;
struct {
ServerName server_name_list<1..2^16-1>
} ServerNameList;
Currently, the only server names supported are DNS hostnames;
however, this does not imply any dependency of TLS on DNS, and other
name types may be added in the future (by an RFC that updates this
document). TLS MAY treat provided server names as opaque data and
pass the names and types to the application.
"HostName" contains the fully qualified DNS hostname of the server,
as understood by the client. The hostname is represented as a byte
string using UTF-8 encoding [UTF8], without a trailing dot.
If the hostname labels contain only US-ASCII characters, then the
client MUST ensure that labels are separated only by the byte 0x2E,
representing the dot character U+002E (requirement 1 in Section 3.1
of [IDNA] notwithstanding). If the server needs to match the
HostName against names that contain non-US-ASCII characters, it MUST
perform the conversion operation described in Section 4 of [IDNA],
treating the HostName as a "query string" (i.e., the AllowUnassigned
flag MUST be set). Note that IDNA allows labels to be separated by
any of the Unicode characters U+002E, U+3002, U+FF0E, and U+FF61;
therefore, servers MUST accept any of these characters as a label
separator. If the server only needs to match the HostName against
names containing exclusively ASCII characters, it MUST compare ASCII
names case-insensitively.
Literal IPv4 and IPv6 addresses are not permitted in "HostName".
It is RECOMMENDED that clients include an extension of type
"server_name" in the client hello whenever they locate a server by a
supported name type.
A server that receives a client hello containing the "server_name"
extension MAY use the information contained in the extension to guide
its selection of an appropriate certificate to return to the client,
and/or other aspects of security policy. In this event, the server
SHALL include an extension of type "server_name" in the (extended)
server hello. The "extension_data" field of this extension SHALL be
empty.
If the server understood the client hello extension but does not
recognize the server name, it SHOULD send an "unrecognized_name"
alert (which MAY be fatal).
If an application negotiates a server name using an application
protocol and then upgrades to TLS, and if a server_name extension is
sent, then the extension SHOULD contain the same name that was
negotiated in the application protocol. If the server_name is
established in the TLS session handshake, the client SHOULD NOT
attempt to request a different server name at the application layer.
Without this extension, TLS specifies a fixed maximum plaintext
fragment length of 2^14 bytes. It may be desirable for constrained
clients to negotiate a smaller maximum fragment length due to memory
limitations or bandwidth limitations.
In order to negotiate smaller maximum fragment lengths, clients MAY
include an extension of type "max_fragment_length" in the (extended)
client hello. The "extension_data" field of this extension SHALL
contain:
enum{
2^9(1), 2^10(2), 2^11(3), 2^12(4), (255)
} MaxFragmentLength;
whose value is the desired maximum fragment length. The allowed
values for this field are: 2^9, 2^10, 2^11, and 2^12.
Servers that receive an extended client hello containing a
"max_fragment_length" extension MAY accept the requested maximum
fragment length by including an extension of type
"max_fragment_length" in the (extended) server hello. The
"extension_data" field of this extension SHALL contain a
"MaxFragmentLength" whose value is the same as the requested maximum
fragment length.
If a server receives a maximum fragment length negotiation request
for a value other than the allowed values, it MUST abort the
handshake with an "illegal_parameter" alert. Similarly, if a client
receives a maximum fragment length negotiation response that differs
from the length it requested, it MUST also abort the handshake with
an "illegal_parameter" alert.
Once a maximum fragment length other than 2^14 has been successfully
negotiated, the client and server MUST immediately begin fragmenting
messages (including handshake messages), to ensure that no fragment
larger than the negotiated length is sent. Note that TLS already
requires clients and servers to support fragmentation of handshake
messages.
The negotiated length applies for the duration of the session
including session resumptions.
The negotiated length limits the input that the record layer may
process without fragmentation (that is, the maximum value of
TLSPlaintext.length; see [TLS], Section 6.2.1). Note that the output
of the record layer may be larger. For example, if the negotiated
length is 2^9=512, then for currently defined cipher suites (those
defined in [TLS], [KERB], and [AESSUITES]), and when null compression
is used, the record layer output can be at most 793 bytes: 5 bytes of
headers, 512 bytes of application data, 256 bytes of padding, and 20
bytes of MAC. This means that in this event a TLS record layer peer
receiving a TLS record layer message larger than 793 bytes may
discard the message and send a "record_overflow" alert, without
decrypting the message.
Without this extension, TLS specifies that when client authentication
is performed, client certificates are sent by clients to servers
during the TLS handshake. It may be desirable for constrained
clients to send certificate URLs in place of certificates, so that
they do not need to store their certificates and can therefore save
memory.
In order to negotiate sending certificate URLs to a server, clients
MAY include an extension of type "client_certificate_url" in the
(extended) client hello. The "extension_data" field of this
extension SHALL be empty.
(Note that it is necessary to negotiate use of client certificate
URLs in order to avoid "breaking" existing TLS servers.)
Servers that receive an extended client hello containing a
"client_certificate_url" extension MAY indicate that they are willing
to accept certificate URLs by including an extension of type
"client_certificate_url" in the (extended) server hello. The
"extension_data" field of this extension SHALL be empty.
After negotiation of the use of client certificate URLs has been
successfully completed (by exchanging hellos including
"client_certificate_url" extensions), clients MAY send a
"CertificateURL" message in place of a "Certificate" message:
enum {
individual_certs(0), pkipath(1), (255)
} CertChainType;
enum {
false(0), true(1)
} Boolean;
struct {
CertChainType type;
URLAndOptionalHash url_and_hash_list<1..2^16-1>;
} CertificateURL;
struct {
opaque url<1..2^16-1>;
Boolean hash_present;
select (hash_present) {
case false: struct {};
case true: SHA1Hash;
} hash;
} URLAndOptionalHash;
opaque SHA1Hash[20];
Here "url_and_hash_list" contains a sequence of URLs and optional
hashes.
When X.509 certificates are used, there are two possibilities:
- If CertificateURL.type is "individual_certs", each URL refers to a
single DER-encoded X.509v3 certificate, with the URL for the
client's certificate first.
- If CertificateURL.type is "pkipath", the list contains a single
URL referring to a DER-encoded certificate chain, using the type
PkiPath described in Section 8.
When any other certificate format is used, the specification that
describes use of that format in TLS should define the encoding format
of certificates or certificate chains, and any constraint on their
ordering.
The hash corresponding to each URL at the client's discretion either
is not present or is the SHA-1 hash of the certificate or certificate
chain (in the case of X.509 certificates, the DER-encoded certificate
or the DER-encoded PkiPath).
Note that when a list of URLs for X.509 certificates is used, the
ordering of URLs is the same as that used in the TLS Certificate
message (see [TLS], Section 7.4.2), but opposite to the order in
which certificates are encoded in PkiPath. In either case, the
self-signed root certificate MAY be omitted from the chain, under the
assumption that the server must already possess it in order to
validate it.
Servers receiving "CertificateURL" SHALL attempt to retrieve the
client's certificate chain from the URLs and then process the
certificate chain as usual. A cached copy of the content of any URL
in the chain MAY be used, provided that a SHA-1 hash is present for
that URL and it matches the hash of the cached copy.
Servers that support this extension MUST support the http: URL scheme
for certificate URLs, and MAY support other schemes. Use of other
schemes than "http", "https", or "ftp" may create unexpected
problems.
If the protocol used is HTTP, then the HTTP server can be configured
to use the Cache-Control and Expires directives described in [HTTP]
to specify whether and for how long certificates or certificate
chains should be cached.
The TLS server is not required to follow HTTP redirects when
retrieving the certificates or certificate chain. The URLs used in
this extension SHOULD therefore be chosen not to depend on such
redirects.
If the protocol used to retrieve certificates or certificate chains
returns a MIME-formatted response (as HTTP does), then the following
MIME Content-Types SHALL be used: when a single X.509v3 certificate
is returned, the Content-Type is "application/pkix-cert" [PKIOP], and
when a chain of X.509v3 certificates is returned, the Content-Type is
"application/pkix-pkipath" (see Section 8).
If a SHA-1 hash is present for an URL, then the server MUST check
that the SHA-1 hash of the contents of the object retrieved from that
URL (after decoding any MIME Content-Transfer-Encoding) matches the
given hash. If any retrieved object does not have the correct SHA-1
hash, the server MUST abort the handshake with a
"bad_certificate_hash_value" alert.
Note that clients may choose to send either "Certificate" or
"CertificateURL" after successfully negotiating the option to send
certificate URLs. The option to send a certificate is included to
provide flexibility to clients possessing multiple certificates.
If a server encounters an unreasonable delay in obtaining
certificates in a given CertificateURL, it SHOULD time out and signal
a "certificate_unobtainable" error alert.
Constrained clients that, due to memory limitations, possess only a
small number of CA root keys may wish to indicate to servers which
root keys they possess, in order to avoid repeated handshake
failures.
In order to indicate which CA root keys they possess, clients MAY
include an extension of type "trusted_ca_keys" in the (extended)
client hello. The "extension_data" field of this extension SHALL
contain "TrustedAuthorities" where:
struct {
TrustedAuthority trusted_authorities_list<0..2^16-1>;
} TrustedAuthorities;
struct {
IdentifierType identifier_type;
select (identifier_type) {
case pre_agreed: struct {};
case key_sha1_hash: SHA1Hash;
case x509_name: DistinguishedName;
case cert_sha1_hash: SHA1Hash;
} identifier;
} TrustedAuthority;
enum {
pre_agreed(0), key_sha1_hash(1), x509_name(2),
cert_sha1_hash(3), (255)
} IdentifierType;
opaque DistinguishedName<1..2^16-1>;
Here "TrustedAuthorities" provides a list of CA root key identifiers
that the client possesses. Each CA root key is identified via
either:
- "pre_agreed": no CA root key identity supplied.
- "key_sha1_hash": contains the SHA-1 hash of the CA root key. For
Digital Signature Algorithm (DSA) and Elliptic Curve Digital
Signature Algorithm (ECDSA) keys, this is the hash of the
"subjectPublicKey" value. For RSA keys, the hash is of the big-
endian byte string representation of the modulus without any
initial 0-valued bytes. (This copies the key hash formats
deployed in other environments.)
- "x509_name": contains the DER-encoded X.509 DistinguishedName of
the CA.
- "cert_sha1_hash": contains the SHA-1 hash of a DER-encoded
Certificate containing the CA root key.
Note that clients may include none, some, or all of the CA root keys
they possess in this extension.
Note also that it is possible that a key hash or a Distinguished Name
alone may not uniquely identify a certificate issuer (for example, if
a particular CA has multiple key pairs). However, here we assume
this is the case following the use of Distinguished Names to identify
certificate issuers in TLS.
The option to include no CA root keys is included to allow the client
to indicate possession of some pre-defined set of CA root keys.
Servers that receive a client hello containing the "trusted_ca_keys"
extension MAY use the information contained in the extension to guide
their selection of an appropriate certificate chain to return to the
client. In this event, the server SHALL include an extension of type
"trusted_ca_keys" in the (extended) server hello. The
"extension_data" field of this extension SHALL be empty.
Currently defined TLS cipher suites use the MAC construction HMAC
with either MD5 or SHA-1 [HMAC] to authenticate record layer
communications. In TLS, the entire output of the hash function is
used as the MAC tag. However, it may be desirable in constrained
environments to save bandwidth by truncating the output of the hash
function to 80 bits when forming MAC tags.
In order to negotiate the use of 80-bit truncated HMAC, clients MAY
include an extension of type "truncated_hmac" in the extended client
hello. The "extension_data" field of this extension SHALL be empty.
Servers that receive an extended hello containing a "truncated_hmac"
extension MAY agree to use a truncated HMAC by including an extension
of type "truncated_hmac", with empty "extension_data", in the
extended server hello.
Note that if new cipher suites are added that do not use HMAC, and
the session negotiates one of these cipher suites, this extension
will have no effect. It is strongly recommended that any new cipher
suites using other MACs consider the MAC size an integral part of the
cipher suite definition, taking into account both security and
bandwidth considerations.
If HMAC truncation has been successfully negotiated during a TLS
handshake, and the negotiated cipher suite uses HMAC, both the client
and the server pass this fact to the TLS record layer along with the
other negotiated security parameters. Subsequently during the
session, clients and servers MUST use truncated HMACs, calculated as
specified in [HMAC]. That is, CipherSpec.hash_size is 10 bytes, and
only the first 10 bytes of the HMAC output are transmitted and
checked. Note that this extension does not affect the calculation of
the pseudo-random function (PRF) as part of handshaking or key
derivation.
The negotiated HMAC truncation size applies for the duration of the
session including session resumptions.
Constrained clients may wish to use a certificate-status protocol
such as OCSP [OCSP] to check the validity of server certificates, in
order to avoid transmission of CRLs and therefore save bandwidth on
constrained networks. This extension allows for such information to
be sent in the TLS handshake, saving roundtrips and resources.
In order to indicate their desire to receive certificate status
information, clients MAY include an extension of type
"status_request" in the (extended) client hello. The
"extension_data" field of this extension SHALL contain
"CertificateStatusRequest" where:
struct {
CertificateStatusType status_type;
select (status_type) {
case ocsp: OCSPStatusRequest;
} request;
} CertificateStatusRequest;
enum { ocsp(1), (255) } CertificateStatusType;
struct {
ResponderID responder_id_list<0..2^16-1>;
Extensions request_extensions;
} OCSPStatusRequest;
opaque ResponderID<1..2^16-1>;
opaque Extensions<0..2^16-1>;
In the OCSPStatusRequest, the "ResponderIDs" provides a list of OCSP
responders that the client trusts. A zero-length "responder_id_list"
sequence has the special meaning that the responders are implicitly
known to the server, e.g., by prior arrangement. "Extensions" is a
DER encoding of OCSP request extensions.
Both "ResponderID" and "Extensions" are DER-encoded ASN.1 types as
defined in [OCSP]. "Extensions" is imported from [PKIX]. A zero-
length "request_extensions" value means that there are no extensions
(as opposed to a zero-length ASN.1 SEQUENCE, which is not valid for
the "Extensions" type).
In the case of the "id-pkix-ocsp-nonce" OCSP extension, [OCSP] is
unclear about its encoding; for clarification, the nonce MUST be a
DER-encoded OCTET STRING, which is encapsulated as another OCTET
STRING (note that implementations based on an existing OCSP client
will need to be checked for conformance to this requirement).
Servers that receive a client hello containing the "status_request"
extension MAY return a suitable certificate status response to the
client along with their certificate. If OCSP is requested, they
SHOULD use the information contained in the extension when selecting
an OCSP responder and SHOULD include request_extensions in the OCSP
request.
Servers return a certificate response along with their certificate by
sending a "CertificateStatus" message immediately after the
"Certificate" message (and before any "ServerKeyExchange" or
"CertificateRequest" messages). If a server returns a
"CertificateStatus" message, then the server MUST have included an
extension of type "status_request" with empty "extension_data" in the
extended server hello.
struct {
CertificateStatusType status_type;
select (status_type) {
case ocsp: OCSPResponse;
} response;
} CertificateStatus;
opaque OCSPResponse<1..2^24-1>;
An "ocsp_response" contains a complete, DER-encoded OCSP response
(using the ASN.1 type OCSPResponse defined in [OCSP]). Note that
only one OCSP response may be sent.
The "CertificateStatus" message is conveyed using the handshake
message type "certificate_status".
Note that a server MAY also choose not to send a "CertificateStatus"
message, even if it receives a "status_request" extension in the
client hello message.
Note in addition that servers MUST NOT send the "CertificateStatus"
message unless it received a "status_request" extension in the client
hello message.
Clients requesting an OCSP response and receiving an OCSP response in
a "CertificateStatus" message MUST check the OCSP response and abort
the handshake if the response is not satisfactory.
