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