Imported Upstream version 4.3.2.467

Former-commit-id: 9c2cb47f45fa221e661ab616387c9cda183f283d

mcs/class/Mono.Security.Providers.NewSystemSource/README.md

@@ -0,0 +1,95 @@
+Mono.Security.Interface / Mono.Security.Providers
+=================================================
+
+This is not a public API yet, but will eventually become public.
+
+
+Mono.Security.Interface
+-----------------------
+
+`Mono.Security.Interface` provides an abstraction layer for the TLS
+APIs that are currently being used by Mono's class libraries.
+
+The main API entry points are `MonoTlsProviderFactory.GetProvider()`
+and `MonoTlsProviderFactory.InstallProvider()`.
+
+Mono.Net.Security
+-----------------
+
+`Mono.Net.Security` provides the internal implementation and lives
+inside `System.dll` as private and internal APIs.  `Mono.Security.dll`
+uses reflection to access these.
+
+On Mobile, the `Mono.Security.Interface` APIs are included as public
+APIs in `System.dll`.
+
+Mono.Security.Providers
+-----------------------
+
+Implementations of the `Mono.Security.Interface.MonoTlsProvider` class
+to provide TLS functionality.
+
+The default provider is inside `System.dll` - it will be used automatically
+if you don't explicitly install a custom provider, so simply call
+`MonoTlsProviderFactory.GetProvider()` to use it.
+
+* DotNet:
+  Provides the default `SslStream` implementation from `System.dll`, only using
+  public .NET types.
+  
+* NewSystemSource:
+  Compiles several referencesource files which would normally live inside
+  `System.dll` if we compiled it with their `SslStream` implementation.
+  
+  This allows to keep the code in `System.dll` as-is, while still providing the
+  new `SslStream`, which will be required by the new TLS code.
+  
+  `System.dll` needs to make its internals visible and we're using several compiler /
+  external alias tricks in here to make this work.
+  
+  In this configuration, `MONO_SYSTEM_ALIAS`, `MONO_FEATURE_NEW_TLS` and
+  `MONO_FEATURE_NEW_SYSTEM_SOURCE` (defining conditional for this configuration)
+  are defined.  We do not define `MONO_X509_ALIAS here`.
+  
+The `Mono.Security.Providers.DotNet` and `Mono.Security.Providers.NewSystemSource` directory is currently
+enabled in the top-level `Makefile`, but the resulting binaries should only be used to test the new TLS
+code and not shipped as stable APIs.
+
+Pending changes
+---------------
+
+This code is not actually being used in `System.dll` yet.  I have some
+local changes which will switch the existing code in `WebClient`,
+`SmptClient` and `FtpWebRequest` over, but these need to be carefully
+tested.
+
+At the moment, this work branch only provides new code and build
+changes, which shuffle some stuff around.  There are also several
+new files which are conditional and not actually being built by
+default.
+
+Build Configurations
+--------------------
+
+* Normal build:
+  Builds everything as before with some new APIs added, but without
+  modifying any existing functionality.
+  
+* Build with the `newtls` profile:
+  Builds `System.dll` with the new `SslStream` implementation from the
+  referencesource.  This is currently a "build then throw away" profile
+  and not enabled from the top-level Makefile.  The resulting `System.dll`
+  won't actually work at runtime since it's missing the new TLS code;
+  building it helps find problems and ensures that it will actually
+  be possible to build this once we deploy it.
+
+* Mono.Security.Providers:
+  The new TLS code requires the newly built `System` and `Mono.Security.Providers.NewSystemSource`
+  from this branch installed in the system.  It is recommended to install it
+  into a custom prefix and set that as custom runtime in Xamarin Studio.
+
+
+Last changed March 07th, 2015,
+Martin Baulig <martin.baulig@xamarin.com>
+
+