Network Working Group D. Migault Internet-Draft Ericsson Intended status: Standards Track February 19, 2016 Expires: August 22, 2016 TLS/DTLS Content Provider Edge Server Abstract API draft-mglt-lurk-tls-abstract-api-00 Abstract This document describes the interactions between the Edge Server and the Content Provider in a split authentication scenario. This document provides an abstract description of the information exchanged between an Edge Server and a Content Provider. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on August 22, 2016. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Migault Expires August 22, 2016 [Page 1] Internet-Draft TLS abstract API February 2016 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 3 3.1. Premaster Computation . . . . . . . . . . . . . . . . . . 5 3.2. Master Computation . . . . . . . . . . . . . . . . . . . 6 3.3. Signature Computation . . . . . . . . . . . . . . . . . . 8 4. Input Parameters Description . . . . . . . . . . . . . . . . 9 4.1. Static parameters . . . . . . . . . . . . . . . . . . . . 10 4.1.1. API Version . . . . . . . . . . . . . . . . . . . . . 10 4.1.2. TLSVersion . . . . . . . . . . . . . . . . . . . . . 10 4.1.3. ObjectRequest . . . . . . . . . . . . . . . . . . . . 10 4.1.4. AuthenticationMethod . . . . . . . . . . . . . . . . 10 4.1.5. MasterMethod . . . . . . . . . . . . . . . . . . . . 10 4.1.6. SignatureMethod . . . . . . . . . . . . . . . . . . . 10 4.1.7. PRF . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2. TLS Hanshake parameters . . . . . . . . . . . . . . . . . 11 4.2.1. ClientHello.random, ClientServer.random . . . . . . . 11 4.2.2. session_hash, DataHash . . . . . . . . . . . . . . . 11 4.2.3. handshake_messages . . . . . . . . . . . . . . . . . 11 4.2.4. PSK_ID . . . . . . . . . . . . . . . . . . . . . . . 11 4.3. Cryptographic Parameters . . . . . . . . . . . . . . . . 11 4.3.1. RSAEncryptedPreMaster . . . . . . . . . . . . . . . . 11 4.3.2. DHECDHTLSClientPublicDHECDHKey . . . . . . . . . . . 13 4.3.3. TLSClientEdgeServerDHSecret . . . . . . . . . . . . . 13 4.3.4. TLSClientEdgeServerDHECDHSecret . . . . . . . . . . . 13 5. Output Parameters Description . . . . . . . . . . . . . . . . 13 5.1. Premaster . . . . . . . . . . . . . . . . . . . . . . . . 13 5.2. Signature . . . . . . . . . . . . . . . . . . . . . . . . 13 5.3. Error . . . . . . . . . . . . . . . . . . . . . . . . . . 13 6. Security Considerations . . . . . . . . . . . . . . . . . . . 14 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 14 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 14 1. Introduction This document assumes a TLS session is established between a TLS Client authenticates a Content Provider while being connected with an TLS Edge Server. The architecture is defined more in details in [draft-cairns-tls- session-key-interface], and the split authentication models are described in [draft-mglt-tls-lurk-requirements]. Motivation for providing an abstract API is to to provide a reference that may be implemented in various ways. As a result, this document Migault Expires August 22, 2016 [Page 2] Internet-Draft TLS abstract API February 2016 does not consider the names of the procedures, their implementations, nor how the informations are exchanged between the Edge Server and the Content Provider. This document only describes the information exchanged between the Edge Server and the Content Provider and the associated treatment or verifications that may apply. 2. Terminology 3. Protocol Overview In a split authentication scenario, the Edge Server and the Content Provider needs to interact in order to set up the TLS/DTLS session between the TLS Client and the Edge Server while the TLS Client authenticates the Content Provider. The current document considers the following authentication methods: dhe_dss, dhe_rsa, dh_anon, rsa, dh_dss and dh_rsa described in [RFC6347], ecdh_ecdsa, ecdhe_ecdsa, ecdh_rsa, ecdhe_rsa and ecdh_anon described in [RFC4492] as well as psk, dhe_psk and rsa_psk that are described in [RFC4279]. These authentication methods are designated in this document by the AuthenticationMethod variable. AuthenticationMethod = [rsa, dh_dss, dh_rsa, dh_dss, dh_rsa, ecdh_rsa, dh_anon, ecdh_anon, dhe_dss, dhe_rsa, ecdhe_ecdsa, ecdhe_rsa, psk, dhe_psk, rsa_psk] AuthenticationMethod The interactions between the Edge Server and the Content Provider depend on the authentication method. First of all, the object request, designated in this document as ObjectRequest, depends on the authentication method. When the authentication methods is one of rsa, dh_dss, dh_rsa rsa, dh_dss, dh_rsa, ecdh_rsa, the Content Provider is likely to be requested by the Edge Server a premaster secret or a master secret. When the authentication method is an ephemeral Diffie Hellman or ephemeral Elliptic Diffie Hellman authentication methods like dhe_dss, dhe_rsa, ecdhe_ecdsa, ecdhe_rsa, the Content Provider is likely to be requested a signature. When the authentication method is an anonymous authentication method like dh_anon, ecdh_anon no interactions are expected from the Content Provider and the Edge Server. Finally, when the authentication method is PSK based, the Content provider is likely to be requested a master secret but not the premaster secret as the premaster contains the PSK in clear text. Migault Expires August 22, 2016 [Page 3] Internet-Draft TLS abstract API February 2016 Second, the object of the request like a master secret or the signature may be generated with different inputs. For example, a signature or a master secret may use the hash of some clear text. The different inputs provided by the Edge Server are designated as InputParameters. Finally, the Content provider may have its own policies regarding the TLS version, the authentication methods, the object request as well as the associated inputs. This means that the Content Provider may refuse some request defined in this document based on its own policies. This should be indicated in an error message by the Content provider in its response. As a result, the basic scheme considered for this API adopts a Query / Response pattern. The Query message provides all necessary information for the Content Provider, to proceed to the Query, and send the output result in the Response. Query: APIVersion = 1.0 TLSVersion = [1.2, 1.3] ObjectRequest = [premaster, master, signature] InputParameters Response: Output [PreMaster, Master, Signature, Error] API Query / Response The Query is associated with the following parameters: (a) APIVersion: which designates the version of the API used. The version is expected to be useful when the authentication methods or TLS version will be added. (b) TLSVersion: the associated version of the TLS. (c) ObjectRequest: the requested output. Currently the requested output can be one of the following: pre_master, master, signature. (d) InputParameters: the parameters provided by the Edge Server in order to compute the ObjectRequest. These InputParameters will be defined in the remaining of the document, and are very specific to each Query. The Response returns the ObjectRequest or an Error. When an Error is returned it SHOULD provide some indication why the request have not been proceeded. Note that the types of errors are: Migault Expires August 22, 2016 [Page 4] Internet-Draft TLS abstract API February 2016 (a) Input Format Parameter Errors: that is errors associated to the format of a given parameter. For example a TLS version that is out of bound, or a Client,random that does not have the expected size would trigger such an error. (b) Input Parameters Incompatibility Error: that is a combination of input parameters that is not acceptable on a standard point of view. This could be for example requesting a signature with an authentication method that is expected to provide a master secret. (c) Not Permitted Input Parameters Error: that is a combination of parameters that is either not accepted by the Content Provider, or not implemented by the API. For example, the Content Provider may only generate signature from the complete clear text and refuse to generate it simply based on the hash of the content. InpuParameters depends on the ObjectRequest value, so the InputParameters can be: (a) PremasterInputParams: when the query requests a premaster, that is ObjectRequest is set to premaster. (b) MasterInputParams: when the query requests a master secret, that is ObjectRequest is set to master. (c) SignatureInputParams: when the query requests a signature, that is the ObjectRequest is set to signature. InputParameters: select(ObjectRequest) case pre_master: PremasterInputParams case master: MasterInputParams case signature: SignatureInputParams InpuParameters 3.1. Premaster Computation A premaster may be requested only for a subset of authentication methods, that is RSA and non anonymous Diffie Helmman based methods. In the case of RSA, the encrypted premaster is provided whereas Diffie Hellman based authentication provides the TLS Client public key. When another authentication method is associated to the premaster request an Input Parameters Incompatibility Error must be sent Migault Expires August 22, 2016 [Page 5] Internet-Draft TLS abstract API February 2016 indicating that the authentication method is not compatible with the premaster request. (a) INCOMPATIBLE_INPUT_PARAMETERS_ERROR In order to indicate the error is associated to the authentication method the two following error message are added. Note that an unacceptable error may occur when there is a incompatibility between the parameters. This can occur due to local policies or due to an incompatibility with the specification. It is the responsibility of the Edge Server to implement the specification properly, and thus to receive the error only when it results from a local policy. AUTHENTICATION_METHOD_UNACCEPTABLE_ERROR The description of the input parameters are provide by the figure below: PreMasterInputParams - AuthenticationMethod - PreMasterInputData PreMasterInputData: select(AuthenticationMethod) case rsa: RSAEncryptedPreMaster case dh_dss, dh_rsa, dh_dss, dh_rsa, ecdh_rsa: DHECDHTLSClientPublicDHECDHKey case dhe_dss, dhe_rsa, ecdhe_ecdsa, ecdhe_rsa, psk, dhe_psk and rsa_psk: /* Input Parameters Incompatibility Error INCOMPATIBLE_INPUT_PARAMETERS_ERROR AUTHENTICATION_METHOD_UNACCEPTABLE_ERROR is generated */ PreMasterInputParams 3.2. Master Computation The computation of a master secret needs more information than the computation of the premaster. Similarly to the premaster generation, generation of a master secret is reserved to a subset of authentication methods. Note that the PSK based authentication methods are able to generate master secret but not to generate premaster. The reason is that the premaster embeds the PSK in clear text. Migault Expires August 22, 2016 [Page 6] Internet-Draft TLS abstract API February 2016 Similarly to the premaster generation, when an authentication method is not permitted an Input Parameters Incompatibility Error INCOMPATIBLE_INPUT_PARAMETERS_ERROR with and AUTHENTICATION_METHOD_UNACCEPTABLE_ERROR are returned. As premaster are used to compute the master, when a authentication method enable the generation of the premaster the same input parameters must be also provided to the Content Provider. Master secret may be generated using different methods and using different inputs. More specifically, the extended master secret may be generated from the hash of the exchange messages, or the exchange message themselves. The figure below represent a method by the type of the master secret (that is the standard master secret or the extended master secret) as well as the expected inputs. Such representation is not normative and provided for illustration. As a result, alternative representation may be used. MasterInputParams AuthenticationMethod MasterMethod = [standard_master, extended_master_from_session_hash, extended_master_method_from_handshake_messages] MasterInputData MasterInputData select(AuthenticationMethod) case rsa: MasterMethodParams RSAEncryptedPreMaster case dh-scdh: MasterMethodParams DHECDHTLSClientPublicDHECDHKey case dhe_dss, dhe_rsa, ecdhe_ecdsa, dh_anon, ecdh_anon ecdhe_rsa, psk /* Input Parameters Incompatibility Error INCOMPATIBLE_INPUT_PARAMETERS_ERROR AUTHENTICATION_METHOD_UNACCEPTABLE_ERROR is generated */ case psk, dhe_psk, rsa_psk: PSKInputData MasterMethodParams select(MasterMethod) case standard_master: - ClientHello.random Migault Expires August 22, 2016 [Page 7] Internet-Draft TLS abstract API February 2016 - ClientServer.random - PRF case extended_master_from_session_hash - session_hash - PRF case extended_master_method_from_handshake_messages - handshake_messages - PRF PSKInputData select(PSKSubAuthenticationMethod) case psk: - PSK_ID case PSK_rsa: - RSAEncryptedPreMaster case psk_dhe: - TLSClientEdgeServerDHSecret - PSK_ID MasterInputParams 3.3. Signature Computation Similarly to the generation of the premaster and the generation of the master, the signature is associated to restricted subset of authentication methods, i.e. dhe_dss, dhe_rsa, ecdhe_ecdsa ecdhe_rsa. When another authentication method is chosen an Input Parameters Incompatibility Error INCOMPATIBLE_INPUT_PARAMETERS_ERROR with an AUTHENTICATION_METHOD_UNACCEPTABLE_ERROR are returned. Similarly to the generation of the master, different method may be used to generate the signature and different parameters may be needed to generate the signature. In some case, the hash is provided whereas in some other case, the whole content to sign is provided. The figure below provides a representation of the possible parameters provided by the Edge Server. Migault Expires August 22, 2016 [Page 8] Internet-Draft TLS abstract API February 2016 SignatureInputParams AuthenticationMethod SignatureMethod = (CryptoAlgo = [dss, rsa, ecdsa], DataType = [hash, content]) SignatureInputData SignatureInputData select(AuthenticationMethod) case dhe_dss, dhe_rsa, ecdhe_ecdsa ecdhe_rsa: SignatureInputData case rsa, dh_dss, dh_rsa, dh_dss, dh_rsa, ecdh_rsa, dh_anon, ecdh_anon, psk, dhe_psk, rsa_psk: /* Input Parameters Incompatibility Error INCOMPATIBLE_INPUT_PARAMETERS_ERROR AUTHENTICATION_METHOD_UNACCEPTABLE_ERROR is generated */ SignatureInput select(SignatureMethod.DataType) case hash: - DataHash case content: - ClientHello.random - ClientServer.random - TLSClientEdgeServerDHECDHSecret MasterInputParams 4. Input Parameters Description This section lists the possible parameters exchanged between the Edge Server and the Content Provider. For each parameters, this section determine what checks and error may be associated to them and communicated to the Edge Server. In order to address the different errors, for each input, there is an associated Input Format Parameter Errors that indicates the input does not follow the format expected in this document. In addition, there is an Not Permitted Input Parameters Error that indicates the API does not support the provided input. This is mostly due to local policies. In addition, the local policies may also prevent a given input value in combination with other input values. In this case, the error returned by the Content Provider is an Input Parameters Incompatibility Error INCOMPATIBLE_INPUT_PARAMETERS_ERROR with the Not Permitted Input Parameters Error associated to the conflicting parameters. Migault Expires August 22, 2016 [Page 9] Internet-Draft TLS abstract API February 2016 4.1. Static parameters 4.1.1. API Version The Input Format Parameter Errors associated to the API version output are: API_VERSION_FORMAT_ERROR 4.1.2. TLSVersion The Input Format Parameter Errors and Not Permitted Input Parameters Error associated to the TLS version output are: TLS_VERSION_FORMAT_ERROR TLS_VERSION_UNACCEPTABLE_ERROR 4.1.3. ObjectRequest The Input Format Parameter Errors and Not Permitted Input Parameters Error associated to the requested output are: REQUEST_OUTPUT_FORMAT_ERROR REQUEST_OUTPUT_UNACCEPTABLE_ERROR 4.1.4. AuthenticationMethod The Input Format Parameter Errors and Not Permitted Input Parameters Error associated to the authentication method are: AUTHENTICATION_METHOD_FORMAT_ERROR AUTHENTICATION_METHOD_UNACCEPTABLE_ERROR 4.1.5. MasterMethod The Input Format Parameter Errors and Not Permitted Input Parameters Error associated to the master methods are: MASTER_METHOD_FORMAT_ERROR MASTER_METHOD_UNACCEPTABLE_ERROR 4.1.6. SignatureMethod The Input Format Parameter Errors and Not Permitted Input Parameters Error associated to the signature method are: SIGNATURE_METHOD_FORMAT_ERROR SIGNATURE_METHOD_UNACCEPTABLE_ERROR Migault Expires August 22, 2016 [Page 10] Internet-Draft TLS abstract API February 2016 4.1.7. PRF The Input Format Parameter Errors and Not Permitted Input Parameters Error associated to the pseudo random function are: PRF_FUNCTION_FORMAT_ERROR PRF_FUNCTION_UNACCEPTABLE_ERROR 4.2. TLS Hanshake parameters 4.2.1. ClientHello.random, ClientServer.random The Input Format Parameter Error associated to the ClientHello randoms is: CLIENT_RANDOM_FORMAT_ERROR (most likely a length different from 32 bytes) 4.2.2. session_hash, DataHash The Input Format Parameter Error associated to the hash is: HASH_FORMAT_ERROR (most likely an unexpected length) 4.2.3. handshake_messages The Input Format Parameter Error associated to the hash is: HANDSHAKE_MESAGE_FORMAT_ERROR 4.2.4. PSK_ID The Not Input Parameter Error associated to the hash is: PSK_ID_UNACCEPTABLE_ERROR (unkown PSK id) 4.3. Cryptographic Parameters 4.3.1. RSAEncryptedPreMaster Encrypted RSA values are expected to follow the PKCS#1 format. Upon receipt of the parameter, the Content Provider checks the format of encrypted parameters. If an error is detected, the Content Provider can either respond with a randomly generated pre_master or master or return a Input Format Parameter Error. The random value will result in an aborted session, and so motivation for providing a random value is to prevent notifying the Edge Server a format error has been detected. This behavior is recommended when the Content provider Migault Expires August 22, 2016 [Page 11] Internet-Draft TLS abstract API February 2016 does not trust the Edge Server or suspect it is under attack. On the other hand, sending a error may also notify the Edge Server an attack is being suspected, so mitigating mechanisms may be activated by the Edge Server. In any case, if an format error is detected the error returned by the Content Provider may be: RSA_ENCRYPTED_FORMAT_ERROR If the parameters ar enot expected, the Content Provider may provide in addition to an INCOMPATIBLE_INPUT_PARAMETERS_ERROR the following message: RSA_ENCRYPTED_UNACCEPTABLE_ERROR 4.3.1.1. Checking RSA Encrypted Premaster Format The first two bytes must be 00 02 followed by non zero padding until a 00 byte is found, followed by the two byte for the TLS version and finally the 46 bytes of the pre master secret. If the format is appropriated the premaster is returned, otherwise an ERROR_UNVALID_ENCRYPTED_MASTER is returned, or a randomly generated Premaster Secret which will silently discard the TLS session - see Section 7.4.7.1 of [RFC5246]. As defined in section 8.1.1 [RFC2546], the pre_master is 48-byte generated by the TLS Client. The two first bytes indicates the TLS version and MUST be the same value as the one provided by the ClientHello.client_version, and the remaining 46 bytes are expected to be random. The pre_master is encrypted with the public key of the TLS Server as a EncryptedPreMasterSecret structure sent in the Client Key Exchange Message as described in section 7.4.7.1 [RFC5246]. The encryption follows for compatibility with previous TLS version RSAES-PKCS1-v1_5 scheme described in [RFC3447], which results in a 256 byte encrypted message for a 2048-bit RSA key or 128 byte encrypted message for a 1024 bit RSA key. <---------- 256 bytes ------------------------------> <-- 205 bytes --> <- 48 bytes -> <- TLS -> version +----+----+------------------+----+-----+-----+--------+ | 00 | 02 | non-zero padding | 00 | maj | min | random | +----+----+------------------+----+-----+-----+--------+ PKCS#1 padding for pre_master secret encrypted with 2048-bit RSA key Migault Expires August 22, 2016 [Page 12] Internet-Draft TLS abstract API February 2016 4.3.2. DHECDHTLSClientPublicDHECDHKey TBD 4.3.3. TLSClientEdgeServerDHSecret TBD 4.3.4. TLSClientEdgeServerDHECDHSecret TBD 5. Output Parameters Description 5.1. Premaster The premaster and master are an opaque number bytes. premaster are 46 byte length and master are 48 byte length. Note that the PreMasterSecret structure of [RFC5246] includes the protocol version. struct { ProtocolVersion client_version; opaque random[46]; } PreMasterSecret; PreMasterSecret Structure 5.2. Signature In order to identify the signature, the signature structure should have the signature algorithm, the hash algorithm and the value of the signature. 5.3. Error In this document, the Error message can carry various messages. More specifically, when a query is not accepted because of incompatibility of parameters provided, the Content provider returns INCOMPATIBLE_INPUT_PARAMETERS_ERROR. In order to provide more indication to the Edge Server additional message as the convicting parameters may be added. Migault Expires August 22, 2016 [Page 13] Internet-Draft TLS abstract API February 2016 6. Security Considerations 7. Acknowledgements 8. References [RFC2546] Durand, A. and B. Buclin, "6Bone Routing Practice", RFC 2546, DOI 10.17487/RFC2546, March 1999, . [RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography Standards (PKCS) #1: RSA Cryptography Specifications Version 2.1", RFC 3447, DOI 10.17487/RFC3447, February 2003, . [RFC4279] Eronen, P., Ed. and H. Tschofenig, Ed., "Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)", RFC 4279, DOI 10.17487/RFC4279, December 2005, . [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS)", RFC 4492, DOI 10.17487/RFC4492, May 2006, . [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/ RFC5246, August 2008, . [RFC6347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer Security Version 1.2", RFC 6347, DOI 10.17487/RFC6347, January 2012, . Author's Address Daniel Migault Ericsson 8400 boulevard Decarie Montreal, QC H4P 2N2 Canada Phone: +1 514-452-2160 Email: daniel.migault@ericsson.com Migault Expires August 22, 2016 [Page 14]