Support for STARTLS/STARTSSL in-band transport upgrades/renegotation

[dirkx]

Split start_ssl_client into two phases; to allow the implementation of protocols that use some sort of in-band STARTTLS or STARTSSL signal to upgrade a plaint text connection to SSL/TLS. Examples of these protocols are XMPP, SMTP and various database TCP connections.

Addresses #9099. An example has been included as part of the documentation.

Description of Change

Option for Inline upgrading from a clear-text connection to an SSL/TLS connection.

Some protocols such as SMTP, XMPP, Mysql, Postgress and others allow, or require,
that you start the connection without encryption; and then send a command to switch
over to encryption.

E.g. a typical SMTP submission would entail a dialogue such as this:

1. client connects to server in the clear
2. server says hello
3. client sents a EHLO
4. server tells the client that it supports SSL/TLS
5. client sends a 'STARTTLS' to make use of this faciltiy
6. client/server negiotiate a SSL or TLS connection.
7. client sends another EHLO
8. server now tells the client what (else) is supported; such as additional authentication options.
   ... conversation continues encrypted.

This can be enabled in WiFiClientSecure by telling it to start in plaintext:

      client.setPlainStart();

and client is than a plain, TCP, connection (just as WiFiClient would be); until the client calls
the method:

      client.startTLS(); // returns zero on error; non zero on success.

After which things switch to TLS/SSL.

Tests scenarios

Please describe on what Hardware and Software combinations you have tested this Pull Request and how.

ESP32, ESP32S

Related links

Addresses
#9099 and issues raised over the year in EMailSender and XMPPClient

[github-actions]

	Warnings
⚠️	Some issues found for the commit messages in this PR: the commit message "Apply suggestions from code review": summary looks empty type/action looks empty the commit message "Fix another \(rightfull\) compiler warning iwth the version pointer": summary looks empty type/action looks empty the commit message "Fix typo in directory name": summary looks empty type/action looks empty the commit message "Newer versions of MBEDTLS make the client key struct private (and most of the x509 struct too), so absent of a non-null pointer we cannot check wether it is populated. Solve this by looking at the version (as 0 is not a valid x509 version).": summary should not end with a period (full stop) summary looks empty type/action looks empty the commit message "Quell CI/CD runs on non-WiFi supporting hardare": summary looks empty type/action looks empty the commit message "Quell CI/CD runs on non-WiFi supporting hardare": summary looks empty type/action looks empty the commit message "Quell compiler warning; use the right timeout": summary looks empty type/action looks empty the commit message "Remove leftover file": summary looks empty type/action looks empty the commit message "Remove removed setTimeout that was accidentally included (was removed for IDF >=5), bring timeout inline with the other timeouts (ints), fix cert/key checks to look if there is actually something there (all issues caught by the CI/CD on windows-latest": summary looks empty type/action looks empty the commit message "Rename Files": summary looks empty type/action looks empty the commit message "Split start_ssl_client into two phases; to allow the implementation of protocols that use some sort of in-band STARTTLS or STARTSSL signal to upgrade a plaint text connection to SSL/TLS. Examples of these protocols are XMPP, SMTP and various database TCP connections.": summary should not end with a period (full stop) summary looks empty type/action looks empty Please fix these commit messages - here are some basic tips: follow Conventional Commits style correct format of commit message should be: <type/action>(<scope/component>): <summary>, for example fix(esp32): Fixed startup timeout issue allowed types are: change,ci,docs,feat,fix,refactor,remove,revert,test sufficiently descriptive message summary should be between 20 to 72 characters and start with upper case letter avoid Jira references in commit messages (unavailable/irrelevant for our customers) TIP: Install pre-commit hooks and run this check when committing (uses the Conventional Precommit Linter).
⚠️	Please consider squashing your 18 commits (simplifying branch history).

👋 Hello dirkx, we appreciate your contribution to this project!

---

Click to see more instructions ...

This automated output is generated by the PR linter DangerJS, which checks if your Pull Request meets the project's requirements and helps you fix potential issues.

DangerJS is triggered with each push event to a Pull Request and modify the contents of this comment.

Please consider the following:
- Danger mainly focuses on the PR structure and formatting and can't understand the meaning behind your code or changes.
- Danger is not a substitute for human code reviews; it's still important to request a code review from your colleagues.
- Resolve all warnings (⚠️ ) before requesting a review from human reviewers - they will appreciate it.
- To manually retry these Danger checks, please navigate to the Actions tab and re-run last Danger workflow.

Review and merge process you can expect ...

We do welcome contributions in the form of bug reports, feature requests and pull requests.

1. An internal issue has been created for the PR, we assign it to the relevant engineer.
2. They review the PR and either approve it or ask you for changes or clarifications.
3. Once the GitHub PR is approved we do the final review, collect approvals from core owners and make sure all the automated tests are passing.
- At this point we may do some adjustments to the proposed change, or extend it by adding tests or documentation.
4. If the change is approved and passes the tests it is merged into the default branch.

Generated by 🚫 dangerJS against 067d2cd

[me-no-dev]

@dirkx you need to add .skip.esp32h2 files in the example folders

[me-no-dev]

@lucasssvaz PTAL

[dirkx]

Apologies - will do - but paid customers intruding :)

[P-R-O-C-H-Y]

@dirkx PTAL on my comments

[dirkx]

Checked all the the changes & reran our testcases (against several mail provider (proton, freedom, against sendmail-sasl/etc, cyrus-imap, XMPP, OpenLDAP and against PosgreSQL) -- and nothing breaks.

AFAIK nothing from my end that needs to be done / anything you folks are waiting on from me ?

[lucasssvaz]

Checked all the the changes & reran our testcases (against several mail provider (proton, freedom, against sendmail-sasl/etc, cyrus-imap, XMPP, OpenLDAP and against PosgreSQL) -- and nothing breaks.

AFAIK nothing from my end that needs to be done / anything you folks are waiting on from me ?

This PR is all good. It is pending merge.