2007-01-29 Chris Toshok <toshok@ximian.com>

[mono.git] / web / crypto

diff --git a/web/crypto b/web/crypto
index 5a5ca7f68305fc22a60d2197a4e58dde117dbc14..56fbde78316e3f083ccb3948acc992ef7ce563bb 100644 (file)
--- a/web/crypto
+++ b/web/crypto
@@ -1,7 +1,8 @@
 * Cryptography
 
        In the .NET framework cryptography can be found under a number of
 * Cryptography
 
        In the .NET framework cryptography can be found under a number of

-       namespaces in several assemblies.
+       namespaces in several assemblies. Mono also has it's own assemblies
+       to provide missing security functionalities from the .NET framework.

 
 ** Assembly: corlib
 
 
 ** Assembly: corlib
 


@@ -11,93 +12,37 @@
 
 **** Status
        <ul>
 
 **** Status
        <ul>

-               * Every classes are present.
+               * All classes are present. Most of them have (minimal) 
+                 documentation in <b>monodoc</b>.

 
                * Most classes have their unit tests. Some tests like <code>
 
                * Most classes have their unit tests. Some tests like <code>

-                 SymmetricAlgorithmTest</code> are generated by an external 
-                 tool.
+                 SymmetricAlgorithmTest</code> are generated by external 
+                 tools.

        </ul>
 
        </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>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>
 *** Namespace: <b>System.Security.Cryptography.X509Certificates</b>
 
 **** Status
        <ul>

-               * X.509 certificates are parsed using 100% managed code. 
+               * X.509 certificates are parsed using 100% managed code 
+                 (using the Mono.Security.ASN1 class). 

 
                * Software Publisher Certificates (SPC) used by Authenticode
 
                * Software Publisher Certificates (SPC) used by Authenticode

-                 (tm) to sign assemblies are supported (extraction from PE 
-                 files) but <b>not</b> validated.
+                 (tm) to sign assemblies are supported and <b>minimally</b>
+                 validated.

 
 

-               * Tests are generated from a set of existing certificates
+               * Unit tests are generated from a set of existing certificates

                  (about a dozen) each having different properties. Another
                  (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 (on Windows) isn't possible as 
-                 long as the <code>X509Certificate(IntPtr)</code> constructor 
-                 isn't completed.
+                 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>
        </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 <b>never</b>
-                 checked!
-
-               * 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.
-
-               * Microsoft implementation of <code>X509Certificate</code> is 
-                 done by using CryptoAPI. From the exceptions thrown 
-                 Authenticode(tm) support is done via COM.
+               * 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.

        </ul>
 
 <hr>
        </ul>
 
 <hr>


@@ -111,55 +56,124 @@
 
 **** Status
        <ul>
 
 **** Status
        <ul>

-               * All classes are present but some are only stubbed.
+               * 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 also pass most Phaos tests.
+
+               * Most classes have their unit tests. Some standalone tests 
+               are also in CVS to test C14N and both Merlin and Phaos test
+               suites.
+       </ul>

 
 

-               * Most classes have their unit tests.
+<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.

 
 

-               * This assembly is present in CVS but only available when 
-                 building using NAnt (i.e. makefile are missing).
+*** 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.
+               * X.509 extensions (from public X.509 to private PKIX, Netsapce, 
+                 Microsoft, Entrust...).

        </ul>
 
        </ul>
 

-**** TODO
+**** Status

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

 
 

-               * Makefile for building under non-Windows operating systems.
+               * Most classes have minimal documentation available in
+                 <b>monodoc</b>.

        </ul>
 
 <hr>
 ** Assembly: Mono.Security.Win32
 
        </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.
 
        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>.
+       <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).
 
        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.
 
 *** Namespace: Mono.Security.Cryptography
 
 **** Status
        <ul>
                * A RNGCryptoServiceProvider built on top of CryptoAPI.
 

-               * Not (yet) commited in CVS - i'm still playing with the base
-                 classes so I can easily add other CryptoAPI-based algorithms.
+               * 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 ...).
+
+               * Classes have minimal documentation available in
+                 <b>monodoc</b>.

        </ul>
 
 **** TODO
        <ul>
        </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.
+               * 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>
 
        </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
 
 <hr>
 ** Assembly: Microsoft.Web.Services
 


@@ -167,30 +181,44 @@
        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
        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 
-       <a href="http://www.oasis-open.org/committees/wss/">OASIS</a>.
+       extending <code>System.Security.Cryptography.Xml</code>) and X.509
+       certificates classes.

 
 

-       <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>
+       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>
 
 *** Namespace: Microsoft.Web.Services.Security
 
 **** Status
        <ul>

-               * Nothing (yet) commited in CVS.
+               * 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>
        </ul>
 
 *** Namespace: Microsoft.Web.Services.Security.X509
 
 **** Status
        <ul>

-               * Nothing (yet) commited in CVS.
+               * X509Certificate support is complete for both WSE 1.0 and 2.0.

        </ul>
 
 **** TODO
        </ul>
 
 **** TODO


@@ -200,76 +228,108 @@
                  keypairs. This could also be used to store the SPC roots.
        </ul>
 
                  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:
-
+*** Notes

        <ul>
        <ul>

-               * SSL/TLS for secure communication (investigation under way).
-       
-               * Assembly signing (and verification) using StrongNames.
-       
-               * Assembly signing (and verification) using Authenticode(tm).
+               * Microsoft has released WSE 2.

        </ul>
 
        </ul>
 

-
-*** Tools
+<hr>
+** Tools

 
        There are many tools in the .NET framework that indirectly interacts 
 
        There are many tools in the .NET framework that indirectly interacts 

-       with some cryptographic classes. Mono will eventually need these tools.
+       with some cryptographic classes. Unless noted the tools should work on
+       any CLR (tested with both Mono and Microsoft).

 
 **** Status
 
 
 **** Status
 

-       The following tools are complete:
+       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 
        <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>
+                  certificates and CRLs into a Software Publisher Certificate
+                 (SPC) file - which is a long name for a simple PKCS#7 file.

 
 

-**** 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>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, some will only works with Mono.

 
                * <code>signcode</code> and <code>chktrust</code> for signing 
 
                * <code>signcode</code> and <code>chktrust</code> for signing 

-                 and validating  Authenticode(tm) signatures on assemblies.
+                 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).
+       </ul>

 
 

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

 
 

+**** 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
                * 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.
+       runtime to be ready for them. E.g. StrongName and Authenticode signatures
+       tools are of limited use until supported by the runtime.

 
 

-<hr>   
-** How to Help
+<hr>
+** References

 
 

-       Complete any of the TODO (and feel good about it ;-).
+       <ul>
+               * RSA Laboratories' <a href="http://www.rsasecurity.com/rsalabs/faq/index.html">
+               Frequently Asked Questions</a> About Today's Cryptography, Version 4.1

 
 

-       Add missing unit tests to classes or methods.
+               * Public-Key Cryptography Standards (<a href="http://www.rsasecurity.com/rsalabs/pkcs/index.html">
+               PKCS</a>)

 
 

-       Write some documentation on the cryptographic classes for MonkeyGuide
-       (as I'm not a good writer, at least in English, but you must be a good
-       reader if you got to this part).
+               * National Institute of Standards and Technology - Federal 
+               Information Processing Standards <a href="http://csrc.nist.gov/publications/fips/index.html">
+               NIST FIPS</a>
+       </ul>

 
 

-       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 ;-).
+<hr>
+** How to Help

 
 

-       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.
+       <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 or add some sample code for the 
+                 cryptographic classes in <b>monodoc</b>.
+       </ul>

 <hr>
 <hr>

-Last reviewed: January 19, 2003 (post mono 0.18)
+Last reviewed: June 26, 2004 (mono release candidate 1)