X-Git-Url: https://wagner.pp.ru/gitweb/?a=blobdiff_plain;f=README.md;h=ee8356bb2df12c72eb9e20359c5626831388609f;hb=7b9c29e43612629052e0ec875fd9ecbb35b0b02d;hp=9abd63b5d14175d49d7c4e11c4e36fda71bcef6e;hpb=5e79220ede7efe3bf4703344c7963049a6e71545;p=oss%2Fctypescrypto.git diff --git a/README.md b/README.md index 9abd63b..ee8356b 100644 --- a/README.md +++ b/README.md @@ -7,49 +7,178 @@ This module is based on works from http://code.google.com/p/ctypescrypto/ -It is aimed to provide Python interface to OpenSSL libcrypto function +most recent version can be checked out from -Now supported: +https://github.com/vbwagner/ctypescrypto.git -bio.py - interfase to OpenSSL stream abstraction BIO. Now supports - memory BIOs this module intended to use for parsing/serializing - various ASN.1 based formats like private keys or certificates - Status: bare minimum functionality is implemented and covered by - rests +Rationale +--------- -oid.py - interface to OpenSSL ASN.1 Object Identifier databsase. - Allows to convert numeric identifier (NIDs) returned by various - OpenSSL function to readable names or dotted-decimal OIDs and back - Status: Fully implemented and covered by tests. +Why have yet another crypto extension for Python? There is pyopenssl, +m2crypto, hashlib in the standard library and many more. -engine.py - interface to loadable modules with alternate implementations - of cryptoalgorithms. - Status: Bare minumum, neccessary to use GOST algorithms is - implemented. +But most of these extension implement interfaces to particular set of +cryptoalgorthms. This extension takes an another approach — it uses +algorithm-agnostic EVP layer whenever possible, and so support any +algorithms which are supported by underlying library, even this +algorithms are implemented in the loadable modules (engines). Algorithms +which you've just added to library, should be supported too. -rand.py - interface to pseudo-random number generator. - Status: Implemented. Tests now only ensure that no segfault occurs - if arugments are passed correctly +Also, this extension takes some care of correctly converting textual +information from ASN.1 structures into unicode. -digests.py - Interface to EVP\_Digest\* family of functions. - Really does almost same as hashlib, which even is able to take - advantage of loaded engines if compiled against dynamic libcrypto - Status: fully implemented and covered by tests -ciphers.py - Interface to EVP\_Cipher family of function. - Status: Needs complete rewriting and test coverage. Idea to keep - cleartext in python variable until entire text would be passed to - update is EVIL. -pkey.py - Low-level private key operations (like pkey, genpkey and p - keyutl command line ops), all via algorithm-agnostic EVP interface. - Status: Designed and mostly implemented but not yet covered by tests +Digest calculation +------------------ -exception.py OpenSSL error stack to python exception conversion - Implemented. +Module **ctypescrypto.digest** contain **new()** function which produces +objects simular to python **hashlib** module objects. -x509 X509 certificates. Support parsing of X509 certificates, - verification and extracting of field values. Possible extnesion - - support creattion of PKCS10 certificate requests. - Status: Interface designed and partially implemented +On the systems where hashlib is linked with libcrypto dynamically, +hashlib even able to make use of digest types, provided by loadable +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 +----------------- + +Module *ctypescrypto.cipher* contain *new()* function which provides +way to create cipher objects. Cipher padding can be configure later. +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 +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. + +It is possible to extract public key from the certificate as PKey +object (see below). + +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 +certificate (and can be constructed from string, contained PEM +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). + +There is no support for creating and signing certificates, i.e. to +perform Certificate Authority functions. This library for now focuses on +cryptography user functionality. + +Certificate has properties corresponding to its subject and issuer +names, public key (of course it is PKey object described above) and +serial number. Subject and issuer names can be indexed by OIDs or by +position of field. Unicode in the names is supported. + +Support for visualising certificate extensions is minimal for now. +Extension object can be converted into string, extension Oid can be +retrieved and critical flag is checked. + +**StackOfX509** implements collection of certificates, necessary for +some operations with CMS and certificate verification. + +CMS documents +------------- + +There is basic factory function **CMS()**, which parses PEM or der +representation of cryptographic message and generates appropriate +object. There are **SignedData**, **EnvelopedData** and +**EncryptedData** classes. 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. + +Unfortunately, **SignedAndEnvelopedData** seems to be unsupported in +libcrypto as of version 1.0.1 of OpenSSL. + +PBKDF2 +------ + +Provides interface to password based key derivation 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 contains internal object identifiers (OID) database. Each OID +have apart from dotted-decimal representation long name, short name and +numeric identifier. 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 +----------- + +OpenSSL contain BIO (basic input-output) abstraction. And all object +serialization/deserialization use this library. Also human-readable +representation of ASN.1 structures use this library extensively. So, +we've to develop python object which allow to read from python string +via BIO abstraction or write to buffer, which can be returned as python +string or unicode object. + +Exceptions +---------- + +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 + +Engine support +-------------- + +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 algorithms, provided by **gost** engine. + +Test Suite +---------- + +Tests can be run using + + python setup.py test + +Test suite is fairly incomplete. Contributions are welcome. + +Possible future enhancements +---------------------------- + +1. Creation and signing of the certificate requests (PKCS#10) +2. Parsing and analyzing CRLs +3. OCSP ([RFC 6960](http://tools.ietf.org/html/rfc6960))request creation and response parsing +4. Timestamping ([RFC 3161](http://tools.ietf.org/html/rfc3161)) +support. +6. MAC support. Few people know that there is more MACs than just HMAC, +and even fewer, that OpenSSL supports them. + + vim: spelllang=en tw=72