Update README.md

Author: safe-webdrop

README.md

@@ -9,4 +9,78 @@
  coded in Python3.
 
  All cryptlib tools can replace complex OpenSSL code by using Cryptlib and are designed
- to interoperate with programs that are widely used and established like gpg2 and openssl.
+ to interoperate with programs that are widely used and established like gpg2, openssl
+ and Email clients like Thunderbird or Outlook.
+
+ ## claes - File Encryption Using Pure AES
+ 
+If you use only one of these programs, either openssl or gpg2 for file encryption, 
+the resulting encrypted cipher texts are stored in a format that cannot be interchanged with the other. 
+GnuPG aims to implement the OpenPGP standard with
+various degrees of success in a format that consists of packets described in 
+<a href="https://datatracker.ietf.org/doc/html/rfc4880">RFC-4880</a>, 
+while OpenSSL (accessed via the command line tools) can produce cipher text in CMS-format or in 
+<a href="https://www.openssl.org/docs/man1.1.1/man1/enc.html">its own proprietary format</a>. 
+As it is seen so often, both worlds (although using AES) cannot talk to each other easily.
+
+But the tool <a href="https://senderek.ie/cryptlib/tools/claes"><b>clAES</b></a> is made to talk to both,
+as it can produce OpenPGP messages (as the default) and additionally
+switch to CMS or OpenSSL message formats if need be. 
+In any case, the input data is encrypted with a passphrase that the user provides to the program
+and AES will always be used as the only encryption method.
+
+```
+claes [-debug] [-decrypt] [-cms | -openssl [-128]] [FILE | -]
+```
+## clkeys - Public and Private Key Management
+
+One of the main features of <a href="https://senderek.ie/cryptlib/tools/clkeys"><b>clkeys</b></a> is to
+generate RSA and DSA asymmetric keys and to store these keys safely in a file in the PKCS#15 token format.
+
+If you ever have imported RSA keys for use in an email client like thunderbird, you'll probably
+know that this software expects both the private and the public key together in a single file
+in PKCS#12 format. This bad habit has become common-sense, despite the fact that the PKCS#12
+format is a <a href="https://www.usenix.org/legacy/event/sec02/full_papers/gutmann/gutmann.pdf">
+weak format and a bad idea to store a private key</a>.
+
+Cryptlib, on the other hand, will always store private keys in the PKCS#15 format, a format that is
+used with cryptographic tokens like Smart Cards, where the keys never leave the device.
+Because one of the principal design features of Cryptlib is that it never exposes private keys to outside
+access, Cryptlib chooses to use the PKCS#15 format with no exception. 
+So do not wait (or even wish) for a conversion tool that makes Cryptlib-generated keys available in
+a PKCS#12 format file. It makes no sense to deliberately reduce the security of your private keys 
+just because some email client wants them in a weak format only.
+
+In addition to generating RSA and DSA public key pairs, clkeys can generate certificate signing requests
+for a public key and also import self-signed certificates or certificates signed by an external CA.
+All files that clkeys will create (cert requests and certificates) can be used by other software,
+just the private key remains secure in a PKCS#15 format file, that will be used with Cryptlib exclusively.
+
+```
+clkeys generate [-DSA] KeysetName [-SIZE RSABits] [-CN YourName]
+clkeys request KeysetName [-CN YourName]
+clkeys import KeysetName CertFile
+clkeys casign CA-KeysetName RequestFile
+```
+
+## clsmime - S/MIME public key encryption tool
+
+<a href="https://senderek.ie/cryptlib/tools/clsmime"><b>clsmime</b></a> is a tool that uses public and 
+private RSA keys made with clkeys to generate encrypted SMIME messages and signed SMIME messages. 
+
+It can also exchange SMIME encrypted and signed messages with established EMAIL clients like Thunderbird, Evolution or Outlook. 
+<a href="https://senderek.ie/cryptlib/tools/clsmime"><b>clsmime</b></a> handles SMIME messages
+that are produced by OpenSSL as well. While <b>clsmime</b> will use private keys generated with clkeys in PKCS#15
+format for decryption and signing, it can use certificates generated by OpenSSL for encryption and
+verification as well.
+
+```
+clsmime [OPTIONS] encrypt messagefile certificate
+clsmime [OPTIONS] decrypt encrypted_message KeysetName
+clsmime [OPTIONS] sign messagefile KeysetName
+clsmime [OPTIONS] verify signed_message [CArootCertificate]
+```
+## More to come!
+
+These are only three examples of how you can use Cryptlib to build reliable tools for users.
+And there are many more tools to come in the near future.