path: root/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>
		* Every classes are present.

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

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

		* 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 specific alternative is available 
		  using the Mono.Security.Win32 assembly.

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

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

		* 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).
		* Look at assembly Mono.Security.Win32 if you require more
		  compatiblity with the Microsoft implementation (like accessing
		  a particuliar keypair container in a 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 (extraction from PE 
		  files) but <b>not</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 300) are used for a more 
		  complete test (but isn't part of the standard 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). See Tools section for more information.

		* Integration with CryptoAPI (on Windows) isn't possible as 
		  long as the <code>X509Certificate(IntPtr)</code> constructor 
		  isn't completed.
	</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.

		* Microsoft implementation of <code>X509Certificate</code> is 
		  done by using CryptoAPI (unmanaged code). 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 <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>
		* All classes are present but some (most Transforms) are only 
		  stubbed.

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

**** TODO
	<ul>
		* All the transforms needs to be done. But this requires far 
		  more XML knowledge than crypto. Note: Most tests runs because
		  the feeded XML is pre-c14n (by hand in the code) before 
		  signing (not because the transforms works). In the short
		  term <code>libxml2</code> could be used to provide C14N, but 
		  in the long term a fully managed class would be much better.
	</ul>

<hr>
** Assembly: Mono.Security

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

*** Namespace: Mono.Security
*** Namespace: Mono.Security.Authenticode
*** Namespace: Mono.Security.Cryptography
*** Namespace: Mono.Security.X509
*** Namespace: Mono.Security.X509.Extensions

**** Status
	<ul>
		* Work has been under way for quite some time - and should 
		  start hitting CVS soon.

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

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

	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>.
	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. 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 and
		  MD2 isn't considered safe). They are included to preserve
		  interoperability with older applications (e.g. some old, but 
		  still valid, X.509 certificates use MD2).
	</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>

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

	<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
*** Namespace: Microsoft.Web.Services.Timestamp

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

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

**** Status
	<ul>
		* Nothing (yet) commited in CVS. However the classes in this 
		  namespace are outside WS-Security scope. So development 
		  could be done without signing any agreements.
	</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>
** 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:
	<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.
	</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 and won't run without Mono.

		* <code>signcode</code> and <code>chktrust</code> (in progress)
		  for signing and validating Authenticode(tm) signatures on 
		  assemblies (or any PE file).

		* <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>
** Other stuff

	<ul>
		* SSL/TLS for secure communication (a prototype is under way).
	</ul>


<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 the 
	<a href="http://go-mono.com/tutorial/html/en/index.html">Mono 
	Handbook</a> as I'm not a good writer (at least in English).

	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:spouliot@videotron.ca">home</a>
	, <a href="mailto:spouliot@motus.com">work</a>) if you need additional
	informations about the status of the cryptographic classes.

<hr>
Last reviewed: March 4, 2003 (post mono 0.21)