Skip to content

Commit ce175de

Browse files
authored
Fix grammar and clarity in simple-tls.md
Corrected grammatical errors and improved clarity in the Simple TLS lab documentation.
1 parent 0cfe644 commit ce175de

File tree

1 file changed

+11
-11
lines changed

1 file changed

+11
-11
lines changed

_labs/simple-tls.md

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Use the GitHub Classroom link posted in the Teams channel for the lab to accept
1919

2020
## Overview
2121

22-
In this lab, you will be building a client for a simplified version of TLS, called Simple TLS. While the protocol might seem slightly bloated or redundant, each part of the protocol protects against a specific threat. TLS is a general purpose security transfer protocol that often works with HTTP. Once a TLS connect has been established, the client can send normal HTTP requests that get secured by the TLS connection. However, to simplify the lab, the server will send you a file after you have connected correctly through Simple TLS, no need to request a file.
22+
In this lab, you will be building a client for a simplified version of TLS, called Simple TLS. While the protocol might seem slightly bloated or redundant, each part of the protocol protects against a specific threat. TLS is a general-purpose security transfer protocol that often works with HTTP. Once a TLS connection has been established, the client can send normal HTTP requests that get secured by the TLS connection. However, to simplify the lab, the server will send you a file after you have connected correctly through Simple TLS; no need to request a file.
2323

2424
### Protocol
2525

@@ -31,11 +31,11 @@ Simple TLS contains a few handshakes to verify the server and establish a shared
3131
</figure>
3232

3333

34-
The client connects to the server and sends a hello message. The server responds with a [cryptographic nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) and its certificate. The client verifies the certificate, then sends its own cryptographic nonce that is encrypted using the server's public key (public keys are included inside of certificates). Now that the client has its own nonce and a nonce from the server, it has enough information to generate the master secret. The server will decrypt the encrypted nonce and generate the same master secret. As a final step before data is sent, the server will send a hash of all the messages it has sent to and received from the client. The client will verify the hash of the messages and then send its own hash of messages it has sent and received. Once the server has verified the hash it has received from the client, it will start sending data to the client.
34+
The client connects to the server and sends a hello message. The server responds with a [cryptographic nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) and its certificate. The client verifies the certificate, then sends its own cryptographic nonce that is encrypted using the server's public key (public keys are included inside certificates). Now that the client has its own nonce and a nonce from the server, it has enough information to generate the master secret. The server will decrypt the encrypted nonce and generate the same master secret. As a final step before data is sent, the server will send a hash of all the messages it has sent to and received from the client. The client will verify the hash of the messages and then send its own hash of the messages it has sent and received. Once the server has verified the hash it has received from the client, it will start sending data to the client.
3535

3636
#### Header
3737

38-
All messages sent, including data messages, has a header. This lets the client and server know how to interpret the data. The general structure of the header, along with the sizes of each field is shown below.
38+
All messages sent, including data messages, have a header. This lets the client and server know how to interpret the data. The general structure of the header, along with the sizes of each field, is shown below.
3939

4040
```
4141
0 1 2 3
@@ -54,7 +54,7 @@ All messages sent, including data messages, has a header. This lets the client a
5454

5555
- **Data**: This field is variable length. **Based on the type of message, you will interpret the data payload differently.**
5656

57-
I have provided a module, `message.py`, that can help you with the parsing of the header.
57+
I have provided a module, `message.py`, that can assist you with parsing the header.
5858

5959
#### Message Formats
6060

@@ -64,17 +64,17 @@ After the client connects to the server, it starts the process by sending a hell
6464

6565
##### Certificate
6666

67-
When the server receives a hello message from a client, it responds with a certificate message (0x02). The certificate message contains two pieces of information: the server's nonce and the server's certificate. In this protocol, all nonces are 32 bytes. The first 32 bytes of the message's payload will be the server's nonce and the rest of the payload will be the certificate.
67+
When the server receives a hello message from a client, it responds with a certificate message (0x02). The certificate message contains two pieces of information: the server's nonce and the server's certificate. In this protocol, all nonces are 32 bytes. The first 32 bytes of the message's payload will be the server's nonce, and the remaining payload will be the certificate.
6868

69-
On the client's end, to verify the certificate, you only need to call `utils.load_certificate` and verify that it doesn't return `None`. There are more thorough ways of verifying certificates, but for this lab, we will only ensure the certificate is formatted correctly.
69+
On the client's end, to verify the certificate, you only need to call `utils.load_certificate` and verify that it returns a value other than `None`. There are more thorough ways of verifying certificates, but for this lab, we will only ensure the certificate is formatted correctly.
7070

7171
##### Nonce
7272

73-
Upon verifying the certificate from the server, the client will generate a 32 byte nonce, encrypt it with the server's public key, and send it to the server in the nonce message (0x03). You can access the public key by calling `certificate.public_key()` on the verified certificate object.
73+
Upon verifying the certificate from the server, the client will generate a 32-byte nonce, encrypt it with the server's public key, and send it to the server in the nonce message (0x03). You can access the public key by calling `certificate.public_key()` on the verified certificate object.
7474

7575
##### Key Derivation
7676

77-
With both nonces, the client and server have enough information to generate a shared key. It is considered a bad practice to use one shared key as the encryption key and data integrity key for both the client and the server. It is better to have two keys, one for encryption and one for data integrity for both client and server (four keys in total). To help with this, you can call `utils.generate_keys` to generate the four keys. It will return a tuple with four items:
77+
With both nonces, the client and server have enough information to generate a shared key. It is considered a bad practice to use one shared key as the encryption key and data integrity key for both the client and the server. It is better to have two keys, one for encryption and one for data integrity, for both client and server (four keys in total). To help with this, you can call `utils.generate_keys` to generate the four keys. It will return a tuple with four items:
7878

7979
1. The server's encryption key
8080
2. The server's data integrity key
@@ -93,7 +93,7 @@ You can use the `utils.mac` with the appropriate data and key to calculate this
9393

9494
##### Data
9595

96-
Assuming that the previous hash matches with the server's hash, the server will start sending data messages (0x05). Using TCP, data is "streamed" between two devices. However, this streaming abstraction starts breaking down when you need to integrity protect data. Message authentication codes (MAC) need to be used to verify the data has not been changed, but where do you put the MAC? At the end of the whole stream? Simple TLS (and TLS) deals with this by breaking the stream into chunks. These chunks are encrypted and integrity protected.
96+
Assuming that the previous hash matches the server's hash, the server will start sending data messages (0x05). Using TCP, data is "streamed" between two devices. However, this streaming abstraction starts breaking down when you need to integrity protect data. Message authentication codes (MAC) need to be used to verify that the data has not been changed, but where do you put the MAC? At the end of the whole stream? Simple TLS (and TLS) deals with this by breaking the stream into chunks. These chunks are encrypted and integrity-protected.
9797

9898
<figure class="image mx-auto" style="max-width: 700px">
9999
<img src="{% link assets/simple_tls_data.png %}" alt="How data is fragmented in Simple TLS.">
@@ -108,7 +108,7 @@ To get the data sent by the server, the client must first decrypt the data using
108108

109109
After you pull apart the decrypted payload, verify the sequence number, calculate the MAC on the data chunk using the server's data integrity key, and finally compare the MAC with the MAC sent from the server. If the sequence number and MAC are correct, then the data chunk can be used. The server will continue to send data messages until it has sent a complete file, then it will close the socket. Warning: an advisory will occasionally change the encrypted data or replay data, so you must check the sequence number and verify the MAC.
110110

111-
If you have made it this far, save the data to a file with an `.png` extension. If you can correctly view the image you received, you have successfully completed the protocol portion of the lab!
111+
If you have made it this far, save the data to a file with a `.png` extension. If you can correctly view the image you received, you have successfully completed the protocol portion of the lab!
112112

113113
### Command-line Interface (CLI)
114114

@@ -132,7 +132,7 @@ optional arguments:
132132

133133
- Get experience with security principles.
134134

135-
- Build a client for a encrypted and integrity protected communication protocol.
135+
- Build a client for an encrypted and integrity-protected communication protocol.
136136

137137

138138
## Requirements

0 commit comments

Comments
 (0)