Next to including several files, our "common.h" header also declares
various macros which are then used throughout the project. As such, we
have to make sure to always include this file first in all
implementation files. Otherwise, we might encounter problems or even
silent behavioural differences due to macros or defines not being
defined as they should be. So in fact, our header and implementation
files should make sure to always include "common.h" first.

This commit does so by establishing a common include pattern. Header
files inside of "src" will now always include "common.h" as its first
other file, separated by a newline from all the other includes to make
it stand out as special. There are two cases for the implementation
files. If they do have a matching header file, they will always include
this one first, leading to "common.h" being transitively included as
first file. If they do not have a matching header file, they instead
include "common.h" as first file themselves.

This fixes the outlined problems and will become our standard practice
for header and source files inside of the "src/" from now on.

OpenSSL v1.1 has introduced a new way of initializing the library
without having to call various functions of different subsystems. In
libgit2, we have been adapting to that change with 88520151
(openssl_stream: use new initialization function on OpenSSL version
>=1.1, 2017-04-07), where we added an #ifdef depending on the OpenSSL
version. This change broke building with libressl, though, which has not
changed its API in the same way.

Fix the issue by expanding the #ifdef condition to use the old way of
initializing with libressl.

Signed-off-by: Marc-Antoine Perennou <Marc-Antoine@Perennou.com>

Previous to OpenSSL version 1.1, the user had to initialize at least the error
strings as well as the SSL algorithms by himself. OpenSSL version 1.1 instead
provides a new function `OPENSSL_init_ssl`, which handles initialization of all
subsystems. As the new API call will by default load error strings and
initialize the SSL algorithms, we can safely replace these calls when compiling
against version 1.1 or later.

This fixes a compiler error when compiling against OpenSSL version 1.1 which has
been built without stubs for deprecated syntax.

Up to version 1.0, OpenSSL required us to provide a callback which implements
a locking mechanism. Due to problems in the API design though this mechanism was
inherently broken, especially regarding that the locking callback cannot report
errors in an obvious way. Due to this shortcoming, the locking initialization
has been completely removed in OpenSSL version 1.1. As the library has also been
refactored to not make any use of these callback functions, we can safely remove
all initialization of the locking subsystem if compiling against OpenSSL version
1.1 or higher.

This fixes a compilation error when compiling against OpenSSL version 1.1 which
has been built without stubs for deprecated syntax.

The OpenSSL library may require multiple locks to work correctly, where
it is the caller's responsibility to initialize and release the locks.
While we correctly initialized up to `n` locks, as determined by
`CRYPTO_num_locks`, we were repeatedly freeing the same mutex in our
shutdown procedure.

Fix the issue by freeing locks at the correct index.

Error messages should be sentence fragments, and therefore:

1. Should not begin with a capital letter,
2. Should not conclude with punctuation, and
3. Should not end a sentence and begin a new one

For older versions we can fall back on the deprecated ASN1_STRING_data.

We want to program against the interface, so recreate it when we compile
against pre-1.1 versions.

Closes: https://github.com/libgit2/libgit2/issues/3959
Signed-off-by: Igor Gnatenko <i.gnatenko.brain@gmail.com>

openssl_read should return -1 in case of error.

SSL_read returns values <= 0 in case of error.

A return value of 0 can lead to an infinite loop, so the return value
of ssl_set_error will be returned if SSL_read is not successful (analog
to openssl_write).

This ensures that when using OpenSSL a safe default set of ciphers
is selected. This is done so that the client communicates securely
and we don't accidentally enable unsafe ciphers like RC4, or even
worse some old export ciphers.

Implements the first part of https://github.com/libgit2/libgit2/issues/3682

This got lost duing the move and it lets the users call this function
just in case.

We need to include the header where we define the function. Otherwise it
won't be available on the DLL.

SSL_shutdown() does not like it when we pass an unitialized ssl context
to it. This means that when we fail to connect to a host, we hide the
error message saying so with OpenSSL's indecipherable error message.

Versions prior to 0.9.8f  did not have this function, rhel/centos5 are still on a
heavily backported version of 0.9.8e and theoretically supported until March 2017

Without this ifdef, I get the following link failure:
```
CMakeFiles/libgit2_clar.dir/src/openssl_stream.c.o: In function `openssl_connect':
openssl_stream.c:(.text+0x45a): undefined reference to `SSL_set_tlsext_host_name'
collect2: error: ld returned 1 exit status
make[6]: *** [libgit2_clar] Error 1
```

We do not want libcurl to perform the TLS negotiation for us, so we
don't need to pass this option.

When linking against libcurl, use it as the underlying transport instead
of straight sockets. We can't quite just give over the file descriptor,
as curl puts it into non-blocking mode, so we build a custom BIO so
OpenSSL sends the data through our stream, be it the socket or curl
streams.

This can be used by tools to show mesages about failing to communicate
with the server. The error message in this case will often contain the
server's error message, as far as it managed to send anything.

We use a blocking socket and set the mode to AUTO_RETRY which means that
`SSL_write` and `SSL_read` will only return once the read or write has
been completed. We therefore don't need to handle partial writes or
re-try read due to a regenotiation.

While here, consider that a zero also indicates an error condition.

This is what it's meant all along, but now we actually have multiple
implementations, it's clearer to use the name of the library.

Windows headers #define some names that openssl uses too. Openssl
headers #undef the offending names before reusing them. But if those
offending Windows headers get included after the openssl headers the
namespace is polluted and nothing good happens.

Fixes issue #2850.

This mainly concerns mingw build.

This fixes the build at least on FreeBSD, where those types were not
defined indirectly:

src/openssl_stream.c:100:18: error: variable has incomplete type 'struct in6_addr'
        struct in6_addr addr6;
                        ^
src/openssl_stream.c:100:9: note: forward declaration of 'struct in6_addr'
        struct in6_addr addr6;
               ^
src/openssl_stream.c:111:18: error: use of undeclared identifier 'AF_INET'
        if (p_inet_pton(AF_INET, host, &addr4)) {
                        ^
src/unix/posix.h:31:40: note: expanded from macro 'p_inet_pton'
                                       ^
src/openssl_stream.c:115:18: error: use of undeclared identifier 'AF_INET6'
                if(p_inet_pton(AF_INET6, host, &addr6)) {
                               ^
src/unix/posix.h:31:40: note: expanded from macro 'p_inet_pton'
                                       ^

Most of the network-facing facilities have been copied to the socket and
openssl streams. No code now uses these functions directly anymore, so
we can now remove them.