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.
  17         </ul>
  18
  19 **** TODO
  20         <ul>
  21                 * Support for adding/modifying algorithms and OID using the
  22                   <code>machine.config</code> configuration file (in progress).
  23
  24                 * RNGCryptoServiceProvider is currently only working on Linux.
  25                   The current implementation reside in Mono's runtime and use
  26                   the <code>/dev/[u]random</code> device (which do not exists
  27                   under Windows). A Windows alternative is in the work...
  28
  29                 * Keypair persistance for RSA and DSA. This persistance must
  30                   somehow be linked with X509 certificate stores (in planning).
  31
  32                 * <code>PasswordDeriveBytes</code> is currently limited to
  33                   generating keys with the maximum length equals to the hash
  34                   output (as specified in PKCS #5). However the framework
  35                   implementation allows for longer keys to be generated. Also
  36                   the algorithms used by CryptDeriveKey (used by Windows
  37                   applications) are unknown.
  38
  39                 * Analyse the current coverage of the unit tests on the
  40                   cryptographic classes and complete the unit tests.
  41
  42                 * Optimizations (performance) on most class are possible. Some
  43                   have been done using the Community Edition of BoundChecker
  44                   (a free VisualStudio addon) - recommanded!
  45         </ul>
  46
  47 **** Notes
  48         <ul>
  49                 * All cryptographic algorithms are entirely managed, including
  50                   classes named <code>*CryptoServiceProvider</code>, with the
  51                   exception of <code>RNGCryptoServiceProvider</code> (which
  52                   resides in the runtime).
  53         </ul>
  54
  55
  56 *** Namespace: <b>System.Security.Cryptography.X509Certificates</b>
  57
  58 **** Status
  59         <ul>
  60                 * X.509 certificates are parsed using 100% managed code.
  61
  62                 * Software Publisher Certificates (SPC) used by Authenticode
  63                   (tm) to sign assemblies are supported (extraction from PE
  64                   files) but <b>not</b> validated.
  65
  66                 * Tests are generated from a set of existing certificates
  67                   (about a dozen) each having different properties. Another
  68                   set of certificates (more than 300) are used for a more
  69                   complete test (but isn't part of the test suite for size
  70                   and time consideration).
  71         </ul>
  72
  73 **** TODO
  74         <ul>
  75                 * Authenticode(tm) support is incomplete. We can extract the
  76                   certificates from PE files but cannot validate the signature
  77                   nor the certificate chain (and we're still missing some trust
  78                   anchors).
  79
  80                 * Integration with CryptoAPI isn't possible as long as the
  81                   <code>X509Certificate(IntPtr)</code> constructor isn't
  82                   completed.
  83         </ul>
  84
  85 **** Notes
  86         <ul>
  87                 * <b>There's no validation of the certificates</b> done in this
  88                   class (this isn't a restriction of Mono!). This means that
  89                   certificate signatures and validity dates are never checked!
  90
  91                 * The newer X509Certificate class included in Microsoft's Web
  92                   Service Enhancement (WSE) is a little better (as it includes
  93                   validation).
  94
  95                 * Microsoft implementation of <code>X509Certificate</code> is
  96                   done by using CryptoAPI. From the exceptions thrown
  97                   Authenticode(tm) support is done via COM.
  98         </ul>
  99
 100 <hr>
 101 ** Assembly: System.Security
 102
 103 *** Namespace: <b>System.Security.Cryptography.Xml</b>
 104
 105         This namespace implements the XML Digital Signature specification from
 106         W3C.
 107
 108 **** Status
 109         <ul>
 110                 * All classes are present but some are only stubbed.
 111
 112                 * Most classes have their unit tests.
 113
 114                 * This assembly is present in CVS but isn't (yet) part of the
 115                   build.
 116         </ul>
 117
 118 **** TODO
 119         <ul>
 120                 * All the transforms needs to be done. But this requires far
 121                   more XML knowledge than crypto.
 122
 123                 * Fix the tests (see notes) then include the assembly into the
 124                   build process.
 125         </ul>
 126
 127 **** Notes
 128         <ul>
 129                 * Many current tests fails because the XML generated by Mono
 130                   isn't exactly the same as the one produced by the Microsoft
 131                   implementation (but 100% equivalent). We'll either have to
 132                   change the XML code or the tests.
 133
 134                 * Testing is difficult because the classes use CryptoConfig
 135                   to create the required cryptographic objects. When running
 136                   the unit tests the CryptoConfig executing is the one in
 137                   mscorlib (not Mono's one) so it doesn't return the expected
 138                   objects. This results in InvalidCastException.
 139         </ul>
 140
 141 <hr>
 142 ** Assembly: Mono.Security.Win32
 143
 144         This assembly is to provide maximum compatibility with CryptoAPI to
 145         application running with Mono's runtime on the Windows operating
 146         system.
 147
 148         <b>This assembly should NEVER be used directly by any application</b>.
 149         The classes should only be used by modifying the <code>machine.config
 150         </code> configuration file (and then only if this increased
 151         compatibility is required by an application).
 152
 153 *** Namespace: Mono.Security.Cryptography
 154
 155 **** Status
 156         <ul>
 157                 * A RNGCryptoServiceProvider built on top of CryptoAPI.
 158
 159                 * Not (yet) commited in CVS.
 160         </ul>
 161
 162 **** TODO
 163         <ul>
 164                 * Unmanaged versions of hash algorithms (SHA1 and MD5).
 165                 * Unmanaged versions of symmetric encryption algorithms
 166                   (like DES, TripleDES, RC2 and others present in CryptoAPI).
 167                 * Unmanaged versions of asymmetric algorithms (like DSA and
 168                   RSA) which persist their keypair into the specified CSP.
 169         </ul>
 170
 171 <hr>
 172 ** Assembly: Microsoft.Web.Services
 173
 174         Microsoft Web Service Enhancement (WSE), known as Web Service
 175         Development Kit (WSDK) in it's beta days, is an add-on the .NET
 176         framework that implements WS-Security (and other WS-* specifications).
 177         It also includes improved support for XML Signature (replacing and/or
 178         extending <code>System.Security.Cryptography.Xml</code>) and X509
 179         certificates.
 180
 181         Note: WSE is distributed as an add-on because the WS-Security
 182         specification isn't yet completed by OASIS.
 183
 184         <b>There are some licensing issues to consider before stating to
 185         implement WS-Security. All contributors must sign an agreement with
 186         Microsoft before commiting anything related to WS-Security into CVS.
 187         </b>
 188
 189 *** Namespace: Microsoft.Web.Services.Security
 190
 191 **** Status
 192         <ul>
 193                 * Nothing (yet) commited in CVS.
 194         </ul>
 195
 196 *** Namespace: Microsoft.Web.Services.Security.X509
 197
 198 **** Status
 199         <ul>
 200                 * Nothing (yet) commited in CVS.
 201         </ul>
 202
 203 **** TODO
 204         <ul>
 205                 * We need to define certificate stores (for both users and
 206                   machines). These sames stores must be linked with asymmetric
 207                   keypairs. This could also be used to store the SPC roots.
 208         </ul>
 209
 210 <hr>
 211 ** Other stuff
 212
 213         There are other, not so visible, uses of cryptography both inside and
 214         outside the class library - such as:
 215
 216         <ul>
 217                 * SSL/TLS for secure communication (investigation under way).
 218
 219                 * Assembly signing (and verification) using StrongNames.
 220
 221                 * Assembly signing (and verification) using Authenticode(tm).
 222         </ul>
 223
 224
 225 *** Tools
 226
 227         There are many tools in the .NET framework that indirectly interacts
 228         with some cryptographic classes. Mono will eventually need these tools.
 229
 230 **** Status
 231
 232         The following tools are complete:
 233         <ul>
 234                 * <code>secutil</code> is a tool to extract certificates and
 235                   strongnames from assemblies in a format that can be easily
 236                   re-used in source code (C# or VB.NET syntax).
 237
 238                 * <code>cert2spc</code> is a tool to transform multiple X.509
 239                    certificates (a chain) into a Software Publisher Certificate
 240                   (SPC) - which is a long name for a simple PKCS#7 file.
 241         </ul>
 242
 243 **** TODO
 244         The following tools are still missing or incomplete:
 245         <ul>
 246                 * <code>monosn</code> is a clone of the <code>sn</code> to manage
 247                   strongnames. This tools is part of the runtime (not the class
 248                   library) and as such is written in C.
 249
 250                 * <code>signcode</code> and <code>chktrust</code> for signing
 251                   and validating  Authenticode(tm) signatures on assemblies.
 252
 253                 * <code>makecert</code> to create X.509 test certificates that
 254                   can be used (once transformed in SPC) to sign assemblies.
 255
 256                 * Other tools like a, GUI-based, certificate manager...
 257         </ul>
 258
 259         Note that many of the tools requires the class library and/or the
 260         runtime to be ready for them.
 261
 262 <hr>
 263 ** How to Help
 264
 265         Complete any of the TODO (and feel good about it ;-).
 266
 267         Add missing unit tests to classes or methods.
 268
 269         Write some documentation on the cryptographic classes for MonkeyGuide
 270         (as I'm not a good writer - but you must be a good reader if you got to
 271         this part).
 272
 273         Optimization can also be done on algorithms as crypto is never fast
 274         enough. Just be sure to test every optimization (using the unit test)
 275         carefully - it's so fast to break an algorithm ;-).
 276
 277         Contact Sebastien Pouliot (<a href="mailto:spouliot@videotron.ca">home</a>
 278         , <a href="mailto:spouliot@motus.com">work</a>) if you need additional
 279         informations about the status of the cryptographic classes.
 280