mono/doc/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>
		* Every classes are present.

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

**** TODO
	<ul>
		* Support for adding/modifying algorithms and OID using the
		  <code>machine.config</code> configuration file (in progress).

		* RNGCryptoServiceProvider is currently only working on Linux.
		  The current implementation reside in Mono's runtime and use 
		  the <code>/dev/[u]random</code> device (which do not exists 
		  under Windows). A Windows alternative is in the work...

		* Keypair persistance for RSA and DSA. This persistance must
		  somehow be linked with X509 certificate stores (in planning).

		* <code>MACTripleDES</code> is not functionnal. There are many 
		  differents and conflicting standards about how to do MAC 
		  (NIST has two, ANSI has one, maybe the framework is using 
		  yet another). We just have to figure out which one it is.

		* <code>PasswordDeriveBytes</code> is currently limited to 
		  generating keys with the maximum length equals to the hash 
		  output (as specified in PKCS #5). However the framework 
		  implementation allows for longer keys to be generated. Also 
		  the algorithms used by CryptDeriveKey (used by Windows 
		  applications) are unknown.

		* Analyse the current coverage of the unit tests on the 
		  cryptographic classes and complete the unit tests.

		* Optimizations (performance) on most class are possible. Some
		  have been done using the Community Edition of BoundChecker 
		  (a free VisualStudio addon) - recommanded!
	</ul>

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


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

**** Status
	<ul>
		* X.509 certificates are parsed using 100% managed code. 

		* Software Publisher Certificates (SPC) used by Authenticode
		  (tm) to sign assemblies are supported (extraction from PE 
		  files) but <b>not</b> validated.

		* Tests are generated from a set of existing certificates
		  (about a dozen) each having different properties. Another
		  set of certificates (more than 300) are used for a more 
		  complete test (but isn't part of the test suite for size
		  and time consideration).
	</ul>

**** TODO
	<ul>
		* Authenticode(tm) support is incomplete. We can extract the
		  certificates from PE files but cannot validate the signature
		  nor the certificate chain (and we're still missing some trust
		  anchors).

		* Integration with CryptoAPI isn't possible as long as the
		  <code>X509Certificate(IntPtr)</code> constructor isn't 
		  completed.
	</ul>

**** Notes
	<ul>
		* <b>There's no validation of the certificates</b> done in this
		  class (this isn't a restriction of Mono!). This means that
		  certificate signatures and validity dates are never checked!

		* The newer X509Certificate class included in Microsoft's Web 
		  Service Enhancement (WSE) is a little better (as it includes 
		  validation).

		* Microsoft implementation of <code>X509Certificate</code> is 
		  done by using CryptoAPI. From 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 XML Digital Signature specification from
	W3C.

**** Status
	<ul>
		* All classes are present but some are only stubbed.

		* Most classes have their unit tests.

		* This assembly is present in CVS but isn't (yet) part of the 
		  build.
	</ul>

**** TODO
	<ul>
		* All the transforms needs to be done. But this requires far 
		  more XML knowledge than crypto.

		* Fix the tests (see notes) then include the assembly into the
		  build process.
	</ul>

**** Notes
	<ul>
		* Many current tests fails because the XML generated by Mono
		  isn't exactly the same as the one produced by the Microsoft
		  implementation (but 100% equivalent). We'll either have to
		  change the XML code or the tests.

		* Testing is difficult because the classes use CryptoConfig
		  to create the required cryptographic objects. When running
		  the unit tests the CryptoConfig executing is the one in
		  mscorlib (not Mono's one) so it doesn't return the expected
		  objects. This results in InvalidCastException.
	</ul>

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

	This assembly 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>.
	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).

*** Namespace: Mono.Security.Cryptography

**** Status
	<ul>
		* A RNGCryptoServiceProvider built on top of CryptoAPI.

		* Not (yet) commited in CVS.
	</ul>

**** TODO
	<ul>
		* Unmanaged versions of hash algorithms (SHA1 and MD5).
		* Unmanaged versions of symmetric encryption algorithms 
		  (like DES, TripleDES, RC2 and others present in CryptoAPI).
		* Unmanaged versions of asymmetric algorithms (like DSA and 
		  RSA) which persist their keypair into the specified CSP.
	</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 X509
	certificates.

	Note: WSE is distributed as an add-on because the WS-Security 
	specification isn't yet completed by OASIS.

	<b>There are some licensing issues to consider before stating to 
	implement WS-Security. All contributors must sign an agreement with 
	Microsoft before commiting anything related to WS-Security into CVS.
	</b>

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

**** Status
	<ul>
		* Nothing (yet) commited in CVS.
	</ul>

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

**** Status
	<ul>
		* Nothing (yet) commited in CVS.
	</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>

<hr>
** Other stuff

	There are other, not so visible, uses of cryptography both inside and
	outside the class library - such as:

	<ul>
		* SSL/TLS for secure communication (investigation under way).
	
		* Assembly signing (and verification) using StrongNames.
	
		* Assembly signing (and verification) using Authenticode(tm).
	</ul>


*** Tools

	There are many tools in the .NET framework that indirectly interacts 
	with some cryptographic classes. Mono will eventually need these tools.

**** Status

	The following tools are 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 (a chain) into a Software Publisher Certificate
		  (SPC) - which is a long name for a simple PKCS#7 file.
	</ul>

**** TODO
	The following tools are still missing or incomplete:
	<ul>
		* <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.

		* <code>signcode</code> and <code>chktrust</code> for signing 
		  and validating  Authenticode(tm) signatures on assemblies.

		* <code>makecert</code> to create X.509 test certificates that 
		  can be used (once transformed in SPC) to sign assemblies.

		* 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.

<hr>	
** How to Help

	Complete any of the TODO (and feel good about it ;-).

	Add missing unit tests to classes or methods.

	Write some documentation on the cryptographic classes for MonkeyGuide
	(as I'm not a good writer - but you must be a good reader if you got to 
	this part).

	Optimization can also be done on algorithms as crypto is never fast 
	enough. Just be sure to test every optimization (using the unit test)
	carefully - it's so fast to break an algorithm ;-).

	Contact Sebastien Pouliot (<a href="mailto:[email protected]">home</a>
	, <a href="mailto:[email protected]">work</a>) if you need additional
	informations about the status of the cryptographic classes.