web/crypto

   1 * Cryptography
   2
   3         In the .NET framework cryptography can be found under a number of
   4         namespaces in several assemblies. Mono also has it's own assemblies
   5         to provide missing security functionalities from the .NET framework.
   6
   7 ** Assembly: corlib
   8
   9 *** Namespace: <b>System.Security.Cryptography</b>
  10
  11         Thanks to the work of many people this namespace is almost complete.
  12
  13 **** Status
  14         <ul>
  15                 * All classes are present. Most of them have (minimal)
  16                   documentation in <b>monodoc</b>.
  17
  18                 * Most classes have their unit tests. Some tests like <code>
  19                   SymmetricAlgorithmTest</code> are generated by external
  20                   tools.
  21         </ul>
  22
  23 *** Namespace: <b>System.Security.Cryptography.X509Certificates</b>
  24
  25 **** Status
  26         <ul>
  27                 * X.509 certificates are parsed using 100% managed code
  28                   (using the Mono.Security.ASN1 class).
  29
  30                 * Software Publisher Certificates (SPC) used by Authenticode
  31                   (tm) to sign assemblies are supported and <b>minimally</b>
  32                   validated.
  33
  34                 * Unit tests are generated from a set of existing certificates
  35                   (about a dozen) each having different properties. Another
  36                   set of certificates (more than 700) are used for a more
  37                   complete test (but isn't part of the standard test suite for
  38                   size and time consideration, i.e. a 7.5Mb C# source file).
  39         </ul>
  40
  41 **** Notes
  42         <ul>
  43                 * The class Mono.Security.X509.X509Certificate (in Mono.Security
  44                   assembly) is becoming a much better alternative - and will
  45                   continue to evolve to support the security tools.
  46         </ul>
  47
  48 <hr>
  49 ** Assembly: System.Security
  50
  51 *** Namespace: <b>System.Security.Cryptography.Xml</b>
  52
  53         This namespace implements the <a href="http://www.w3.org/TR/xmldsig-core/">
  54         XML Digital Signature</a> specification from
  55         <a href="http://www.w3.org/">W3C</a>.
  56
  57 **** Status
  58         <ul>
  59                 * We pass the fifteen tests from Merlin's xmldsig suite with
  60                 success. Which is funny because Microsoft fails in one case
  61                 where both a X509Certificate and an X509CRL are present in
  62                 an X509Data. We also pass most Phaos tests.
  63
  64                 * Most classes have their unit tests. Some standalone tests
  65                 are also in CVS to test C14N and both Merlin and Phaos test
  66                 suites.
  67         </ul>
  68
  69 <hr>
  70 ** Assembly: Mono.Security
  71
  72         <b>Rational: </b>
  73         This assembly provides the missing pieces to .NET security. On Windows
  74         CryptoAPI is often used to provide much needed functionalities (like
  75         some cryptographic algorithms, code signing, X.509 certificates). Mono,
  76         for platform independance, implements these functionalities in 100%
  77         managed code.
  78
  79 *** Namespace: Mono.Security
  80         <ul>
  81                 * Structures (ASN1, PKCS7) and primitives (PKCS1).
  82         </ul>
  83 *** Namespace: Mono.Security.Authenticode
  84         <ul>
  85                 * Code signing and verification.
  86                 * Support for SPC (Software Publisher Certificate) files and
  87                   PVK (Private Key) files.
  88         </ul>
  89 *** Namespace: Mono.Security.Cryptography
  90         <ul>
  91                 * Additional algorithms: MD2, MD4, ARCFOUR (required for SSL)
  92                 * Convertion helpers
  93         </ul>
  94 *** Namespace: Mono.Security.Protocol.*
  95         <ul>
  96                 * Tls: An 100% managed SSLv3 and TLSv1 implementation from
  97                 Carlos Guzman Alvarez.
  98                 * Ntlm: NTLM authentication (used for HTTP and SQL Server).
  99         </ul>
 100 *** Namespace: Mono.Security.X509.*
 101         <ul>
 102                 * X.509 structures (certificate, CRL...) building and decoding.
 103                 * PKCS#12 decoding and encoding.
 104                 * X.509 extensions (from public X.509 to private PKIX, Netsapce,
 105                   Microsoft, Entrust...).
 106         </ul>
 107
 108 **** Status
 109         <ul>
 110                 * A big part of this assembly is also included inside Mono's
 111                   corlib. The classes are duplicated in this assembly so the
 112                   functionalities can be used without a dependency on Mono's
 113                   corlib (which depends on Mono's runtime).
 114
 115                 * Unit test coverage isn't (yet) complete.
 116
 117                 * Most classes have minimal documentation available in
 118                   <b>monodoc</b>.
 119         </ul>
 120
 121 <hr>
 122 ** Assembly: Mono.Security.Win32
 123
 124         <b>Rational: </b>
 125         This assembly goal is to provide maximum compatibility with CryptoAPI
 126         to application running with Mono's runtime on the Windows operating
 127         system.
 128
 129         <b>This assembly should NEVER be used directly by any application</b>
 130         (e.g. referecing the assembly from a project).
 131         The classes should only be used by modifying the <code>machine.config
 132         </code> configuration file (and then only if this increased
 133         compatibility is required by an application).
 134
 135         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>
 136         for complete instructions.
 137
 138 *** Namespace: Mono.Security.Cryptography
 139
 140 **** Status
 141         <ul>
 142                 * A RNGCryptoServiceProvider built on top of CryptoAPI.
 143
 144                 * Wrapper classes for unmanaged versions of hash algorithms:
 145                   MD2, MD4, MD5 and SHA1 are supported. <b>note</b>: some
 146                   algorithms shouldn't be used in new design (MD4 is broken,
 147                   MD2 and MD5 aren't considered safe for some usage). They are
 148                   included to preserve interoperability with older applications
 149                   (e.g. some old, but still valid, X.509 certificates use MD2,
 150                   MD4 is required for NTLM authentication ...).
 151
 152                 * Classes have minimal documentation available in
 153                   <b>monodoc</b>.
 154         </ul>
 155
 156 **** TODO
 157         <ul>
 158                 * Wrapper classes for unmanaged versions of symmetric
 159                   encryption algorithms (like DES, TripleDES, RC2 and others
 160                   present in default CSP).
 161
 162                 * Wrapper classes for unmanaged versions of asymmetric
 163                   algorithms (like DSA and RSA) which persist their keypair
 164                   into the specified CSP.
 165         </ul>
 166
 167 **** Ideas
 168         <ul>
 169                 * Similar assemblies (e.g. <code>Mono.Security.XXX</code>)
 170                   could be created for <a href="http://www.openssl.org">OpenSSL</a>,
 171                   <a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a>,
 172                   <a href="http://www.eskimo.com/~weidai/cryptlib.html">crypto++</a>,
 173                   <a href="http://www.cryptlib.orion.co.nz/">cryptlib</a> ... for
 174                   improved performance and/or HSM (Hardware Security Module) support
 175                   under Linux and/or Windows.
 176         </ul>
 177 <hr>
 178 ** Assembly: Microsoft.Web.Services
 179
 180         Microsoft Web Service Enhancement (WSE), known as Web Service
 181         Development Kit (WSDK) in it's beta days, is an add-on the .NET
 182         framework that implements WS-Security (and other WS-* specifications).
 183         It also includes improved support for XML Signature (replacing and/or
 184         extending <code>System.Security.Cryptography.Xml</code>) and X.509
 185         certificates classes.
 186
 187         Note: WSE is distributed as an add-on because some specifications,
 188         like WS-Security, aren't yet completed by
 189         <a href="http://www.oasis-open.org/committees/wss/">OASIS</a> or
 190         other committees.
 191
 192 *** Namespace: Microsoft.Web.Services.Security
 193
 194 **** Status
 195         <ul>
 196                 * Most WSE 1.0 classes are implemented.
 197         </ul>
 198
 199 **** TODO
 200         <ul>
 201                 * Some classes from System.Security assembly need to be
 202                 duplicated (and somewhat fixed) in WSE for XMLDSIG.
 203
 204                 * There are still missing classes and <b>many</b> missing
 205                 unit tests.
 206         </ul>
 207
 208
 209 *** Namespace: Microsoft.Web.Services.Timestamp
 210
 211 **** Status
 212         <ul>
 213                 * This seems complete for WSE 1.0 but some new classes were
 214                 introduced in WSE 2.0.
 215         </ul>
 216
 217 *** Namespace: Microsoft.Web.Services.Security.X509
 218
 219 **** Status
 220         <ul>
 221                 * X509Certificate support is complete for both WSE 1.0 and 2.0.
 222         </ul>
 223
 224 **** TODO
 225         <ul>
 226                 * We need to define certificate stores (for both users and
 227                   machines). These sames stores must be linked with asymmetric
 228                   keypairs. This could also be used to store the SPC roots.
 229         </ul>
 230
 231 *** Notes
 232         <ul>
 233                 * Microsoft has released WSE 2.
 234         </ul>
 235
 236 <hr>
 237 ** Tools
 238
 239         There are many tools in the .NET framework that indirectly interacts
 240         with some cryptographic classes. Unless noted the tools should work on
 241         any CLR (tested with both Mono and Microsoft).
 242
 243 **** Status
 244
 245         The following tools are complete (or mostly complete):
 246         <ul>
 247                 * <code>secutil</code> is a tool to extract certificates and
 248                   strongnames from assemblies in a format that can be easily
 249                   re-used in source code (C# or VB.NET syntax).
 250
 251                 * <code>cert2spc</code> is a tool to transform multiple X.509
 252                    certificates and CRLs into a Software Publisher Certificate
 253                   (SPC) file - which is a long name for a simple PKCS#7 file.
 254
 255                 * <code>makecert</code> to create X.509 test certificates that
 256                   can be used (once transformed in SPC) to sign assemblies. It's
 257                   now possible to generate SSL certificates for web servers.
 258
 259                 * <code>sn</code> is a clone of the <code>sn</code> to manage
 260                   strongnames. Current version can create, convert, sign and
 261                   verify strongnames signatures. Some configuration options
 262                   are still missing, some will only works with Mono.
 263
 264                 * <code>signcode</code> and <code>chktrust</code> for signing
 265                   and validating Authenticode(tm) signatures on assemblies (or
 266                   any PE file) are now working (signature and timestamps) but
 267                   some options aren't yet supported.
 268
 269                 * <code>setreg</code> can change some cryptographic parameters
 270                 of the runtime. Currently it can add or remove two root test
 271                 certificates (the one used by Mono's <code>makecert</code>,
 272                 the other used by Microsoft's <code>makecert</code>).
 273
 274                 * <code>certmgr</code> can add and remove certificates from
 275                 the stores. Most common use is to add new trusted certificates
 276                 or remove them.
 277         </ul>
 278
 279         Somewhat usable, somewhat incomplete:
 280         <ul>
 281                 * <code>certview</code> is a certificate viewer for
 282                   <code>System.Windows.Forms</code> (right now only working on
 283                   Windows), while <code>gcertview</code> is the same viewer
 284                   implemented for GTK# (working on both Windows and Linux).
 285         </ul>
 286
 287
 288 **** TODO
 289         The following tools are still missing or largely incomplete:
 290         <ul>
 291                 * Other tools like a, GUI-based, certificate manager...
 292         </ul>
 293
 294         Note that many of the tools requires the class library and/or the
 295         runtime to be ready for them. E.g. StrongName and Authenticode signatures
 296         tools are of limited use until supported by the runtime.
 297
 298 <hr>
 299 ** References
 300
 301         <ul>
 302                 * RSA Laboratories' <a href="http://www.rsasecurity.com/rsalabs/faq/index.html">
 303                 Frequently Asked Questions</a> About Today's Cryptography, Version 4.1
 304
 305                 * Public-Key Cryptography Standards (<a href="http://www.rsasecurity.com/rsalabs/pkcs/index.html">
 306                 PKCS</a>)
 307
 308                 * National Institute of Standards and Technology - Federal
 309                 Information Processing Standards <a href="http://csrc.nist.gov/publications/fips/index.html">
 310                 NIST FIPS</a>
 311         </ul>
 312
 313 <hr>
 314 ** How to Help
 315
 316         <ul>
 317                 * Complete any of the TODO (and feel good about it ;-).
 318
 319                 * Analyse the current coverage of the unit tests on the
 320                   cryptographic classes and complete the unit tests. <b><code>
 321                   monocov</code> does a great job at this! Now we just need to
 322                   complete the missing unit tests.</b>
 323
 324                 * Optimization can also be done on most algorithms as crypto
 325                   is never fast enough. Some have been done using the
 326                   Community Edition of BoundChecker (a free VisualStudio
 327                   addon) - recommanded! Just be sure to test every optimization
 328                   (using the unit tests) carefully - it's so fast to break an
 329                   algorithm ;-).
 330
 331                 * Write some documentation or add some sample code for the
 332                   cryptographic classes in <b>monodoc</b>.
 333         </ul>
 334 <hr>
 335 Last reviewed: June 26, 2004 (mono release candidate 1)