From: Victor Wagner Date: Mon, 27 Oct 2014 13:35:37 +0000 (+0300) Subject: improved readme X-Git-Url: http://wagner.pp.ru/gitweb/?a=commitdiff_plain;h=9c15fc86e48a5e4be1b6e8488ab845d0ad8ba656;p=oss%2Fctypescrypto.git improved readme --- diff --git a/README.md b/README.md index 27991db..34835b2 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,8 @@ data structures and groups of functions. Digest calculation ------------------ -Module *ctypescrypto.digest* contain *new()* function which produces -objects simular to python *hashlib* module objects. +Module **ctypescrypto.digest** contain **new()** function which produces +objects simular to python **hashlib** module objects. On the systems where hashlib is linked with libcrypto dynamically, hashlib even able to make use of digest types, provided by loadable @@ -30,6 +30,9 @@ engines. This module would utilize same copy of libcrypto library as other ctypescrypto modules, so it would work with engine-provided digests. +Additionally there is **DigestType** class which may be needed to +construct CMS SignedData objects or add signatures to them. + Symmetric ciphers ----------------- @@ -39,22 +42,30 @@ This object provides methods *update* and *finish* which allows to encrypt/decrypt data. All ciphers, supported by your version of OpenSSL and its loadable engines are supported. +Additionally the **CipherType** class instances may be used directly to +pass to other functions such as CMS EnvelopedData or EncryptedData +**create** + Public key operations --------------------- -Module *ctypescrypto.pkey* provides *PKey* object, which represents +Module **ctypescrypto.pkey** provides **PKey** object, which represents public/private key pair or just public key. With this object you can sign data, derive shared key and verify signatures. This is quite low-level object, which can be used to implement some non-standard protocols and operations. +Additional module **ctypescrypto.ec** allows to create **PKey** objects +with elliptic curve keys from just raw secret key as byte buffer or +python big integer. + X509 certificates ----------------- -Module *ctypescrypto.x509* contains objects *X509* which represents +Module **ctypescrypto.x509** contains objects **X509** which represents certificate (and can be constructed from string, contained PEM -or DER certificate) and object *X509Store* which is a store of trusted +or DER certificate) and object **X509Store** which is a store of trusted CA certificates which can be used to high-level signature verifications (i.e. in PKCS7/CMS messages). @@ -65,13 +76,43 @@ position of field. Unicode in the names is supported. There is no support for certificate validity time yet. +**StackOfX509** implements collection of certificates, neccessary for +some operations with CMS and certificate verification. + +CMS documents +------------- + +There is basic constructor function **CMS()**, which parses PEM or der +representation of cryptographic message and generates appropriate +object. There are **SignedData**, **EnvelopedData** and +**EncryptedData** clases. Each class has static method **create** +allowing to create this subtype of message from raw data and appropriate +keys and certificates. + +**SignedData** has **verify()** method. **EnvelopedData** and +**EncryptedData** - **decrypt** method. + +Unfortunatly, **SignedAndEnvelopedData** seems to be unsupported in +libcrypto as of version 1.0.1 of OpenSSL. + +PBKDF2 +------ + +Provices interface to password based keyderivation function +Interface slightly differs from the **hashlib.pbkdf2_hmac** function, +which have appeared in Python 2.7.8 but functionality is just same, +although OpenSSL implementation might be faster. + + + + OID database ------------ OpenSSL conteins internal object identifiers (OID) database. Each OID have apart from dotted-decimal representation long name, short name and -numeric identifer. Module *ctypescrypto.oid* provides interface to the -database. *Oid* objects store numeric identifier internally and can +numeric identifer. Module **ctypescrypto.oid** provides interface to the +database. **Oid** objects store numeric identifier internally and can return both long and short name and dotted-decimal representation. BIO library @@ -87,7 +128,7 @@ string or unicode object. Exceptions ---------- -Exceptions, used in the *ctypescrypto* to report problems are tied +Exceptions, used in the **ctypescrypto** to report problems are tied closely with OpenSSL error-reporting functions, so if such an exception occurs, as much as possibly information from inside libcrypto would be available in the Python @@ -95,8 +136,8 @@ available in the Python Engine support -------------- -There is just one function *ctypescrypt.engine.set_default*. which loads +There is just one function **ctypescrypt.engine.set_default**. which loads specified engine by id and makes it default for all algorithms, supported by it. It is enough for me to use Russian national -cryptographic algoritms, provided by *gost* engine. +cryptographic algoritms, provided by **gost** engine.