doc: add information about s2n-tls software architecture #4868
Conversation
* add software architecture md file * insert the file before connection doc
| @@ -0,0 +1,21 @@ | |||
| # Software Architecture | |||
|
|
|||
| User interaction with s2n-tls happens primarily through the `s2n_connection` and `s2n_config` structures. | |||
There was a problem hiding this comment.
I'm not sure you currently have enough new information for this to be an entirely new chapter. Is there a way you can work this information into the existing chapters? Maybe connection.md because it's one of the first chapters.
There was a problem hiding this comment.
One other way that I think would work is to combine the software architecture, connection, and config chapters together and name it Software Architecture. I think both connection and config are parts of the software architecture. I don't think adding general software architecture documentation to connection.md alone is appropriate. Hence, I would say either we use three chapters to describe software architecture, or we combine all three chapters into one. I prefer the former, since it makes each chapter to serve one purpose. It also follows a logical flow where we discussed a general concept, and then gets down to the specific about connection and config.
There was a problem hiding this comment.
I agree with Madeleine - I don't see a reason for an entirely new section for this. It seems like most of the new content can be added to either the connection or config sections.
| @@ -0,0 +1,21 @@ | |||
| # Software Architecture | |||
|
|
|||
| User interaction with s2n-tls happens primarily through the `s2n_connection` and `s2n_config` structures. | |||
There was a problem hiding this comment.
I agree with Madeleine - I don't see a reason for an entirely new section for this. It seems like most of the new content can be added to either the connection or config sections.
* move those general docs to config and connection chapters * move config chapter in front of the connection chapter
* remove some repeating sentences * rephrase some sentences to make them read more precise
* make doc wording more precise based on comments
* add software architecture information on top of the connection chapter * resolve a nit
| Users interact with s2n-tls primarily through the `s2n_connection` and `s2n_config` structures. Users should build a `s2n_config` object and `s2n_connection` objects, associate the config with those connections, and then calling `s2n_negotiate()` on those connections until the TLS handshakes are completed. Users should then call `s2n_send`/`s2n_recv` on those connections to send and receive application data. | ||
|
|
There was a problem hiding this comment.
I'm not really sure what the goal of this paragraph is or that its inclusion makes the documentation better. This section is on connections, and technically you don't have to create a config to use a connection. I'm also not sure how useful the very brief mention of negotiate and send/receive is-- if we're going to mention them, we should probably at least link to the usage guide section that goes into more details.
There was a problem hiding this comment.
I'm not really sure what the goal of this paragraph is or that its inclusion makes the documentation better.
The initial intent of this paragraph is to provide a general overview of S2N software architecture. I think such a high level overview does make the documentation better, since it provides a general idea of how S2N-TLS usually works. It also connects the following chapters together. This is also suggested by this comment.
technically you don't have to create a config to use a connection.
I would change the wording as In general, users build a s2n_config ... to indicate how S2N is generally configured. That change implies there can be exceptions.
I'm also not sure how useful the very brief mention of negotiate and send/receive is-- if we're going to mention them, we should probably at least link to the usage guide section that goes into more details.
I think the process of negotiation and send/receive is a part of how users would typically interact with S2N-TLS. I would keep this part. I agree that we need to link chapter 7 - sending and receiving to this part.
There was a problem hiding this comment.
I don't think that paragraph achieves that goal, and currently isn't particularly helpful. Right now, I look in the "connection" section and before even explaining what a connection is or what it's for, you're redirecting me to configs and IO methods.
You may need to think about reorganizing things. Introduce what a connection is, then direct customers to the config section for configuration options and the IO section for how to use IO.
There was a problem hiding this comment.
You may need to think about reorganizing things. Introduce what a connection is, then direct customers to the config section for configuration options and the IO section for how to use IO.
I want to set up a subsection under # TLS Connections called ## Software Architecture, and move the paragraph into that subsection. Hence, the s2n_connection introduction will go before the general overview of software architecture.
Moreover, ## Connection Memory subsection talks about freeing memory after handshake.
Hence, introducing the software architecture after
# TLS Connections and right before ## Connection Memory should helps the doc to explain when the sequence of events usually take place.
There was a problem hiding this comment.
I'm not convinced that "Software Architecture" really makes sense as its own section. There's not much to talk about other than connections with software architecture :P
I'd go for:
- what is a connection
- how is a connection used, high level with links to details
- how do connections interact with configs, high level with links to details
There was a problem hiding this comment.
I wrote a general introduction about TLS connections and configs, which includes answers to those questions. We can revise it based on the new commit.
* remove repetitive sentences, and make wording more precise. * link relevant sections to software architecture's overview.
* change wording * move software architecture section to proper position * give general introductions about connection and config
| @@ -1,6 +1,8 @@ | |||
| # TLS Connections | |||
|
|
|||
| Users will need to create a `s2n_connection` struct to store all of the state necessary for a TLS connection. Call `s2n_connection_new()` to create a new server or client connection. Call `s2n_connection_free()` to free the memory allocated for this struct when no longer needed. | |||
| A TLS connection is a secure and encrypted channel established between two communicating peers. A TLS connection is used to send and receive data, perform TLS handshake negotiations, send alert messages, and etc. Read [TLS Connections](./ch04-connection.md) for information about connections, and [Sending and Receiving](./ch07-io.md) for io interactions. TLS connections are configured by TLS configs, which contains a collection of TLS settings. TLS configs apply rules on TLS connections by defining connection specs, such as supported certificate authorities. Read [Configuring the Connection](./ch05-config.md) for information about TLS connection and config interactions. | |||
There was a problem hiding this comment.
You need to give introductions for s2n-tls connections, but a user of a TLS library can probably be assumed to know what a TLS connection is. It also looks like you're using "TLS connection" and "s2n-tls connection" interchangeably tho. And "TLS configs" aren't a standard part of TLS, those are an s2n-tls implementation detail.
And I also still don't think this paragraph will really be useful to a new user trying to understand the overall flow of the library. You give examples of possible things you can do with connections, but it's really not clear enough to be helpful. What do I need to do with a connection to use TLS? You also include a link to this section, which is odd.
You also go too deep into "TLS configs"-- configs have their own section, they should at most be referenced here.
Resolved issues:
The usage guide doesn't have documentations for general s2n-tls software architecture.
Description of changes:
I have updated our
usage-guideto include documentation about s2n-tls high level software architecture. Since the architecture mostly involvess2n_connectionands2n_config, I decided to create a new markdown file for software architecture before the connection usage guide. Therefore, I need to rename those documentations after the connection usage guide.By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.