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 external
  18                   tools.
  19
  20                 * MACTripleDES is compatible with the implementation shipped in
  21                   framework 1.0. Version 1.1 gives different results when the
  22                   MACed data is a multiple of BlockSize (8 bytes).
  23         </ul>
  24
  25 **** TODO
  26         <ul>
  27                 * The current implementation of <code>CryptoStream</code> is
  28                   very limited and contain known bugs (<a
  29                   href="http://bugzilla.ximian.com/show_bug.cgi?id=40689">
  30                   40689</a>). The class need to be re-designed.
  31
  32                 * RNGCryptoServiceProvider is currently only working on Linux.
  33                   The current implementation reside in Mono's runtime and use
  34                   the <code>/dev/[u]random</code> device (which do not exists
  35                   under Windows). A Windows specific alternative is available
  36                   using the Mono.Security.Win32 assembly.
  37
  38                 * Keypair persistance for RSA and DSA. This persistance must
  39                   somehow be linked with X509 certificate stores (in planning).
  40
  41                 * <code>PasswordDeriveBytes.CryptDeriveKey</code> is included
  42                   in MS BCL to provide compatibility with existing Windows
  43                   applications. The main problem is that the key derivation
  44                   algorithm can be different for every CSP (Crypto Service
  45                   Provider). However for compatibility we should provide an
  46                   implementation compatible with the MS CSP (most likely used).
  47         </ul>
  48
  49 **** Notes
  50         <ul>
  51                 * All cryptographic algorithms are entirely managed, including
  52                   classes named <code>*CryptoServiceProvider</code>, with the
  53                   exception of <code>RNGCryptoServiceProvider</code> (which
  54                   implementation resides in the runtime).
  55
  56                 * There is a bug in the <code>PKCS1MaskGenerationMethod</code>
  57                   class (in both framework 1.0 and 1.1). This means our
  58                   implementation isn't compatible with MS (but is compatible with
  59                   PKCS#1 v.2.1). However we get OAEP padding for every platform!
  60
  61                 * Look at assembly Mono.Security.Win32 if you require more
  62                   compatiblity with the Microsoft implementation (like accessing
  63                   a particuliar keypair container inside a specific CSP).
  64         </ul>
  65
  66
  67 *** Namespace: <b>System.Security.Cryptography.X509Certificates</b>
  68
  69 **** Status
  70         <ul>
  71                 * X.509 certificates are parsed using 100% managed code
  72                   (using the Mono.Security.ASN1 class).
  73
  74                 * Software Publisher Certificates (SPC) used by Authenticode
  75                   (tm) to sign assemblies are supported (extraction from PE
  76                   files) but <b>not yet</b> validated.
  77
  78                 * Unit tests are generated from a set of existing certificates
  79                   (about a dozen) each having different properties. Another
  80                   set of certificates (more than 700) are used for a more
  81                   complete test (but isn't part of the standard test suite for
  82                   size and time consideration, i.e. a 7.5Mb C# source file).
  83         </ul>
  84
  85 **** TODO
  86         <ul>
  87                 * Authenticode(tm) support is incomplete. We can extract the
  88                   certificates from PE files but cannot validate the signature
  89                   nor the certificate chain (and we're still missing some trust
  90                   anchors). See Tools section for more information.
  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                 * The class Mono.Security.X509.X509Certificate (in Mono.Security
 108                   assembly) is becoming a much better alternative - and will
 109                   continue to evolve to support the security tools.
 110
 111                 * Microsoft implementation of <code>X509Certificate</code> is
 112                   done by using CryptoAPI (unmanaged code). From the exceptions
 113                   thrown Authenticode(tm) support is done via COM.
 114         </ul>
 115
 116 <hr>
 117 ** Assembly: System.Security
 118
 119 *** Namespace: <b>System.Security.Cryptography.Xml</b>
 120
 121         This namespace implements the <a href="http://www.w3.org/TR/xmldsig-core/">
 122         XML Digital Signature</a> specification from
 123         <a href="http://www.w3.org/">W3C</a>.
 124
 125 **** Status
 126         <ul>
 127                 * All classes are present but some (most Transforms) are only
 128                   stubbed.
 129
 130                 * Most classes have their unit tests.
 131         </ul>
 132
 133 **** TODO
 134         <ul>
 135                 * All the transforms needs to be done. But this requires far
 136                   more XML knowledge than crypto. Note: Most tests runs because
 137                   the feeded XML is pre-c14n (by hand in the code) before
 138                   signing (not because the transforms works). In the short
 139                   term <code>libxml2</code> could be used to provide C14N, but
 140                   in the long term a fully managed class would be much better.
 141         </ul>
 142
 143 <hr>
 144 ** Assembly: Mono.Security
 145
 146         <b>Rational: </b>
 147         This assembly provides the missing pieces to .NET security. On Windows
 148         CryptoAPI is often used to provide much needed functionalities (like
 149         some cryptographic algorithms, code signing, X.509 certificates). Mono,
 150         for platform independance, implements these functionalities in 100%
 151         managed code.
 152
 153 *** Namespace: Mono.Security
 154         <ul>
 155                 * Structures (ASN1, PKCS7) and primitives (PKCS1).
 156         </ul>
 157 *** Namespace: Mono.Security.Authenticode
 158         <ul>
 159                 * Code signing and verification.
 160                 * Support for SPC (Software Publisher Certificate) files and
 161                   PVK (Private Key) files.
 162         </ul>
 163 *** Namespace: Mono.Security.Cryptography
 164         <ul>
 165                 * Additional algorithms: MD2, ARCFOUR (required for SSL)
 166                 * Convertion helpers
 167         </ul>
 168 *** Namespace: Mono.Security.X509
 169         <ul>
 170                 * X.509 structures (certificate, CRL...) building and decoding.
 171         </ul>
 172 *** Namespace: Mono.Security.X509.Extensions
 173         <ul>
 174                 * X.509 extensions (from public X.509 to private PKIX, Netsapce,
 175                   Microsoft, Entrust...).
 176         </ul>
 177
 178 **** Status
 179         <ul>
 180                 * Some part of the work has not yet been commited (still cleaning up).
 181
 182                 * A big part of this assembly is also included inside Mono's
 183                   corlib. The classes are duplicated in this assembly so the
 184                   functionalities can be used without a dependency on Mono's
 185                   corlib (which depends on Mono's runtime).
 186
 187                 * Unit test coverage isn't (yet) complete.
 188         </ul>
 189
 190 <hr>
 191 ** Assembly: Mono.Security.Win32
 192
 193         <b>Rational: </b>
 194         This assembly goal is to provide maximum compatibility with CryptoAPI
 195         to application running with Mono's runtime on the Windows operating
 196         system.
 197
 198         <b>This assembly should NEVER be used directly by any application</b>
 199         (e.g. referecing the assembly from a project).
 200         The classes should only be used by modifying the <code>machine.config
 201         </code> configuration file (and then only if this increased
 202         compatibility is required by an application).
 203
 204         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>
 205         for complete instructions.
 206
 207 *** Namespace: Mono.Security.Cryptography
 208
 209 **** Status
 210         <ul>
 211                 * A RNGCryptoServiceProvider built on top of CryptoAPI. This
 212                   allows Windows users to get around the limitation of the
 213                   runtime RNG (which requires <code>/dev/[u]random/</code>).
 214
 215                 * Wrapper classes for unmanaged versions of hash algorithms:
 216                   MD2, MD4, MD5 and SHA1 are supported. <b>note</b>: some
 217                   algorithms shouldn't be used in new design (MD4 is broken,
 218                   MD2 and MD5 aren't considered safe for some usage). They are
 219                   included to preserve interoperability with older applications
 220                   (e.g. some old, but still valid, X.509 certificates use MD2).
 221         </ul>
 222
 223 **** TODO
 224         <ul>
 225                 * Wrapper classes for unmanaged versions of symmetric
 226                   encryption algorithms (like DES, TripleDES, RC2 and others
 227                   present in default CSP).
 228
 229                 * Wrapper classes for unmanaged versions of asymmetric
 230                   algorithms (like DSA and RSA) which persist their keypair
 231                   into the specified CSP.
 232         </ul>
 233
 234 **** Ideas
 235         <ul>
 236                 * Similar assemblies (e.g. <code>Mono.Security.XXX</code>)
 237                   could be created for <a href="http://www.openssl.org">OpenSSL</a>,
 238                   <a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a>,
 239                   <a href="http://www.eskimo.com/~weidai/cryptlib.html">crypto++</a>,
 240                   <a href="http://www.cryptlib.orion.co.nz/">cryptlib</a> ... for
 241                   improved performance and/or HSM (Hardware Security Module) support
 242                   under Linux and/or Windows.
 243         </ul>
 244 <hr>
 245 ** Assembly: Microsoft.Web.Services
 246
 247         Microsoft Web Service Enhancement (WSE), known as Web Service
 248         Development Kit (WSDK) in it's beta days, is an add-on the .NET
 249         framework that implements WS-Security (and other WS-* specifications).
 250         It also includes improved support for XML Signature (replacing and/or
 251         extending <code>System.Security.Cryptography.Xml</code>) and X.509
 252         certificates classes.
 253
 254         Note: WSE is distributed as an add-on because some specifications,
 255         like WS-Security, aren't yet completed by
 256         <a href="http://www.oasis-open.org/committees/wss/">OASIS</a> or
 257         other committees.
 258
 259         <b>[*] There are some licensing issues to consider before starting to
 260         implement WS-Security. All contributors must sign an agreement with
 261         Microsoft before commiting anything related to WS-Security into CVS.
 262         </b>
 263
 264 *** Namespace: Microsoft.Web.Services.Security [*]
 265 *** Namespace: Microsoft.Web.Services.Timestamp [*]
 266
 267 **** Status
 268         <ul>
 269                 * Nothing (yet) commited in CVS <b>[*]</b>.
 270         </ul>
 271
 272 *** Namespace: Microsoft.Web.Services.Security.X509
 273
 274 **** Status
 275         <ul>
 276                 * Nothing (yet) commited in CVS. However the classes in this
 277                   namespace are outside WS-Security scope. So development, for
 278                   those classes, could be done without signing any agreements.
 279         </ul>
 280
 281 **** TODO
 282         <ul>
 283                 * We need to define certificate stores (for both users and
 284                   machines). These sames stores must be linked with asymmetric
 285                   keypairs. This could also be used to store the SPC roots.
 286         </ul>
 287
 288 <hr>
 289 ** Tools
 290
 291         There are many tools in the .NET framework that indirectly interacts
 292         with some cryptographic classes. Mono will eventually need these tools.
 293         Unless noted the tools should work on any CLR (tested with both Mono
 294         and Microsoft).
 295
 296 **** Status
 297
 298         The following tools are complete (mostly complete):
 299         <ul>
 300                 * <code>secutil</code> is a tool to extract certificates and
 301                   strongnames from assemblies in a format that can be easily
 302                   re-used in source code (C# or VB.NET syntax).
 303
 304                 * <code>cert2spc</code> is a tool to transform multiple X.509
 305                    certificates and CRLs into a Software Publisher Certificate
 306                   (SPC) file - which is a long name for a simple PKCS#7 file.
 307
 308                 * <code>makecert</code> to create X.509 test certificates that
 309                   can be used (once transformed in SPC) to sign assemblies.
 310         </ul>
 311
 312         Somewhat usable, somewhat incomplete:
 313         <ul>
 314                 * <code>sn</code> is a clone of the <code>sn</code> to manage
 315                   strongnames. Current version is limited to creating new keypairs
 316                   and converting values.
 317
 318                 * <code>monosn</code> is a clone of the <code>sn</code> to manage
 319                   strongnames. This tools is part of the runtime (not the class
 320                   library) and as such is written in C and won't run without Mono.
 321         </ul>
 322
 323
 324 **** TODO
 325         The following tools are still missing or largely incomplete:
 326         <ul>
 327
 328                 * <code>signcode</code> and <code>chktrust</code> (in progress)
 329                   for signing and validating Authenticode(tm) signatures on
 330                   assemblies (or any PE file).
 331
 332                 * Other tools like a, GUI-based, certificate manager...
 333         </ul>
 334
 335         Note that many of the tools requires the class library and/or the
 336         runtime to be ready for them. E.g. StrongName and Authenticode signatures
 337         tools are of limited use until supported by the runtime.
 338
 339 <hr>
 340 ** Other stuff
 341
 342         <ul>
 343                 * SSL/TLS for secure communication (a prototype is under way).
 344                   Some work is already visible in Mono.Security assembly (e.g.
 345                   RC4, RSAManaged ...).
 346         </ul>
 347
 348
 349 <hr>
 350 ** How to Help
 351
 352         <ul>
 353                 * Complete any of the TODO (and feel good about it ;-).
 354
 355                 * Analyse the current coverage of the unit tests on the
 356                   cryptographic classes and complete the unit tests.
 357
 358                 * Optimization can also be done on most algorithms as crypto
 359                   is never fast enough. Some have been done using the
 360                   Community Edition of BoundChecker (a free VisualStudio
 361                   addon) - recommanded! Just be sure to test every optimization
 362                   (using the unit test) carefully - it's so fast to break an
 363                   algorithm ;-).
 364
 365                 * Write some documentation on the cryptographic classes for
 366                   the <a href="http://go-mono.com/tutorial/html/en/index.html">Mono
 367                   Handbook</a> as I'm not a very good writer (at least in English).
 368         </ul>
 369
 370         Contact Sebastien Pouliot (<a href="mailto:spouliot@videotron.ca">home</a>
 371         , <a href="mailto:spouliot@motus.com">work</a>) if you need additional
 372         informations about the status of the cryptographic classes.
 373
 374 <hr>
 375 Last reviewed: June 11, 2003 (post mono 0.24)