Closes #822

This commit is several drafts squashed together. The changes from each
draft are noted below. If any changes are similar and possibly
contradictory the change in the latest draft takes precedence.

Bug: https://github.com/bagder/curl/issues/244
Reported-by: Chris Araman

%%
%% Draft 1
%%
- return 0 if len == 0. that will have to be documented.
- continue on and process the caches regardless of raw recv
- if decrypted data will be returned then set the error code to CURLE_OK
and return its count
- if decrypted data will not be returned and the connection has closed
(eg nread == 0) then return 0 and CURLE_OK
- if decrypted data will not be returned and the connection *hasn't*
closed then set the error code to CURLE_AGAIN --only if an error code
isn't already set-- and return -1
- narrow the Win2k workaround to only Win2k

%%
%% Draft 2
%%
- Trying out a change in flow to handle corner cases.

%%
%% Draft 3
%%
- Back out the lazier decryption change made in draft2.

%%
%% Draft 4
%%
- Some formatting and branching changes
- Decrypt all encrypted cached data when len == 0
- Save connection closed state
- Change special Win2k check to use connection closed state

%%
%% Draft 5
%%
- Default to CURLE_AGAIN in cleanup if an error code wasn't set and the
connection isn't closed.

%%
%% Draft 6
%%
- Save the last error only if it is an unrecoverable error.

Prior to this I saved the last error state in all cases; unfortunately
the logic to cover that in all cases would lead to some muddle and I'm
concerned that could then lead to a bug in the future so I've replaced
it by only recording an unrecoverable error and that state will persist.

- Do not recurse on renegotiation.

Instead we'll continue on to process any trailing encrypted data
received during the renegotiation only.

- Move the err checks in cleanup after the check for decrypted data.

In either case decrypted data is always returned but I think it's easier
to understand when those err checks come after the decrypted data check.

%%
%% Draft 7
%%
- Regardless of len value go directly to cleanup if there is an
unrecoverable error or a close_notify was already received. Prior to
this change we only acknowledged those two states if len != 0.

- Fix a bug in connection closed behavior: Set the error state in the
cleanup, because we don't know for sure it's an error until that time.

- (Related to above) In the case the connection is closed go "greedy"
with the decryption to make sure all remaining encrypted data has been
decrypted even if it is not needed at that time by the caller. This is
necessary because we can only tell if the connection closed gracefully
(close_notify) once all encrypted data has been decrypted.

- Do not renegotiate when an unrecoverable error is pending.

%%
%% Draft 8
%%
- Don't show 'server closed the connection' info message twice.

- Show an info message if server closed abruptly (missing close_notify).

Removed the curl_ prefix from the schannel source files as discussed
with Marc and Daniel at FOSDEM.

Slight code cleanup as the SSL backend #define is mixed up with the API
function setup.

Prefer void for unused parameters, rather than assigning an argument to
itself as a) unintelligent compilers won't optimize it out, b) it can't
be used for const parameters, c) it will cause compilation warnings for
clang with -Wself-assign and d) is inconsistent with other areas of the
curl source code.

Moved our Initialize Security Context return attribute definitions to
the SSPI module, as a) these can be used by other SSPI based providers
and b) the ISC required attributes are defined there.

curl_schannel.h:123: warning: right-hand operand of comma expression
                     has no effect

Some instances of the curlssl_close_all() function were declared with a
void return type whilst others as int. The schannel version returned
CURLE_NOT_BUILT_IN and others simply returned zero, but in all cases the
return code was ignored by the calling function Curl_ssl_close_all().

For the time being and to keep the internal API consistent, changed all
declarations to use a void return type.

To reduce code we might want to consider removing the unimplemented
versions and use a void #define like schannel does.

- do not grow memory by doubling its size
- do not leak previously allocated memory if reallocation fails
- replace while-loop with a single check to make sure
  that the requested amount of data fits into the buffer

Bug: http://curl.haxx.se/bug/view.cgi?id=1450
Reported-by: Warren Menzer

vtls.c:688:43: warning: unused parameter 'data'

This function is available for every Windows version since Windows 95/NT.

reference:
http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942.aspx

Each backend now defines CURL_SSL_BACKEND accordingly. Added the *AXTLS
one which was missing previously.

This commit renames lib/setup.h to lib/curl_setup.h and
renames lib/setup_once.h to lib/curl_setup_once.h.

Removes the need and usage of a header inclusion guard foreign
to libcurl. [1]

Removes the need and presence of an alarming notice we carried
in old setup_once.h [2]

----------------------------------------

1 - lib/setup_once.h used __SETUP_ONCE_H macro as header inclusion guard
    up to commit ec691ca3 which changed this to HEADER_CURL_SETUP_ONCE_H,
    this single inclusion guard is enough to ensure that inclusion of
    lib/setup_once.h done from lib/setup.h is only done once.

    Additionally lib/setup.h has always used __SETUP_ONCE_H macro to
    protect inclusion of setup_once.h even after commit ec691ca3, this
    was to avoid a circular header inclusion triggered when building a
    c-ares enabled version with c-ares sources available which also has
    a setup_once.h header. Commit ec691ca3 exposes the real nature of
    __SETUP_ONCE_H usage in lib/setup.h, it is a header inclusion guard
    foreign to libcurl belonging to c-ares's setup_once.h

    The renaming this commit does, fixes the circular header inclusion,
    and as such removes the need and usage of a header inclusion guard
    foreign to libcurl. Macro __SETUP_ONCE_H no longer used in libcurl.

2 - Due to the circular interdependency of old lib/setup_once.h and the
    c-ares setup_once.h header, old file lib/setup_once.h has carried
    back from 2006 up to now days an alarming and prominent notice about
    the need of keeping libcurl's and c-ares's setup_once.h in sync.

    Given that this commit fixes the circular interdependency, the need
    and presence of mentioned notice is removed.

    All mentioned interdependencies come back from now old days when
    the c-ares project lived inside a curl subdirectory. This commit
    removes last traces of such fact.

This reverts renaming and usage of lib/*.h header files done
28-12-2012, reverting 2 commits:

  f871de00... build: make use of 76 lib/*.h renamed files
  ffd8e127... build: rename 76 lib/*.h files

This also reverts removal of redundant include guard (redundant thanks
to changes in above commits) done 2-12-2013, reverting 1 commit:

  c087374c... curl_setup.h: remove redundant include guard

This also reverts renaming and usage of lib/*.c source files done
3-12-2013, reverting 3 commits:

  13606bbf... build: make use of 93 lib/*.c renamed files
  5b6e7927... build: rename 93 lib/*.c files
  7d83dfff... build: commit 13606bbf follow-up 1

Start of related discussion thread:

  http://curl.haxx.se/mail/lib-2013-01/0012.html

Asking for confirmation on pushing this revertion commit:

  http://curl.haxx.se/mail/lib-2013-01/0048.html

Confirmation summary:

  http://curl.haxx.se/mail/lib-2013-01/0079.html

NOTICE: The list of 2 files that have been modified by other
intermixed commits, while renamed, and also by at least one
of the 6 commits this one reverts follows below. These 2 files
will exhibit a hole in history unless git's '--follow' option
is used when viewing logs.

  lib/curl_imap.h
  lib/curl_smtp.h

76 private header files renamed to use our standard naming scheme.

This change affects 322 files in libcurl's source tree.

Since there are servers that seem to return very big encrypted
data packages, we need to be able to handle those without having
an internal size limit. To avoid the buffer growing to fast to
early the initial size was decreased and the minimum free space
in the buffer was decreased as well.

Increase decrypted and encrypted cache buffers using limitted
doubling strategy. More information on the mailinglist:
http://curl.haxx.se/mail/lib-2012-06/0255.html

It updates the two remaining reallocations that have already been there
and fixes the other one to use the same "do we need to increase the
buffer"-condition as the other two.  CURL_SCHANNEL_BUFFER_STEP_SIZE was
renamed to CURL_SCHANNEL_BUFFER_FREE_SIZE since that is actually what it
is now.  Since we don't know how much more data we are going to read
during the handshake, CURL_SCHANNEL_BUFFER_FREE_SIZE is used as the
minimum free space required in the buffer for the next operation.
CURL_SCHANNEL_BUFFER_STEP_SIZE was used for that before, too, but since
we don't have a step size now, the define was renamed.

Make the Schannel implementation use libcurl's default buffer size
for the initial received encrypted and decrypted data cache buffers.
The implementation still needs to handle more data since more data
might have already been received or decrypted during the handshake
or a read operation which needs to be cached for the next read.

Version number is removed in order to make this info consistent with
how we do it with other MS and Linux system libraries for which we don't
provide this info.

Identifier changed from 'WinSSPI' to 'schannel' given that this is the
actual provider of the SSL/TLS support. libcurl can still be built with
SSPI and without SCHANNEL support.

curl_sspi.c: Fixed mingw32-gcc compiler warnings
curl_sspi.c: Fixed length of error code hex output

The hex value was printed as signed 64-bit value on 64-bit systems:
SEC_E_WRONG_PRINCIPAL (0xFFFFFFFF80090322)

It is now correctly printed as the following:
SEC_E_WRONG_PRINCIPAL (0x80090322)

curl_sspi.c: Fallback to security function table version number
Instead of reporting an unknown version, the interface version is used.

curl_sspi.c: Removed SSPI/ version prefix from Curl_sspi_version
curl_schannel: Replaced static buffer sizes with defined names
curl_schannel.c: First brace when declaring functions on column 0
curl_schannel.c: Put the pointer sign directly at variable name
curl_schannel.c: Use structs directly instead of typedef'ed structs
curl_schannel.c: Removed space before opening brace
curl_schannel.c: Fixed lines being longer than 80 chars

Moved type definitions in order to avoid inclusion loop

Stop the abuse of CURLE_FAILED_INIT as return code for things not being
init related by introducing two new return codes:

CURLE_NOT_BUILT_IN and CURLE_UNKNOWN_OPTION

CURLE_NOT_BUILT_IN replaces return code 4 that has been obsoleted for
several years. It is used for returning error when something is
attempted to be used but the feature/option was not enabled or
explictitly disabled at build-time. Getting this error mostly means that
libcurl needs to be rebuilt.

CURLE_FAILED_INIT is now saved and used strictly for init
failures. Getting this problem means something went seriously wrong,
like a resource shortage or similar.

CURLE_UNKNOWN_OPTION is the option formerly known as
CURLE_UNKNOWN_TELNET_OPTION (and the old name is still present,
separately defined to be removed in a very distant future). This error
code is meant to be used to return when an option is given to libcurl
that isn't known. This problem would mostly indicate a problem in the
program that uses libcurl.

Howard Chu brought the bulk work of this patch that properly
moves out the sending and recving of data to the parts of the
code that are properly responsible for the various ways of doing
so.

Daniel Stenberg assisted with polishing a few bits and fixed some
minor flaws in the original patch.

Another upside of this patch is that we now abuse CURLcodes less
with the "magic" -1 return codes and instead use CURLE_AGAIN more
consistently.

This is Hoi-Ho Chan's patch with some minor fixes by me. There
are some potential issues in this, but none worse than we can
sort out on the list and over time.