doc/crypto

   1 * Cryptography
   2
   3         In the .NET framework cryptography can be found under a number of
   4         namespaces in several assemblies.
   5
   6 ** Assembly: corlib
   7
   8 *** Namespace: <b>System.Security.Cryptography</b>
   9
  10         Thanks to the work of many people this namespace is almost complete.
  11
  12 **** Status
  13         <ul>
  14                 * Every classes are present.
  15
  16                 * Most classes have their unit tests. Some tests like <code>
  17                   SymmetricAlgorithmTest</code> are generated by an external
  18                   tool.
  19         </ul>
  20
  21 **** TODO
  22         <ul>
  23                 * Support for adding/modifying OID using the
  24                   <code>machine.config</code> configuration file (algorithms
  25                   are done).
  26
  27                 * RNGCryptoServiceProvider is currently only working on Linux.
  28                   The current implementation reside in Mono's runtime and use
  29                   the <code>/dev/[u]random</code> device (which do not exists
  30                   under Windows). A Windows specific alternative is available
  31                   using the Mono.Security.Win32 assembly.
  32
  33                 * Keypair persistance for RSA and DSA. This persistance must
  34                   somehow be linked with X509 certificate stores (in planning).
  35
  36                 * <code>PasswordDeriveBytes.CryptDeriveKey</code> is included
  37                   in MS BCL to provide compatibility with existing Windows
  38                   applications. The main problem is that the key derivation
  39                   algorithm can be different for every CSP (Crypto Service
  40                   Provider). However for compatibility we should provide an
  41                   implementation compatible with the MS CSP (most likely used).
  42
  43                 * Analyse the current coverage of the unit tests on the
  44                   cryptographic classes and complete the unit tests.
  45
  46                 * Optimizations (performance) on most class are possible. Some
  47                   have been done using the Community Edition of BoundChecker
  48                   (a free VisualStudio addon) - recommanded!
  49         </ul>
  50
  51 **** Notes
  52         <ul>
  53                 * All cryptographic algorithms are entirely managed, including
  54                   classes named <code>*CryptoServiceProvider</code>, with the
  55                   exception of <code>RNGCryptoServiceProvider</code> (which
  56                   resides in the runtime).
  57                 * Look at assembly Mono.Security.Win32 if you require more
  58                   compatiblity with the Microsoft implementation (like accessing
  59                   a particuliar keypair container in a CSP).
  60         </ul>
  61
  62
  63 *** Namespace: <b>System.Security.Cryptography.X509Certificates</b>
  64
  65 **** Status
  66         <ul>
  67                 * X.509 certificates are parsed using 100% managed code
  68                   (using the Mono.Security.ASN1 class).
  69
  70                 * Software Publisher Certificates (SPC) used by Authenticode
  71                   (tm) to sign assemblies are supported (extraction from PE
  72                   files) but <b>not</b> validated.
  73
  74                 * Unit tests are generated from a set of existing certificates
  75                   (about a dozen) each having different properties. Another
  76                   set of certificates (more than 300) are used for a more
  77                   complete test (but isn't part of the standard test suite for
  78                   size and time consideration).
  79         </ul>
  80
  81 **** TODO
  82         <ul>
  83                 * Authenticode(tm) support is incomplete. We can extract the
  84                   certificates from PE files but cannot validate the signature
  85                   nor the certificate chain (and we're still missing some trust
  86                   anchors). See Tools section for more information.
  87
  88                 * Integration with CryptoAPI (on Windows) isn't possible as
  89                   long as the <code>X509Certificate(IntPtr)</code> constructor
  90                   isn't completed.
  91         </ul>
  92
  93 **** Notes
  94         <ul>
  95                 * Except for their structure <b>there are no validation of the
  96                   certificates</b> done by this class (this is by design and
  97                   isn't a restriction of Mono!). This means that certificate
  98                   signatures and validity dates are <b>never</b> checked
  99                   (except when used for Authenticode, i.e.
 100                   <code>CreateFromSignedFile</code>).
 101
 102                 * The newer X509Certificate class included in Microsoft's Web
 103                   Service Enhancement (WSE) is a little better (as it includes
 104                   CryptoAPI's validation) when <code>IsCurrent</code> is called.
 105                   See assembly <b>Microsoft.Web.Services</b> for more details.
 106
 107                 * Microsoft implementation of <code>X509Certificate</code> is
 108                   done by using CryptoAPI (unmanaged code). From the exceptions
 109                   thrown Authenticode(tm) support is done via COM.
 110         </ul>
 111
 112 <hr>
 113 ** Assembly: System.Security
 114
 115 *** Namespace: <b>System.Security.Cryptography.Xml</b>
 116
 117         This namespace implements the <a href="http://www.w3.org/TR/xmldsig-core/">
 118         XML Digital Signature</a> specification from
 119         <a href="http://www.w3.org/">W3C</a>.
 120
 121 **** Status
 122         <ul>
 123                 * All classes are present but some (most Transforms) are only
 124                   stubbed.
 125
 126                 * Most classes have their unit tests.
 127         </ul>
 128
 129 **** TODO
 130         <ul>
 131                 * All the transforms needs to be done. But this requires far
 132                   more XML knowledge than crypto. Note: Most tests runs because
 133                   the feeded XML is pre-c14n (by hand in the code) before
 134                   signing (not because the transforms works). In the short
 135                   term <code>libxml2</code> could be used to provide C14N, but
 136                   in the long term a fully managed class would be much better.
 137         </ul>
 138
 139 <hr>
 140 ** Assembly: Mono.Security
 141
 142         This assembly provides the missing pieces to .NET security. On Windows
 143         CryptoAPI is often used to provide much needed functionalities (like
 144         some cryptographic algorithms, code signing, X.509 certificates).
 145
 146 *** Namespace: Mono.Security
 147 *** Namespace: Mono.Security.Authenticode
 148 *** Namespace: Mono.Security.Cryptography
 149 *** Namespace: Mono.Security.X509
 150 *** Namespace: Mono.Security.X509.Extensions
 151
 152 **** Status
 153         <ul>
 154                 * Work has been under way for quite some time - and should
 155                   start hitting CVS soon.
 156
 157                 * A big part of this assembly is also included inside Mono's
 158                   corlib. The class are duplicated in this assembly so the
 159                   functionalities can be used with a dependency on Mono's
 160                   corlib (which depends on Mono's runtime).
 161         </ul>
 162
 163 <hr>
 164 ** Assembly: Mono.Security.Win32
 165
 166         This assembly goal is to provide maximum compatibility with CryptoAPI
 167         to application running with Mono's runtime on the Windows operating
 168         system.
 169
 170         <b>This assembly should NEVER be used directly by any application</b>.
 171         The classes should only be used by modifying the <code>machine.config
 172         </code> configuration file (and then only if this increased
 173         compatibility is required by an application).
 174
 175 *** Namespace: Mono.Security.Cryptography
 176
 177 **** Status
 178         <ul>
 179                 * A RNGCryptoServiceProvider built on top of CryptoAPI. This
 180                   allows Windows users to get around the limitation of the
 181                   runtime RNG (which requires <code>/dev/[u]random/</code>).
 182
 183                 * Wrapper classes for unmanaged versions of hash algorithms:
 184                   MD2, MD4, MD5 and SHA1 are supported. <b>note</b>: some
 185                   algorithms shouldn't be used in new design (MD4 is broken and
 186                   MD2 isn't considered safe). They are included to preserve
 187                   interoperability with older applications (e.g. some old, but
 188                   still valid, X.509 certificates use MD2).
 189         </ul>
 190
 191 **** TODO
 192         <ul>
 193                 * Wrapper classes for unmanaged versions of symmetric
 194                   encryption algorithms (like DES, TripleDES, RC2 and others
 195                   present in default CSP).
 196                 * Wrapper classes for unmanaged versions of asymmetric
 197                   algorithms (like DSA and RSA) which persist their keypair
 198                   into the specified CSP.
 199         </ul>
 200
 201 <hr>
 202 ** Assembly: Microsoft.Web.Services
 203
 204         Microsoft Web Service Enhancement (WSE), known as Web Service
 205         Development Kit (WSDK) in it's beta days, is an add-on the .NET
 206         framework that implements WS-Security (and other WS-* specifications).
 207         It also includes improved support for XML Signature (replacing and/or
 208         extending <code>System.Security.Cryptography.Xml</code>) and X.509
 209         certificates classes.
 210
 211         Note: WSE is distributed as an add-on because some specifications,
 212         like WS-Security, aren't yet completed by
 213         <a href="http://www.oasis-open.org/committees/wss/">OASIS</a> or
 214         other committees.
 215
 216         <b>[*] There are some licensing issues to consider before stating to
 217         implement WS-Security. All contributors must sign an agreement with
 218         Microsoft before commiting anything related to WS-Security into CVS.
 219         </b>
 220
 221 *** Namespace: Microsoft.Web.Services.Security
 222 *** Namespace: Microsoft.Web.Services.Timestamp
 223
 224 **** Status
 225         <ul>
 226                 * Nothing (yet) commited in CVS <b>[*]</b>.
 227         </ul>
 228
 229 *** Namespace: Microsoft.Web.Services.Security.X509
 230
 231 **** Status
 232         <ul>
 233                 * Nothing (yet) commited in CVS. However the classes in this
 234                   namespace are outside WS-Security scope. So development
 235                   could be done without signing any agreements.
 236         </ul>
 237
 238 **** TODO
 239         <ul>
 240                 * We need to define certificate stores (for both users and
 241                   machines). These sames stores must be linked with asymmetric
 242                   keypairs. This could also be used to store the SPC roots.
 243         </ul>
 244
 245 <hr>
 246 ** Tools
 247
 248         There are many tools in the .NET framework that indirectly interacts
 249         with some cryptographic classes. Mono will eventually need these tools.
 250         Unless noted the tools should work on any CLR (tested with both Mono
 251         and Microsoft).
 252
 253 **** Status
 254
 255         The following tools are complete:
 256         <ul>
 257                 * <code>secutil</code> is a tool to extract certificates and
 258                   strongnames from assemblies in a format that can be easily
 259                   re-used in source code (C# or VB.NET syntax).
 260
 261                 * <code>cert2spc</code> is a tool to transform multiple X.509
 262                    certificates and CRLs into a Software Publisher Certificate
 263                   (SPC) file - which is a long name for a simple PKCS#7 file.
 264         </ul>
 265
 266 **** TODO
 267         The following tools are still missing or incomplete:
 268         <ul>
 269                 * <code>monosn</code> is a clone of the <code>sn</code> to manage
 270                   strongnames. This tools is part of the runtime (not the class
 271                   library) and as such is written in C and won't run without Mono.
 272
 273                 * <code>signcode</code> and <code>chktrust</code> (in progress)
 274                   for signing and validating Authenticode(tm) signatures on
 275                   assemblies (or any PE file).
 276
 277                 * <code>makecert</code> to create X.509 test certificates that
 278                   can be used (once transformed in SPC) to sign assemblies.
 279
 280                 * Other tools like a, GUI-based, certificate manager...
 281         </ul>
 282
 283         Note that many of the tools requires the class library and/or the
 284         runtime to be ready for them.
 285
 286 <hr>
 287 ** Other stuff
 288
 289         <ul>
 290                 * SSL/TLS for secure communication (a prototype is under way).
 291         </ul>
 292
 293
 294 <hr>
 295 ** How to Help
 296
 297         Complete any of the TODO (and feel good about it ;-).
 298
 299         Add missing unit tests to classes or methods.
 300
 301         Write some documentation on the cryptographic classes for the
 302         <a href="http://go-mono.com/tutorial/html/en/index.html">Mono
 303         Handbook</a> as I'm not a good writer (at least in English).
 304
 305         Optimization can also be done on algorithms as crypto is never fast
 306         enough. Just be sure to test every optimization (using the unit test)
 307         carefully - it's so fast to break an algorithm ;-).
 308
 309         Contact Sebastien Pouliot (<a href="mailto:spouliot@videotron.ca">home</a>
 310         , <a href="mailto:spouliot@motus.com">work</a>) if you need additional
 311         informations about the status of the cryptographic classes.
 312
 313 <hr>
 314 Last reviewed: March 4, 2003 (post mono 0.21)