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