mono/web/crypto

* Cryptography

	In the .NET framework cryptography can be found under a number of
	namespaces in several assemblies.

** Assembly: corlib

*** Namespace: <b>System.Security.Cryptography</b>

	Thanks to the work of many people this namespace is almost complete.

**** Status
	<ul>
		* All classes are present.

		* Most classes have their unit tests. Some tests like <code>
		  SymmetricAlgorithmTest</code> are generated by external 
		  tools.
	</ul>

**** TODO
	<ul>
		* <code>PasswordDeriveBytes.CryptDeriveKey</code> is included 
		  in MS BCL to provide compatibility with existing Windows 
		  applications. The main problem is that the key derivation 
		  algorithm can be different for every CSP (Crypto Service 
		  Provider). However for compatibility we should provide an
		  implementation compatible with the MS CSP (most likely used).
	</ul>

**** Notes
	<ul>
		* All cryptographic algorithms are entirely managed, including 
		  classes named <code>*CryptoServiceProvider</code>, with the 
		  exception of <code>RNGCryptoServiceProvider</code> for which 
		  parts of the implementation resides in the runtime.

		* There is a bug in the <code>PKCS1MaskGenerationMethod</code>
		  class (in both framework 1.0 and 1.1). This means our 
		  implementation isn't compatible with MS (but is compatible with
		  PKCS#1 v.2.1). However we get OAEP padding for every platform!

		* Look at assembly Mono.Security.Win32 if you require more
		  compatiblity with the Microsoft implementation (like accessing
		  a particuliar keypair container inside a specific CSP).
	</ul>


*** Namespace: <b>System.Security.Cryptography.X509Certificates</b>

**** Status
	<ul>
		* X.509 certificates are parsed using 100% managed code 
		  (using the Mono.Security.ASN1 class). 

		* Software Publisher Certificates (SPC) used by Authenticode
		  (tm) to sign assemblies are supported and <b>minimally</b>
		  validated.

		* Unit tests are generated from a set of existing certificates
		  (about a dozen) each having different properties. Another
		  set of certificates (more than 700) are used for a more 
		  complete test (but isn't part of the standard test suite for 
		  size and time consideration, i.e. a 7.5Mb C# source file).
	</ul>

**** Notes
	<ul>
		* Except for their structure <b>there are no validation of the
		  certificates</b> done by this class (this is by design and 
		  isn't a restriction of Mono!). This means that certificate 
		  signatures and validity dates are <b>never</b> checked 
		  (except when used for Authenticode, i.e. 
		  <code>CreateFromSignedFile</code>).

		* The newer X509Certificate class included in Microsoft's Web 
		  Service Enhancement (WSE) is a little better (as it includes 
		  CryptoAPI's validation) when <code>IsCurrent</code> is called.
		  See assembly <b>Microsoft.Web.Services</b> for more details.

		* The class Mono.Security.X509.X509Certificate (in Mono.Security 
		  assembly) is becoming a much better alternative - and will 
		  continue to evolve to support the security tools.

		* Microsoft implementation of <code>X509Certificate</code> is 
		  done by using CryptoAPI (unmanaged code). Based on the 
		  exceptions thrown, Authenticode(tm) support is done via COM.
	</ul>

<hr>
** Assembly: System.Security

*** Namespace: <b>System.Security.Cryptography.Xml</b>

	This namespace implements the <a href="http://www.w3.org/TR/xmldsig-core/">
	XML Digital Signature</a> specification from 
	<a href="http://www.w3.org/">W3C</a>.

**** Status
	<ul>
		* We pass the fifteen tests from Merlin's xmldsig suite with
		success. Which is funny because Microsoft fails in one case 
		where both a X509Certificate and an X509CRL are present in
		an X509Data.

		* We now have a fully managed C14N implementation.

		* Most classes have their unit tests.
	</ul>

<hr>
** Assembly: Mono.Security

	<b>Rational: </b>
	This assembly provides the missing pieces to .NET security. On Windows
	CryptoAPI is often used to provide much needed functionalities (like
	some cryptographic algorithms, code signing, X.509 certificates). Mono,
	for platform independance, implements these functionalities in 100% 
	managed code.

*** Namespace: Mono.Security
	<ul>
		* Structures (ASN1, PKCS7) and primitives (PKCS1).
	</ul>
*** Namespace: Mono.Security.Authenticode
	<ul>
		* Code signing and verification.
		* Support for SPC (Software Publisher Certificate) files and 
		  PVK (Private Key) files.
	</ul>
*** Namespace: Mono.Security.Cryptography
	<ul>
		* Additional algorithms: MD2, MD4, ARCFOUR (required for SSL)
		* Convertion helpers
	</ul>
*** Namespace: Mono.Security.Protocol.*
	<ul>
		* Tls: An 100% managed SSLv3 and TLSv1 implementation from 
		Carlos Guzman Alvarez.
		* Ntlm: NTLM authentication (used for HTTP and SQL Server).
	</ul>
*** Namespace: Mono.Security.X509
	<ul>
		* X.509 structures (certificate, CRL...) building and decoding.
		* PKCS#12 decoding and encoding.
	</ul>
*** Namespace: Mono.Security.X509.Extensions
	<ul>
		* X.509 extensions (from public X.509 to private PKIX, Netsapce, 
		  Microsoft, Entrust...).
	</ul>

**** Status
	<ul>
		* A big part of this assembly is also included inside Mono's
		  corlib. The classes are duplicated in this assembly so the 
		  functionalities can be used without a dependency on Mono's 
		  corlib (which depends on Mono's runtime).

		* Unit test coverage isn't (yet) complete.
	</ul>

<hr>
** Assembly: Mono.Security.Win32

	<b>Rational: </b>
	This assembly goal is to provide maximum compatibility with CryptoAPI
	to application running with Mono's runtime on the Windows operating 
	system.

	<b>This assembly should NEVER be used directly by any application</b>
	(e.g. referecing the assembly from a project).
	The classes should only be used by modifying the <code>machine.config
	</code> configuration file (and then only if this increased 
	compatibility is required by an application).

	See the file <code><a href="http://cvs.hispalinux.es/cgi-bin/cvsweb/~checkout~/mcs/class/Mono.Security.Win32/README?rev=1.1&content-type=text/plain&cvsroot=mono">/mcs/class/Mono.Security.Win32/README</a></code>
	for complete instructions.

*** Namespace: Mono.Security.Cryptography

**** Status
	<ul>
		* A RNGCryptoServiceProvider built on top of CryptoAPI. This
		  allows Windows users to get around the limitation of the 
		  runtime RNG (which requires <code>/dev/[u]random/</code>).

		* Wrapper classes for unmanaged versions of hash algorithms:
		  MD2, MD4, MD5 and SHA1 are supported. <b>note</b>: some 
		  algorithms shouldn't be used in new design (MD4 is broken, 
		  MD2 and MD5 aren't considered safe for some usage). They are 
		  included to preserve interoperability with older applications
		  (e.g. some old, but still valid, X.509 certificates use MD2,
		  MD4 is required for NTLM authentication ...).
	</ul>

**** TODO
	<ul>
		* Wrapper classes for unmanaged versions of symmetric 
		  encryption algorithms (like DES, TripleDES, RC2 and others 
		  present in default CSP).

		* Wrapper classes for unmanaged versions of asymmetric 
		  algorithms (like DSA and RSA) which persist their keypair 
		  into the specified CSP.
	</ul>

**** Ideas
	<ul>
		* Similar assemblies (e.g. <code>Mono.Security.XXX</code>) 
		  could be created for <a href="http://www.openssl.org">OpenSSL</a>,
		  <a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a>,
		  <a href="http://www.eskimo.com/~weidai/cryptlib.html">crypto++</a>,
		  <a href="http://www.cryptlib.orion.co.nz/">cryptlib</a> ... for 
		  improved performance and/or HSM (Hardware Security Module) support 
		  under Linux and/or Windows.
	</ul>
<hr>
** Assembly: Microsoft.Web.Services

	Microsoft Web Service Enhancement (WSE), known as Web Service 
	Development Kit (WSDK) in it's beta days, is an add-on the .NET
	framework that implements WS-Security (and other WS-* specifications).
	It also includes improved support for XML Signature (replacing and/or
	extending <code>System.Security.Cryptography.Xml</code>) and X.509
	certificates classes.

	Note: WSE is distributed as an add-on because some specifications,
 	like WS-Security, aren't yet completed by 
	<a href="http://www.oasis-open.org/committees/wss/">OASIS</a> or
	other committees.

*** Namespace: Microsoft.Web.Services.Security

**** Status
	<ul>
		* Most WSE 1.0 classes are implemented.
	</ul>

**** TODO
	<ul>
		* Some classes from System.Security assembly need to be 
		duplicated (and somewhat fixed) in WSE for XMLDSIG.

		* There are still missing classes and <b>many</b> missing
		unit tests.
	</ul>


*** Namespace: Microsoft.Web.Services.Timestamp

**** Status
	<ul>
		* This seems complete for WSE 1.0 but some new classes were 
		introduced in WSE 2.0.
	</ul>

*** Namespace: Microsoft.Web.Services.Security.X509

**** Status
	<ul>
		* X509Certificate support is complete for both WSE 1.0 and 2.0.
	</ul>

**** TODO
	<ul>
		* We need to define certificate stores (for both users and
		  machines). These sames stores must be linked with asymmetric
		  keypairs. This could also be used to store the SPC roots.
	</ul>

*** Notes
	<ul>
		* Microsoft has <a href="http://microsoft.com/downloads/details.aspx?FamilyId=21FB9B9A-C5F6-4C95-87B7-FC7AB49B3EDD&displaylang=en">released</a>
		a technical preview of WSE 2. <b>Note that WSDK (the technical 
		preview of WSE) had A LOT of changes before it's initial 
		release!</b>
	</ul>

<hr>
** Tools

	There are many tools in the .NET framework that indirectly interacts 
	with some cryptographic classes. Mono will eventually need these tools.
	Unless noted the tools should work on any CLR (tested with both Mono 
	and Microsoft).

**** Status

	The following tools are complete (or mostly complete):
	<ul>
		* <code>secutil</code> is a tool to extract certificates and 
		  strongnames from assemblies in a format that can be easily 
		  re-used in source code (C# or VB.NET syntax).

		* <code>cert2spc</code> is a tool to transform multiple X.509 
		   certificates and CRLs into a Software Publisher Certificate
		  (SPC) file - which is a long name for a simple PKCS#7 file.

		* <code>makecert</code> to create X.509 test certificates that 
		  can be used (once transformed in SPC) to sign assemblies. It's
		  now possible to generate SSL certificates for web servers.

		* <code>sn</code> is a clone of the <code>sn</code> to manage
		  strongnames. Current version can create, convert, sign and
		  verify strongnames signatures. Some configuration options 
		  are still missing.

		* <code>signcode</code> and <code>chktrust</code> for signing 
		  and validating Authenticode(tm) signatures on assemblies (or 
		  any PE file) are now working (signature and timestamps) but 
		  some options aren't yet supported.

		* <code>setreg</code> can change some cryptographic parameters
		of the runtime. Currently it can add or remove two root test
		certificates (the one used by Mono's <code>makecert</code>, 
		the other used by Microsoft's <code>makecert</code>).

		* <code>certmgr</code> can add and remove certificates from 
		the stores. Most common use is to add new trusted certificates
		or remove them.
	</ul>

	Somewhat usable, somewhat incomplete:
	<ul>
		* <code>certview</code> is a certificate viewer for 
		  <code>System.Windows.Forms</code> (right now only working on 
		  Windows), while <code>gcertview</code> is the same viewer 
		  implemented for GTK# (working on both Windows and Linux).

		* <code>monosn</code> is a clone of the <code>sn</code> to manage
		  strongnames. This tools is part of the runtime (not the class
		  library) and as such is written in C and won't run without Mono.
	</ul>


**** TODO
	The following tools are still missing or largely incomplete:
	<ul>
		* Other tools like a, GUI-based, certificate manager...
	</ul>

	Note that many of the tools requires the class library and/or the
	runtime to be ready for them. E.g. StrongName and Authenticode signatures
	tools are of limited use until supported by the runtime.

<hr>
** References

	<ul>
		* RSA Laboratories' <a href="http://www.rsasecurity.com/rsalabs/faq/index.html">
		Frequently Asked Questions</a> About Today's Cryptography, Version 4.1

		* Public-Key Cryptography Standards (<a href="http://www.rsasecurity.com/rsalabs/pkcs/index.html">
		PKCS</a>)

		* National Institute of Standards and Technology - Federal 
		Information Processing Standards <a href="http://csrc.nist.gov/publications/fips/index.html">
		NIST FIPS</a>
	</ul>

<hr>
** How to Help

	<ul>
		* Complete any of the TODO (and feel good about it ;-).

		* Analyse the current coverage of the unit tests on the 
		  cryptographic classes and complete the unit tests. <b><code>
		  monocov</code> does a great job at this! Now we just need to
		  complete the missing unit tests.</b>

		* Optimization can also be done on most algorithms as crypto 
		  is never fast enough. Some have been done using the 
		  Community Edition of BoundChecker (a free VisualStudio 
		  addon) - recommanded! Just be sure to test every optimization
		  (using the unit tests) carefully - it's so fast to break an
		  algorithm ;-).

		* Write some documentation on the cryptographic classes for 
		  <b>monodoc</b>.
	</ul>
<hr>
Last reviewed: March 20, 2004 (mono 0.31)