From fc0f4c00fb62af35d25b26f63ecdd2bff9e1e0c3 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 5 Dec 2022 00:36:00 -0500 Subject: [PATCH 01/10] add content for tls --- content/concepts/secure-comm/tls.md | 115 +++++++++++++++++++++++++++- 1 file changed, 113 insertions(+), 2 deletions(-) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index 27c7576f..c79794a5 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -6,5 +6,116 @@ aliases: - "/concepts/secure-comm/tls" --- - -Coming soon! +## What is TLS? + +TLS (Transport Layer Security) is a cryptographic protocol that securely uses encryption +to transfer data over a communication channel. It serves as the successor +to SSL (Secure Sockets Layer). TLS guarantees encryption, authentication, and data integrity +as a cryptographic protocol. + +Like SSL, a handshake establishes a secure connection between a client +and a server. A TLS handshake is responsible for negotiating cipher suites and the +protocol version (TLS version), authenticating both server and client, and key +sharing. + +### What is TLS 1.3? + +TLS 1.3 is a new encryption protocol, as defined in +[RFC 8446](https://www.rfc-editor.org/rfc/rfc8446), in 2018. It has several +improvements over TLS 1.2, including faster performance, more robust encryption, +and better support for modern cryptographic algorithms. + +TLS 1.3 is also used as part of the Noise protocol framework to provide secure +and private communication between nodes. Learn more about Noise [here](noise). + +{{< alert icon="💡" context="note" text="For context, TLS 1.0 was defined as RFC 2246 in 1996, TLS 1.1 was defined as RFC 4346 in 2006, and TLS 1.2 was defined as RFC 5246 in 2008." />}} + +### Comparing TLS 1.3 to TLS 1.2 + +The primary distinction between TLS 1.3 from TLS 1.2 is that a TLS 1.3 connection takes +one less round trip. + +{{< alert icon="💡" context="info" text="The number of round trips required for a TLS 1.2 handshake can vary; when combined with TCP (SYN and SYN-ACK), the TLS 1.2 handshake takes 3 round trips." />}} + +**A typical TLS 1.2 handshake is as follows:** + +1. The client sends a `ClientHello` message with a list of supported cipher suites to + indicate to the server that it wants to connect using TLS 1.2. + +2. The server responds with a `ServerHello` message which is a result of the following: + - checking if the client's TLS version is valid (in this case, TLS 1.2); + - choosing the preferred cipher suite from the list that the client provided and the + associated key share; + > The key is based on the cipher suite selected. TLS recommends ECDHE as the key exchange algorithm, + > but supports other key exchange algorithms like RSA. + > If ECDHE is chosen: + > + > - the associated algorithm parameters for ECDHE are used to generate a server signature; + > - key shares are mixed with the Elliptic Curve Diffie Hellman algorithm. + > that can be used for authentication on the client side. + > + - providing a TLS certificate signed by a trusted CA (certificate authority); + > A browser typically requires a server to present a valid TLS certificate signed by a trusted CA. + +3. The client sends a `Finished` message once it verifies the server's TLS certificate and signature, + and then generates its key share and mixes it with the server key share using the cipher suite. + +4. The server also sends a `Finished` message with its key share. + +#### Benefits of TLS 1.3 + +TLS 1.3 uses more robust encryption algorithms, such as AES-GCM. They provide +better security and faster performance than the algorithms used in TLS 1.2. TLS 1.3 also +eliminates the use of less secure cryptographic techniques still used in TLS 1.2, +such as SHA-1. + + > Over the years, there have been vulnerabilities identified in a variety of encryption + > algorithms. To guarantee safe communication, TLS 1.3 only supports + > 5 cipher suites, as opposed to the 37 supported in TLS 1.2. They are: + + > - TLS_CHACHA20_POLY1305_SHA256 + > - TLS_AES_128_GCM_SHA256 + > - TLS_AES_256_GCM_SHA384 + > - TLS_AES_128_CCM_8_SHA256 + > - TLS_AES_128_CCM_SHA256 + +In TLS 1.3, a client can include all the necessary information, including the key share, +in the first `ClientHello` message by assuming which key agreement algorithm the +server will choose due to the limited cipher suites. This saves one round trip as the server can +generate its key since it already has the client's key share. + +As a result, TLS 1.3 uses a new handshake protocol that allows for faster and more efficient +establishment of encrypted connections. TLS 1.3 also introduces new features, such as certificate +compression and support for cryptographic keys larger than 4096 bits. + +## TLS 1.3 in libp2p + +To use TLS 1.3 in libp2p, a peer must first establish a TLS 1.3 connection with another peer using the +handshake protocol. Once the handshake is complete, the peers can use the encrypted connection +to exchange data securely and privately. + +### Handshake + +During the handshake, TLS 1.3 only takes 1 round-trip to complete. +Peers must authenticate each other’s identity during the handshake. +By extension, servers require client authentication during the TLS handshake +and will abort if the client fails to authenticate. + +TLS 1.3 is identified during protocol negotiation with the following protocol ID: `/tls/1.0.0`. + +In LibP2P, endpoints authenticate peers by encoding their public key into an X.509 certificate +extension, however, peers can use arbitrary key types and are not constrained to those for which +the signing of an X.509 certificate is specified. + +{{< alert icon="💡" context="note" text="X.509 is an ITU (International Telecommunication Union) standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is an additional field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details."/>}} + +For arbitrary key types, an endpoint needs to encode its host key using the +[LibP2P public key extension](https://github.com/libp2p/specs/blob/master/tls/tls.md#libp2p-public-key-extension) +which is carried in a self-signed certificate to prove ownership of its host key. It generates a signature using its private host key and shares it with the +public host key for verification. The signature proves that the endpoint owned +the private host key when signing the certificate. + +The public host allows the other peer to calculate the peer ID of the endpoint it connects to. Failed +authentication will immediately terminate the secure connection establishment. + +{{< alert icon="💡" context="note" text="See the TLS technical specification for more details." />}} From 210c724915ac9ec3cbdcfba804bb734d83d76331 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 5 Dec 2022 01:37:04 -0500 Subject: [PATCH 02/10] lint --- content/concepts/secure-comm/tls.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index c79794a5..0842fb36 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -1,6 +1,6 @@ --- title: "TLS" -description: Learn about TLS 1.3 in libp2p. +description: Learn about TLS 1.3 in LibP2P. weight: 130 aliases: - "/concepts/secure-comm/tls" @@ -72,7 +72,7 @@ such as SHA-1. > Over the years, there have been vulnerabilities identified in a variety of encryption > algorithms. To guarantee safe communication, TLS 1.3 only supports > 5 cipher suites, as opposed to the 37 supported in TLS 1.2. They are: - + > > - TLS_CHACHA20_POLY1305_SHA256 > - TLS_AES_128_GCM_SHA256 > - TLS_AES_256_GCM_SHA384 @@ -88,9 +88,9 @@ As a result, TLS 1.3 uses a new handshake protocol that allows for faster and mo establishment of encrypted connections. TLS 1.3 also introduces new features, such as certificate compression and support for cryptographic keys larger than 4096 bits. -## TLS 1.3 in libp2p +## TLS 1.3 in LibP2P -To use TLS 1.3 in libp2p, a peer must first establish a TLS 1.3 connection with another peer using the +To use TLS 1.3 in LibP2P, a peer must first establish a TLS 1.3 connection with another peer using the handshake protocol. Once the handshake is complete, the peers can use the encrypted connection to exchange data securely and privately. From ec025a6e94d39ecaf24217995ad53320cb2b9bb4 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 5 Dec 2022 11:06:59 -0500 Subject: [PATCH 03/10] enhance + edits --- content/concepts/secure-comm/tls.md | 101 ++++++++++++++++------------ 1 file changed, 57 insertions(+), 44 deletions(-) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index 0842fb36..51fc7308 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -1,6 +1,6 @@ --- title: "TLS" -description: Learn about TLS 1.3 in LibP2P. +description: Learn about TLS 1.3 in libp2p. weight: 130 aliases: - "/concepts/secure-comm/tls" @@ -8,15 +8,15 @@ aliases: ## What is TLS? -TLS (Transport Layer Security) is a cryptographic protocol that securely uses encryption -to transfer data over a communication channel. It serves as the successor -to SSL (Secure Sockets Layer). TLS guarantees encryption, authentication, and data integrity -as a cryptographic protocol. +TLS (Transport Layer Security) is a cryptographic protocol that securely uses +encryption to transfer data over a communication channel. It serves as the +successor to SSL (Secure Sockets Layer). TLS guarantees encryption, authentication, +and data integrity as a cryptographic protocol. Like SSL, a handshake establishes a secure connection between a client -and a server. A TLS handshake is responsible for negotiating cipher suites and the -protocol version (TLS version), authenticating both server and client, and key -sharing. +and a server. A TLS handshake is responsible for negotiating cipher suites +and the protocol version (TLS version), authenticating both server and client, +and key sharing. ### What is TLS 1.3? @@ -35,7 +35,7 @@ and private communication between nodes. Learn more about Noise [here](noise). The primary distinction between TLS 1.3 from TLS 1.2 is that a TLS 1.3 connection takes one less round trip. -{{< alert icon="💡" context="info" text="The number of round trips required for a TLS 1.2 handshake can vary; when combined with TCP (SYN and SYN-ACK), the TLS 1.2 handshake takes 3 round trips." />}} +{{< alert icon="💡" context="info" text="The number of round trips required for a TLS 1.2 handshake can vary; when combined with TCP (SYN and SYN-ACK), the TLS 1.2 handshake takes three round trips." />}} **A typical TLS 1.2 handshake is as follows:** @@ -43,30 +43,36 @@ one less round trip. indicate to the server that it wants to connect using TLS 1.2. 2. The server responds with a `ServerHello` message which is a result of the following: - - checking if the client's TLS version is valid (in this case, TLS 1.2); + - checking if the client's TLS version is valid; - choosing the preferred cipher suite from the list that the client provided and the - associated key share; - > The key is based on the cipher suite selected. TLS recommends ECDHE as the key exchange algorithm, - > but supports other key exchange algorithms like RSA. + associated key share using a `ServerKeyExchange`; + > The key is based on the cipher suite selected. TLS recommends ECDHE as the key exchange + > algorithm, but supports other key exchange algorithms like RSA. > If ECDHE is chosen: > - > - the associated algorithm parameters for ECDHE are used to generate a server signature; + > - the associated algorithm parameters for ECDHE would be used to generate a server signature; > - key shares are mixed with the Elliptic Curve Diffie Hellman algorithm. - > that can be used for authentication on the client side. - > - - providing a TLS certificate signed by a trusted CA (certificate authority); + + - providing a TLS certificate signed by a trusted CA (certificate authority). > A browser typically requires a server to present a valid TLS certificate signed by a trusted CA. -3. The client sends a `Finished` message once it verifies the server's TLS certificate and signature, - and then generates its key share and mixes it with the server key share using the cipher suite. +3. The client verifies the server's certificate and generates a premaster secret key, which + is used to encrypt the data being transferred. The client encrypts the secret key with the + server's public key (using the cipher suite) and sends a `ClientKeyExchange` message to the + server. + +4. The server decrypts the premaster secret key using its private key and uses it with its + private keys to generate sessions keys to establish an encrypted connection with the client. + The server also sends a `Finished` message to indicate that the key exchange was successful + and the session keys have been generated. -4. The server also sends a `Finished` message with its key share. +5. The client sends a `Finished` message to confirm that the handshake is complete. #### Benefits of TLS 1.3 TLS 1.3 uses more robust encryption algorithms, such as AES-GCM. They provide -better security and faster performance than the algorithms used in TLS 1.2. TLS 1.3 also -eliminates the use of less secure cryptographic techniques still used in TLS 1.2, +better security and faster performance than the algorithms used in TLS 1.2. TLS 1.3 +also eliminates the use of less secure cryptographic techniques still used in TLS 1.2, such as SHA-1. > Over the years, there have been vulnerabilities identified in a variety of encryption @@ -81,41 +87,48 @@ such as SHA-1. In TLS 1.3, a client can include all the necessary information, including the key share, in the first `ClientHello` message by assuming which key agreement algorithm the -server will choose due to the limited cipher suites. This saves one round trip as the server can -generate its key since it already has the client's key share. +server will choose due to the limited cipher suites. This saves one round trip as the server +can generate its key from the first message. As a result, TLS 1.3 uses a new handshake protocol that allows for faster and more efficient -establishment of encrypted connections. TLS 1.3 also introduces new features, such as certificate -compression and support for cryptographic keys larger than 4096 bits. +establishment of encrypted connections. TLS 1.3 also introduces new features, such as +certificate compression and support for cryptographic keys larger than 4096 bits. -## TLS 1.3 in LibP2P +## TLS 1.3 in libp2p -To use TLS 1.3 in LibP2P, a peer must first establish a TLS 1.3 connection with another peer using the -handshake protocol. Once the handshake is complete, the peers can use the encrypted connection -to exchange data securely and privately. +To use TLS 1.3 in libp2p, a peer must first establish a TLS 1.3 connection with another peer +using the handshake protocol. Once the handshake is complete, the peers can use the encrypted +connection to exchange data securely and privately. ### Handshake -During the handshake, TLS 1.3 only takes 1 round-trip to complete. -Peers must authenticate each other’s identity during the handshake. -By extension, servers require client authentication during the TLS handshake -and will abort if the client fails to authenticate. +A TLS 1.3 handshake in libp2p conducts both key sharing and peer authentication +in a single round trip. Peers must authenticate each other’s identity during the +handshake. By extension, servers require client authentication during the TLS +handshake and will abort if the client fails to authenticate. -TLS 1.3 is identified during protocol negotiation with the following protocol ID: `/tls/1.0.0`. +TLS 1.3 is identified during protocol negotiation with the following protocol +ID: `/tls/1.0.0`. -In LibP2P, endpoints authenticate peers by encoding their public key into an X.509 certificate -extension, however, peers can use arbitrary key types and are not constrained to those for which -the signing of an X.509 certificate is specified. +In libp2p, endpoints authenticate peers by encoding their public key into an X.509 +certificate extension, however, peers can use arbitrary key types and are not constrained +to those for which the signing of an X.509 certificate is specified. -{{< alert icon="💡" context="note" text="X.509 is an ITU (International Telecommunication Union) standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is an additional field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details."/>}} +{{< alert icon="💡" context="note" text="X.509 is an ITU standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is a field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details."/>}} For arbitrary key types, an endpoint needs to encode its host key using the -[LibP2P public key extension](https://github.com/libp2p/specs/blob/master/tls/tls.md#libp2p-public-key-extension) -which is carried in a self-signed certificate to prove ownership of its host key. It generates a signature using its private host key and shares it with the -public host key for verification. The signature proves that the endpoint owned +[libp2p public key extension](https://github.com/libp2p/specs/blob/master/tls/tls.md#libp2p-public-key-extension) +which is carried in a self-signed certificate to prove ownership of its host key. +The libp2p public key extension is an X.509 extension with the Object Identier +`1.3.6.1.4.1.53594.1.1`. A certificate must include the libp2p public key extension +to be marked valid. + +The endpoint generates a signature using its private host key and shares it along with +its public host key for verification. The signature proves that the peer owned the private host key when signing the certificate. -The public host allows the other peer to calculate the peer ID of the endpoint it connects to. Failed -authentication will immediately terminate the secure connection establishment. +The public host allows the other peer to calculate the peer ID of the endpoint it +connects to. Failed authentication would immediately terminate the secure connection +establishment. {{< alert icon="💡" context="note" text="See the TLS technical specification for more details." />}} From 1113f448746ee06a39bdea294f81702114f56a90 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 12 Dec 2022 06:38:48 -0500 Subject: [PATCH 04/10] Apply suggestions from code review Co-authored-by: Marten Seemann --- content/concepts/secure-comm/tls.md | 38 ++++++++++++++--------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index 51fc7308..f46dda71 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -8,22 +8,23 @@ aliases: ## What is TLS? -TLS (Transport Layer Security) is a cryptographic protocol that securely uses -encryption to transfer data over a communication channel. It serves as the -successor to SSL (Secure Sockets Layer). TLS guarantees encryption, authentication, -and data integrity as a cryptographic protocol. +TLS (Transport Layer Security) is a cryptographic protocol that allows the establishment +of a secure data channel. TLS provides encryption, authentication, +and data integrity. -Like SSL, a handshake establishes a secure connection between a client -and a server. A TLS handshake is responsible for negotiating cipher suites -and the protocol version (TLS version), authenticating both server and client, -and key sharing. +During the TLS handshake, a secure context is established between a client +and a server. After the handshake completes, both sides have derived a key +(the TLS master secret) that's only known to the two parties, and is from then +on used to encrypt application data sent over the channel. ### What is TLS 1.3? -TLS 1.3 is a new encryption protocol, as defined in -[RFC 8446](https://www.rfc-editor.org/rfc/rfc8446), in 2018. It has several -improvements over TLS 1.2, including faster performance, more robust encryption, -and better support for modern cryptographic algorithms. +TLS 1.3 is a new version of the TLS protocol, published 2018 in +[RFC 8446](https://www.rfc-editor.org/rfc/rfc8446). It brings several +improvements over TLS 1.2: the latency of a handshake was brought +down from 2 to 1 network round trips (in the common case), the privacy +properties were improved by encrypting the certificates, and the protocol +was made simplified to reduce implementation complexity. TLS 1.3 is also used as part of the Noise protocol framework to provide secure and private communication between nodes. Learn more about Noise [here](noise). @@ -102,17 +103,16 @@ connection to exchange data securely and privately. ### Handshake -A TLS 1.3 handshake in libp2p conducts both key sharing and peer authentication -in a single round trip. Peers must authenticate each other’s identity during the -handshake. By extension, servers require client authentication during the TLS -handshake and will abort if the client fails to authenticate. +libp2p uses TLS 1.3 handshake to establish a secure connection between two peers. +Peers authenticate each other’s libp2p peer ID during the handshake. TLS 1.3 is identified during protocol negotiation with the following protocol ID: `/tls/1.0.0`. -In libp2p, endpoints authenticate peers by encoding their public key into an X.509 -certificate extension, however, peers can use arbitrary key types and are not constrained -to those for which the signing of an X.509 certificate is specified. +In libp2p, peer authentication works by encoding the public key into the TLS certificate. +We designed the system such that we can authenticate key types that are usually not +supported by TLS stacks, such as sepc256k1 (which is a key type that can be used for +libp2p keys). {{< alert icon="💡" context="note" text="X.509 is an ITU standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is a field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details."/>}} From b2258ec2a3b762724aebfe49260acd075d35bec5 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 12 Dec 2022 06:55:10 -0500 Subject: [PATCH 05/10] incorporate feedback and simplify tls content --- content/concepts/secure-comm/tls.md | 120 +++++----------------------- 1 file changed, 21 insertions(+), 99 deletions(-) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index f46dda71..dfb21165 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -8,127 +8,49 @@ aliases: ## What is TLS? -TLS (Transport Layer Security) is a cryptographic protocol that allows the establishment -of a secure data channel. TLS provides encryption, authentication, -and data integrity. +TLS (Transport Layer Security) is a cryptographic protocol that establishes a +secure data channel. TLS provides encryption, authentication, and data integrity. -During the TLS handshake, a secure context is established between a client +During the TLS handshake, a secure connection is established between a client and a server. After the handshake completes, both sides have derived a key -(the TLS master secret) that's only known to the two parties, and is from then -on used to encrypt application data sent over the channel. +(the TLS master secret) that's only known to the two parties and is then used to +encrypt application data sent over the channel. ### What is TLS 1.3? -TLS 1.3 is a new version of the TLS protocol, published 2018 in +TLS 1.3 is a new version of the TLS protocol, published in 2018 in [RFC 8446](https://www.rfc-editor.org/rfc/rfc8446). It brings several improvements over TLS 1.2: the latency of a handshake was brought -down from 2 to 1 network round trips (in the common case), the privacy +down from 2 to 1 network round trips (in the typical case), the privacy properties were improved by encrypting the certificates, and the protocol was made simplified to reduce implementation complexity. -TLS 1.3 is also used as part of the Noise protocol framework to provide secure -and private communication between nodes. Learn more about Noise [here](noise). - -{{< alert icon="💡" context="note" text="For context, TLS 1.0 was defined as RFC 2246 in 1996, TLS 1.1 was defined as RFC 4346 in 2006, and TLS 1.2 was defined as RFC 5246 in 2008." />}} - -### Comparing TLS 1.3 to TLS 1.2 - -The primary distinction between TLS 1.3 from TLS 1.2 is that a TLS 1.3 connection takes -one less round trip. - -{{< alert icon="💡" context="info" text="The number of round trips required for a TLS 1.2 handshake can vary; when combined with TCP (SYN and SYN-ACK), the TLS 1.2 handshake takes three round trips." />}} - -**A typical TLS 1.2 handshake is as follows:** - -1. The client sends a `ClientHello` message with a list of supported cipher suites to - indicate to the server that it wants to connect using TLS 1.2. - -2. The server responds with a `ServerHello` message which is a result of the following: - - checking if the client's TLS version is valid; - - choosing the preferred cipher suite from the list that the client provided and the - associated key share using a `ServerKeyExchange`; - > The key is based on the cipher suite selected. TLS recommends ECDHE as the key exchange - > algorithm, but supports other key exchange algorithms like RSA. - > If ECDHE is chosen: - > - > - the associated algorithm parameters for ECDHE would be used to generate a server signature; - > - key shares are mixed with the Elliptic Curve Diffie Hellman algorithm. - - - providing a TLS certificate signed by a trusted CA (certificate authority). - > A browser typically requires a server to present a valid TLS certificate signed by a trusted CA. - -3. The client verifies the server's certificate and generates a premaster secret key, which - is used to encrypt the data being transferred. The client encrypts the secret key with the - server's public key (using the cipher suite) and sends a `ClientKeyExchange` message to the - server. - -4. The server decrypts the premaster secret key using its private key and uses it with its - private keys to generate sessions keys to establish an encrypted connection with the client. - The server also sends a `Finished` message to indicate that the key exchange was successful - and the session keys have been generated. - -5. The client sends a `Finished` message to confirm that the handshake is complete. - -#### Benefits of TLS 1.3 - -TLS 1.3 uses more robust encryption algorithms, such as AES-GCM. They provide -better security and faster performance than the algorithms used in TLS 1.2. TLS 1.3 -also eliminates the use of less secure cryptographic techniques still used in TLS 1.2, -such as SHA-1. - - > Over the years, there have been vulnerabilities identified in a variety of encryption - > algorithms. To guarantee safe communication, TLS 1.3 only supports - > 5 cipher suites, as opposed to the 37 supported in TLS 1.2. They are: - > - > - TLS_CHACHA20_POLY1305_SHA256 - > - TLS_AES_128_GCM_SHA256 - > - TLS_AES_256_GCM_SHA384 - > - TLS_AES_128_CCM_8_SHA256 - > - TLS_AES_128_CCM_SHA256 - -In TLS 1.3, a client can include all the necessary information, including the key share, -in the first `ClientHello` message by assuming which key agreement algorithm the -server will choose due to the limited cipher suites. This saves one round trip as the server -can generate its key from the first message. - -As a result, TLS 1.3 uses a new handshake protocol that allows for faster and more efficient -establishment of encrypted connections. TLS 1.3 also introduces new features, such as -certificate compression and support for cryptographic keys larger than 4096 bits. - ## TLS 1.3 in libp2p -To use TLS 1.3 in libp2p, a peer must first establish a TLS 1.3 connection with another peer -using the handshake protocol. Once the handshake is complete, the peers can use the encrypted -connection to exchange data securely and privately. +**libp2p doesn't use TLS versions older than 1.3.** libp2p uses as extended +version of TLS 1.3, referred to as TLS 1.3+. + +To use TLS 1.3 in libp2p, a peer must first establish a TLS 1.3 connection with +another peer using the handshake protocol. Once the handshake is complete, the peers +can use the encrypted connection to exchange data securely and privately. ### Handshake -libp2p uses TLS 1.3 handshake to establish a secure connection between two peers. -Peers authenticate each other’s libp2p peer ID during the handshake. +libp2p uses TLS 1.3 handshake to establish a secure connection between two peers. +Peers authenticate each other's libp2p peer ID during the handshake. TLS 1.3 is identified during protocol negotiation with the following protocol ID: `/tls/1.0.0`. In libp2p, peer authentication works by encoding the public key into the TLS certificate. -We designed the system such that we can authenticate key types that are usually not -supported by TLS stacks, such as sepc256k1 (which is a key type that can be used for +We designed the system to authenticate key types usually not +supported by TLS stacks, such as sepc256k1 (a key type that can be used for libp2p keys). -{{< alert icon="💡" context="note" text="X.509 is an ITU standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is a field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details."/>}} - -For arbitrary key types, an endpoint needs to encode its host key using the -[libp2p public key extension](https://github.com/libp2p/specs/blob/master/tls/tls.md#libp2p-public-key-extension) -which is carried in a self-signed certificate to prove ownership of its host key. -The libp2p public key extension is an X.509 extension with the Object Identier -`1.3.6.1.4.1.53594.1.1`. A certificate must include the libp2p public key extension -to be marked valid. - -The endpoint generates a signature using its private host key and shares it along with -its public host key for verification. The signature proves that the peer owned -the private host key when signing the certificate. +{{< alert icon=" 💡" context=" note" text=" X.509 is an ITU standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is a field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details." />}} -The public host allows the other peer to calculate the peer ID of the endpoint it -connects to. Failed authentication would immediately terminate the secure connection -establishment. +When processing the TLS certificate, nodes derive the peer ID from the public key that +they received, and peers check that it matches the peer ID of the server they intend +to connect to. {{< alert icon="💡" context="note" text="See the TLS technical specification for more details." />}} From 1e861fdc12a3b02985d97460e29431b30b23db93 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 12 Dec 2022 07:00:46 -0500 Subject: [PATCH 06/10] modify ITU callout to general note --- content/concepts/secure-comm/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index dfb21165..c7bf138f 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -47,7 +47,7 @@ We designed the system to authenticate key types usually not supported by TLS stacks, such as sepc256k1 (a key type that can be used for libp2p keys). -{{< alert icon=" 💡" context=" note" text=" X.509 is an ITU standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is a field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details." />}} +> X.509 is an [ITU](https://www.itu.int/en/Pages/default.aspx) standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is a field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details." When processing the TLS certificate, nodes derive the peer ID from the public key that they received, and peers check that it matches the peer ID of the server they intend From 8fe74e243593b74d419538f5afb5294cef685ff5 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 12 Dec 2022 16:50:10 -0500 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Marten Seemann --- content/concepts/secure-comm/tls.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index c7bf138f..ad12d276 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -42,7 +42,7 @@ Peers authenticate each other's libp2p peer ID during the handshake. TLS 1.3 is identified during protocol negotiation with the following protocol ID: `/tls/1.0.0`. -In libp2p, peer authentication works by encoding the public key into the TLS certificate. +Peer authentication works by encoding the public key into the TLS certificate. We designed the system to authenticate key types usually not supported by TLS stacks, such as sepc256k1 (a key type that can be used for libp2p keys). @@ -50,7 +50,7 @@ libp2p keys). > X.509 is an [ITU](https://www.itu.int/en/Pages/default.aspx) standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is a field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details." When processing the TLS certificate, nodes derive the peer ID from the public key that -they received, and peers check that it matches the peer ID of the server they intend +they received. The node initiating the connection checks that it matches the peer ID of the node it intended to connect to. {{< alert icon="💡" context="note" text="See the TLS technical specification for more details." />}} From cfb107e2a89c72385b2ca46e8df751893c116426 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 12 Dec 2022 16:52:26 -0500 Subject: [PATCH 08/10] refine tls in libp2p --- content/concepts/secure-comm/tls.md | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index ad12d276..82381ed7 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -27,12 +27,7 @@ was made simplified to reduce implementation complexity. ## TLS 1.3 in libp2p -**libp2p doesn't use TLS versions older than 1.3.** libp2p uses as extended -version of TLS 1.3, referred to as TLS 1.3+. - -To use TLS 1.3 in libp2p, a peer must first establish a TLS 1.3 connection with -another peer using the handshake protocol. Once the handshake is complete, the peers -can use the encrypted connection to exchange data securely and privately. +**libp2p doesn't use TLS versions older than 1.3.** ### Handshake @@ -47,10 +42,8 @@ We designed the system to authenticate key types usually not supported by TLS stacks, such as sepc256k1 (a key type that can be used for libp2p keys). -> X.509 is an [ITU](https://www.itu.int/en/Pages/default.aspx) standard defining the format of public key certificates that use asymmetric cryptography for authentication. Certificate extensions were introduced in version 3 of the X.509 standard, which is a field that offers a set of additional attributes that can be included in the certificate to provide more information about the certificate's subject, such as the certificate's intended purpose, the cryptographic algorithms that the certificate uses, and other relevant details." - When processing the TLS certificate, nodes derive the peer ID from the public key that -they received. The node initiating the connection checks that it matches the peer ID of the node it intended -to connect to. +they received. The node initiating the connection checks that it matches the peer ID of the node +it intended to connect to. {{< alert icon="💡" context="note" text="See the TLS technical specification for more details." />}} From 5485e2b86aa05c320d9297ff9a6c2e489eabdc47 Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Wed, 14 Dec 2022 09:11:15 -0500 Subject: [PATCH 09/10] Apply suggestions from code review --- content/concepts/secure-comm/tls.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index 82381ed7..83c3598f 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -31,7 +31,7 @@ was made simplified to reduce implementation complexity. ### Handshake -libp2p uses TLS 1.3 handshake to establish a secure connection between two peers. +libp2p uses the TLS 1.3 handshake to establish a secure connection between two peers. Peers authenticate each other's libp2p peer ID during the handshake. TLS 1.3 is identified during protocol negotiation with the following protocol From 8582cfaf7b7903b20f6daa5add389de98cec6a5f Mon Sep 17 00:00:00 2001 From: Danny Salman Date: Mon, 19 Dec 2022 00:54:30 -0500 Subject: [PATCH 10/10] add introductory phrase --- content/concepts/secure-comm/tls.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/concepts/secure-comm/tls.md b/content/concepts/secure-comm/tls.md index 83c3598f..6c65f621 100644 --- a/content/concepts/secure-comm/tls.md +++ b/content/concepts/secure-comm/tls.md @@ -6,6 +6,10 @@ aliases: - "/concepts/secure-comm/tls" --- +TLS (Transport Layer Security) is one of the security handshakes used to secure transports +that don't have built-in security (e.g. TCP, WebSocket). [Noise](noise), an alternative to +TLS, is also another security handshake used to secure transports. + ## What is TLS? TLS (Transport Layer Security) is a cryptographic protocol that establishes a