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