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                 * 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.*
 142         <ul>
 143                 * Tls: An 100% managed TLS implementation from Carlos Guzman
 144                   Alvarez.
 145                 * Ntlm: NTLM authentication (used for HTTP and SQL Server).
 146         </ul>
 147 *** Namespace: Mono.Security.X509
 148         <ul>
 149                 * X.509 structures (certificate, CRL...) building and decoding.
 150                 * PKCS#12 decoding.
 151         </ul>
 152 *** Namespace: Mono.Security.X509.Extensions
 153         <ul>
 154                 * X.509 extensions (from public X.509 to private PKIX, Netsapce,
 155                   Microsoft, Entrust...).
 156         </ul>
 157
 158 **** Status
 159         <ul>
 160                 * A big part of this assembly is also included inside Mono's
 161                   corlib. The classes are duplicated in this assembly so the
 162                   functionalities can be used without a dependency on Mono's
 163                   corlib (which depends on Mono's runtime).
 164
 165                 * Unit test coverage isn't (yet) complete.
 166         </ul>
 167
 168 <hr>
 169 ** Assembly: Mono.Security.Win32
 170
 171         <b>Rational: </b>
 172         This assembly goal is to provide maximum compatibility with CryptoAPI
 173         to application running with Mono's runtime on the Windows operating
 174         system.
 175
 176         <b>This assembly should NEVER be used directly by any application</b>
 177         (e.g. referecing the assembly from a project).
 178         The classes should only be used by modifying the <code>machine.config
 179         </code> configuration file (and then only if this increased
 180         compatibility is required by an application).
 181
 182         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>
 183         for complete instructions.
 184
 185 *** Namespace: Mono.Security.Cryptography
 186
 187 **** Status
 188         <ul>
 189                 * A RNGCryptoServiceProvider built on top of CryptoAPI. This
 190                   allows Windows users to get around the limitation of the
 191                   runtime RNG (which requires <code>/dev/[u]random/</code>).
 192
 193                 * Wrapper classes for unmanaged versions of hash algorithms:
 194                   MD2, MD4, MD5 and SHA1 are supported. <b>note</b>: some
 195                   algorithms shouldn't be used in new design (MD4 is broken,
 196                   MD2 and MD5 aren't considered safe for some usage). They are
 197                   included to preserve interoperability with older applications
 198                   (e.g. some old, but still valid, X.509 certificates use MD2,
 199                   MD4 is required for NTLM authentication ...).
 200         </ul>
 201
 202 **** TODO
 203         <ul>
 204                 * Wrapper classes for unmanaged versions of symmetric
 205                   encryption algorithms (like DES, TripleDES, RC2 and others
 206                   present in default CSP).
 207
 208                 * Wrapper classes for unmanaged versions of asymmetric
 209                   algorithms (like DSA and RSA) which persist their keypair
 210                   into the specified CSP.
 211         </ul>
 212
 213 **** Ideas
 214         <ul>
 215                 * Similar assemblies (e.g. <code>Mono.Security.XXX</code>)
 216                   could be created for <a href="http://www.openssl.org">OpenSSL</a>,
 217                   <a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a>,
 218                   <a href="http://www.eskimo.com/~weidai/cryptlib.html">crypto++</a>,
 219                   <a href="http://www.cryptlib.orion.co.nz/">cryptlib</a> ... for
 220                   improved performance and/or HSM (Hardware Security Module) support
 221                   under Linux and/or Windows.
 222         </ul>
 223 <hr>
 224 ** Assembly: Microsoft.Web.Services
 225
 226         Microsoft Web Service Enhancement (WSE), known as Web Service
 227         Development Kit (WSDK) in it's beta days, is an add-on the .NET
 228         framework that implements WS-Security (and other WS-* specifications).
 229         It also includes improved support for XML Signature (replacing and/or
 230         extending <code>System.Security.Cryptography.Xml</code>) and X.509
 231         certificates classes.
 232
 233         Note: WSE is distributed as an add-on because some specifications,
 234         like WS-Security, aren't yet completed by
 235         <a href="http://www.oasis-open.org/committees/wss/">OASIS</a> or
 236         other committees.
 237
 238 *** Namespace: Microsoft.Web.Services.Security
 239
 240 **** Status
 241         <ul>
 242                 * Most WSE 1.0 classes are implemented.
 243         </ul>
 244
 245 **** TODO
 246         <ul>
 247                 * Some classes from System.Security assembly need to be
 248                 duplicated (and somewhat fixed) in WSE for XMLDSIG.
 249
 250                 * There are still missing classes and <b>many</b> missing
 251                 unit tests.
 252         </ul>
 253
 254
 255 *** Namespace: Microsoft.Web.Services.Timestamp
 256
 257 **** Status
 258         <ul>
 259                 * This seems complete for WSE 1.0 but some new classes were
 260                 introduced in WSE 2.0.
 261         </ul>
 262
 263 *** Namespace: Microsoft.Web.Services.Security.X509
 264
 265 **** Status
 266         <ul>
 267                 * X509Certificate support is complete for both WSE 1.0 and 2.0.
 268         </ul>
 269
 270 **** TODO
 271         <ul>
 272                 * We need to define certificate stores (for both users and
 273                   machines). These sames stores must be linked with asymmetric
 274                   keypairs. This could also be used to store the SPC roots.
 275         </ul>
 276
 277 *** Notes
 278         <ul>
 279                 * Microsoft has <a href="http://microsoft.com/downloads/details.aspx?FamilyId=21FB9B9A-C5F6-4C95-87B7-FC7AB49B3EDD&displaylang=en">released</a>
 280                 a technical preview of WSE 2. <b>Note that WSDK (the technical
 281                 preview of WSE) had A LOT of changes before it's initial
 282                 release!</b>
 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 (or 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
 309                 * <code>sn</code> is a clone of the <code>sn</code> to manage
 310                   strongnames. Current version can create, convert, sign and
 311                   verify strongnames signatures. Some configuration options
 312                   are still missing.
 313
 314                 * <code>signcode</code> and <code>chktrust</code> for signing
 315                   and validating Authenticode(tm) signatures on assemblies (or
 316                   any PE file) are now working (signature and timestamps) but
 317                   some options aren't yet supported.
 318         </ul>
 319
 320         Somewhat usable, somewhat incomplete:
 321         <ul>
 322                 * <code>certview</code> is a certificate viewer for
 323                   <code>System.Windows.Forms</code> (right now only working on
 324                   Windows), while <code>gcertview</code> is the same viewer
 325                   implemented for GTK# (working on both Windows and Linux).
 326
 327                 * <code>monosn</code> is a clone of the <code>sn</code> to manage
 328                   strongnames. This tools is part of the runtime (not the class
 329                   library) and as such is written in C and won't run without Mono.
 330         </ul>
 331
 332
 333 **** TODO
 334         The following tools are still missing or largely incomplete:
 335         <ul>
 336                 * Other tools like a, GUI-based, certificate manager...
 337         </ul>
 338
 339         Note that many of the tools requires the class library and/or the
 340         runtime to be ready for them. E.g. StrongName and Authenticode signatures
 341         tools are of limited use until supported by the runtime.
 342
 343 <hr>
 344 ** References
 345
 346         <ul>
 347                 * RSA Laboratories' <a href="http://www.rsasecurity.com/rsalabs/faq/index.html">
 348                 Frequently Asked Questions</a> About Today's Cryptography, Version 4.1
 349
 350                 * Public-Key Cryptography Standards (<a href="http://www.rsasecurity.com/rsalabs/pkcs/index.html">
 351                 PKCS</a>)
 352
 353                 * National Institute of Standards and Technology - Federal
 354                 Information Processing Standards <a href="http://csrc.nist.gov/publications/fips/index.html">
 355                 NIST FIPS</a>
 356         </ul>
 357
 358 <hr>
 359 ** How to Help
 360
 361         <ul>
 362                 * Complete any of the TODO (and feel good about it ;-).
 363
 364                 * Analyse the current coverage of the unit tests on the
 365                   cryptographic classes and complete the unit tests. <b><code>
 366                   monocov</code> does a great job at this! Now we just need to
 367                   complete the missing unit tests.</b>
 368
 369                 * Optimization can also be done on most algorithms as crypto
 370                   is never fast enough. Some have been done using the
 371                   Community Edition of BoundChecker (a free VisualStudio
 372                   addon) - recommanded! Just be sure to test every optimization
 373                   (using the unit tests) carefully - it's so fast to break an
 374                   algorithm ;-).
 375
 376                 * Write some documentation on the cryptographic classes for
 377                   <b>monodoc</b>.
 378         </ul>
 379 <hr>
 380 Last reviewed: February 2, 2004 (mono 0.30)