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

   1 Mono.Security.Interface / Mono.Security.Providers
   2 =================================================
   3
   4 This is not a public API yet, but will eventually become public.
   5
   6
   7 Mono.Security.Interface
   8 -----------------------
   9
  10 `Mono.Security.Interface` provides an abstraction layer for the TLS
  11 APIs that are currently being used by Mono's class libraries.
  12
  13 The main API entry points are `MonoTlsProviderFactory.GetProvider()`
  14 and `MonoTlsProviderFactory.InstallProvider()`.
  15
  16 Mono.Net.Security
  17 -----------------
  18
  19 `Mono.Net.Security` provides the internal implementation and lives
  20 inside `System.dll` as private and internal APIs.  `Mono.Security.dll`
  21 uses reflection to access these.
  22
  23 On Mobile, the `Mono.Security.Interface` APIs are included as public
  24 APIs in `System.dll`.
  25
  26 Mono.Security.Providers
  27 -----------------------
  28
  29 Implementations of the `Mono.Security.Interface.MonoTlsProvider` class
  30 to provide TLS functionality.
  31
  32 The default provider is inside `System.dll` - it will be used automatically
  33 if you don't explicitly install a custom provider, so simply call
  34 `MonoTlsProviderFactory.GetProvider()` to use it.
  35
  36 * DotNet:
  37   Provides the default `SslStream` implementation from `System.dll`, only using
  38   public .NET types.
  39
  40 * NewSystemSource:
  41   Compiles several referencesource files which would normally live inside
  42   `System.dll` if we compiled it with their `SslStream` implementation.
  43
  44   This allows to keep the code in `System.dll` as-is, while still providing the
  45   new `SslStream`, which will be required by the new TLS code.
  46
  47   `System.dll` needs to make its internals visible and we're using several compiler /
  48   external alias tricks in here to make this work.
  49
  50   In this configuration, `MONO_SYSTEM_ALIAS`, `MONO_FEATURE_NEW_TLS` and
  51   `MONO_FEATURE_NEW_SYSTEM_SOURCE` (defining conditional for this configuration)
  52   are defined.  We do not define `MONO_X509_ALIAS here`.
  53
  54 The `Mono.Security.Providers.DotNet` and `Mono.Security.Providers.NewSystemSource` directory is currently
  55 enabled in the top-level `Makefile`, but the resulting binaries should only be used to test the new TLS
  56 code and not shipped as stable APIs.
  57
  58 Pending changes
  59 ---------------
  60
  61 This code is not actually being used in `System.dll` yet.  I have some
  62 local changes which will switch the existing code in `WebClient`,
  63 `SmptClient` and `FtpWebRequest` over, but these need to be carefully
  64 tested.
  65
  66 At the moment, this work branch only provides new code and build
  67 changes, which shuffle some stuff around.  There are also several
  68 new files which are conditional and not actually being built by
  69 default.
  70
  71 Build Configurations
  72 --------------------
  73
  74 * Normal build:
  75   Builds everything as before with some new APIs added, but without
  76   modifying any existing functionality.
  77
  78 * Build with the `newtls` profile:
  79   Builds `System.dll` with the new `SslStream` implementation from the
  80   referencesource.  This is currently a "build then throw away" profile
  81   and not enabled from the top-level Makefile.  The resulting `System.dll`
  82   won't actually work at runtime since it's missing the new TLS code;
  83   building it helps find problems and ensures that it will actually
  84   be possible to build this once we deploy it.
  85
  86 * Mono.Security.Providers:
  87   The new TLS code requires the newly built `System` and `Mono.Security.Providers.NewSystemSource`
  88   from this branch installed in the system.  It is recommended to install it
  89   into a custom prefix and set that as custom runtime in Xamarin Studio.
  90
  91
  92 Last changed March 07th, 2015,
  93 Martin Baulig <martin.baulig@xamarin.com>
  94
  95