Add a tutorial on writing a simple blocking TLS client #21133

mattcaswell · 2023-06-06T15:26:01Z

Provide guidance on the steps needed to write a very simple blocking TLS
client.

This blocking client is intended to be used to explain how to implement a simple client in the documentation.

mattcaswell · 2023-06-06T15:27:06Z

@vdukhovni - I'd appreciate your input on this (in particular the demo)

Provide guidance on the steps needed to write a very simple blocking TLS client.

paulidale

Really good stuff.

My main question is if the background material belongs here or elsewhere. My feeling is elsewhere.

demos/guide/Makefile

doc/man7/guide-tls-client-block.pod

vdukhovni

Perhaps also set the min_protocol to TLSv1.2 as BCP for non-opportunistic TLS, and to showcase that API.

demos/guide/tls-client-block.c

vdukhovni · 2023-06-07T05:41:31Z

demos/guide/tls-client-block.c

+     */
+    ctx = SSL_CTX_new(TLS_client_method());
+    if (ctx == NULL) {
+        printf("Failed to create the SSL_CTX\n");


I would use a wrapper function that prints the error stack.

I'm not sure it adds much? The error stack printing is already there and in the common "end" block. The only thing different about each location is printing the error message itself.

Yes, HTTP?1.0 is supposed to close by default, but AFAIK sending Connection: close is still recommended, but I'm not sure how useful this is in practice.

vdukhovni · 2023-06-07T05:44:00Z

demos/guide/tls-client-block.c

+    /* Create an SSL object to represent the TLS connection */
+    ssl = SSL_new(ctx);
+    if (ssl == NULL) {
+        printf("Failed to create the SSL object\n");


Call same wrapper to dump the error stack and then print the message. Here and below as appropriate.

vdukhovni · 2023-06-07T05:45:37Z

demos/guide/tls-client-block.c

+     * Virtually all clients should do this unless you really know what you
+     * are doing.
+     */
+    if (!SSL_set1_host(ssl, HOSTNAME)) {


Perhaps mention that in some cases it may be appropriate to disable wildcard matching mentioning the relevant manpage.

I'd prefer not to in this example. I'm trying to keep it simple and the wildcard handling is probably not something most users need to be worrying about.

vdukhovni · 2023-06-07T05:47:41Z

demos/guide/tls-client-block.c

+    }
+
+    /* Write an HTTP GET request to the peer */
+    if (!SSL_write_ex(ssl, request, strlen(request), &written)) {


This is the blocking API, with no WANT_READ/WANT_WRITE. It may be also good to have examples that use a non-blocking BIO poll for I/O completion/ready.

I plan to do provide a specific example and associated tutorial for non-blocking in a future PR.

vdukhovni · 2023-06-07T05:49:39Z

demos/guide/tls-client-block.c

+        * non-printable or have NUL characters in the middle of it.
+        */
+        buf[readbytes] = '\0';
+        printf("%s", buf);


Could just use fwrite(3) to dump readbytes bytes of the response, and then putchar('\n').

Also, what if the server does not close the connection as soon as the response is sent? Perhaps also include a "Connection: close\r\n" request header?

I'm doing HTTP/1.0 here. IIUC, in HTTP/1.0 the default expectation is that the connection is closed automatically. The "Connection: close" header is an HTTP/1.1 header so shouldn't be needed. Or have I misunderstood something?

For tutorial type pages it doesn't make any sense to have a DESCRIPTION section.

We split the page into two: one covering basic TLS introductory material that applies to both clients and servers, and one with the specific material on writing a blocking TLS client.

mattcaswell · 2023-06-07T15:08:59Z

Perhaps also set the min_protocol to TLSv1.2 as BCP for non-opportunistic TLS, and to showcase that API.

Done

mattcaswell · 2023-06-07T15:15:01Z

All feedback addressed or otherwise responded to above. Please take another look.

paulidale · 2023-06-07T22:01:51Z

@vdukhovni you should probably reappove after the changes.

vdukhovni · 2023-06-08T17:52:39Z

demos/guide/tls-client-block.c

+/* Helper function to create a BIO connected to the server */
+static BIO *create_socket_bio(const char *hostname, const char *port)
+{
+    int sock = -1;


On Windows the socket type is a HANDLE, not an int. Is this code supposed to be Windows-portable?

Yes, that is an interesting anomaly. However BIO_socket() and friends return an int - so this code is correct. InternallyBIO_socket() implicitly casts the HANDLE to int. But its been that way for a very long time and is used (for example in s_client and s_server). So in practice I don't think this is actually a problem. Either way it isn't a problem for this demo code because it is using the API as it is designed.

vdukhovni · 2023-06-08T17:54:24Z

demos/guide/tls-client-block.c

+     */
+    ctx = SSL_CTX_new(TLS_client_method());
+    if (ctx == NULL) {
+        printf("Failed to create the SSL_CTX\n");


Yes, HTTP?1.0 is supposed to close by default, but AFAIK sending Connection: close is still recommended, but I'm not sure how useful this is in practice.

mattcaswell · 2023-06-09T08:59:14Z

Yes, HTTP?1.0 is supposed to close by default, but AFAIK sending Connection: close is still recommended, but I'm not sure how useful this is in practice.

Ok. I added the "Connection: close" header. It may be redundant, but at least it looks harmless.

mattcaswell · 2023-06-09T09:01:33Z

I've pushed a fixup to add the "Connection: close" header. I also spotted a minor bug in my socket creation code (missing "break" in the for loop) which I also fixed.

So - please could I have one more round of reconfirmations? @vdukhovni, @paulidale.

hlandau · 2023-06-12T11:02:50Z

@mattcaswell Needs rebase over check-ansi fix

t8m · 2023-06-12T13:17:27Z

@mattcaswell Needs rebase over check-ansi fix

It is sufficient to close&reopen so the test is re-run.

openssl-machine · 2023-06-14T03:00:19Z

This pull request is ready to merge

paulidale · 2023-06-14T03:08:54Z

Merged to master.

This blocking client is intended to be used to explain how to implement a simple client in the documentation. Reviewed-by: Viktor Dukhovni <viktor@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from #21133)

Provide guidance on the steps needed to write a very simple blocking TLS client. Reviewed-by: Viktor Dukhovni <viktor@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from #21133)

For tutorial type pages it doesn't make any sense to have a DESCRIPTION section. Reviewed-by: Viktor Dukhovni <viktor@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from #21133)

We split the page into two: one covering basic TLS introductory material that applies to both clients and servers, and one with the specific material on writing a blocking TLS client. Reviewed-by: Viktor Dukhovni <viktor@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from #21133)

Reviewed-by: Viktor Dukhovni <viktor@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from #21133)

Add a very simple blocking TLS client demo

d8dee05

This blocking client is intended to be used to explain how to implement a simple client in the documentation.

mattcaswell added branch: master Merge to master branch approval: review pending This pull request needs review by a committer approval: otc review pending This pull request needs review by an OTC member tests: exempted The PR is exempt from requirements for testing labels Jun 6, 2023

arapov assigned mattcaswell Jun 6, 2023

Add a tutorial on writing a simple blocking TLS client

b1085f2

Provide guidance on the steps needed to write a very simple blocking TLS client.

mattcaswell force-pushed the guide-blocking branch from c903317 to b1085f2 Compare June 6, 2023 15:41

arapov linked an issue Jun 6, 2023 that may be closed by this pull request

Writing a simple blocking TLS Client openssl/project#16

Closed

paulidale reviewed Jun 7, 2023

View reviewed changes

demos/guide/Makefile Outdated Show resolved Hide resolved

doc/man7/guide-tls-client-block.pod Outdated Show resolved Hide resolved

doc/man7/guide-tls-client-block.pod Outdated Show resolved Hide resolved

doc/man7/guide-tls-client-block.pod Outdated Show resolved Hide resolved

vdukhovni approved these changes Jun 7, 2023

View reviewed changes

mattcaswell added 4 commits June 7, 2023 12:10

Allow man7 pages to not have a DESCRIPTION section

5ebcc33

For tutorial type pages it doesn't make any sense to have a DESCRIPTION section.

fixup! Add a very simple blocking TLS client demo

524416d

fixup! Add a tutorial on writing a simple blocking TLS client

9b802eb

Split the blocking TLS client guide page into two

8dc3406

We split the page into two: one covering basic TLS introductory material that applies to both clients and servers, and one with the specific material on writing a blocking TLS client.

Fix minor issues in the demo/man pages for TLS client/blocking

390c7fe

paulidale approved these changes Jun 7, 2023

View reviewed changes

paulidale removed the approval: otc review pending This pull request needs review by an OTC member label Jun 7, 2023

vdukhovni approved these changes Jun 8, 2023

View reviewed changes

mattcaswell added 2 commits June 9, 2023 09:51

fixup! Add a very simple blocking TLS client demo

1ad7bb6

fixup! Fix minor issues in the demo/man pages for TLS client/blocking

1fa3ef4

vdukhovni approved these changes Jun 9, 2023

View reviewed changes

t8m closed this Jun 12, 2023

t8m reopened this Jun 12, 2023

paulidale approved these changes Jun 13, 2023

View reviewed changes

paulidale added approval: done This pull request has the required number of approvals and removed approval: review pending This pull request needs review by a committer labels Jun 13, 2023

openssl-machine added approval: ready to merge The 24 hour grace period has passed, ready to merge and removed approval: done This pull request has the required number of approvals labels Jun 14, 2023

paulidale closed this Jun 14, 2023

openssl-machine pushed a commit that referenced this pull request Jun 14, 2023

Fix minor issues in the demo/man pages for TLS client/blocking

edd5b9d

Reviewed-by: Viktor Dukhovni <viktor@openssl.org> Reviewed-by: Paul Dale <pauli@openssl.org> (Merged from #21133)

paulidale mentioned this pull request Jun 16, 2023

OMC requirements review openssl/project#34

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a tutorial on writing a simple blocking TLS client #21133

Add a tutorial on writing a simple blocking TLS client #21133

mattcaswell commented Jun 6, 2023

mattcaswell commented Jun 6, 2023

paulidale left a comment

vdukhovni left a comment

vdukhovni Jun 7, 2023

mattcaswell Jun 7, 2023

vdukhovni Jun 8, 2023

vdukhovni Jun 7, 2023

mattcaswell Jun 7, 2023

vdukhovni Jun 7, 2023

mattcaswell Jun 7, 2023

vdukhovni Jun 7, 2023

mattcaswell Jun 7, 2023

vdukhovni Jun 7, 2023

vdukhovni Jun 7, 2023

mattcaswell Jun 7, 2023

mattcaswell commented Jun 7, 2023

mattcaswell commented Jun 7, 2023

paulidale commented Jun 7, 2023

vdukhovni Jun 8, 2023

mattcaswell Jun 9, 2023

vdukhovni Jun 8, 2023

mattcaswell commented Jun 9, 2023

mattcaswell commented Jun 9, 2023

hlandau commented Jun 12, 2023

t8m commented Jun 12, 2023

openssl-machine commented Jun 14, 2023

paulidale commented Jun 14, 2023

Add a tutorial on writing a simple blocking TLS client #21133

Add a tutorial on writing a simple blocking TLS client #21133

Conversation

mattcaswell commented Jun 6, 2023

mattcaswell commented Jun 6, 2023

paulidale left a comment

Choose a reason for hiding this comment

vdukhovni left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mattcaswell commented Jun 7, 2023

mattcaswell commented Jun 7, 2023

paulidale commented Jun 7, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mattcaswell commented Jun 9, 2023

mattcaswell commented Jun 9, 2023

hlandau commented Jun 12, 2023

t8m commented Jun 12, 2023

openssl-machine commented Jun 14, 2023

paulidale commented Jun 14, 2023