README.md

   1 ctypescrypto
   2 ============
   3
   4 Python interface to some openssl function based on ctypes module
   5
   6 This module is based on works from
   7
   8 http://code.google.com/p/ctypescrypto/
   9
  10 most recent version can be checked out from
  11
  12 https://github.com/vbwagner/ctypescrypto.git
  13
  14 It is aimed to provide Python interface to OpenSSL libcrypto functions.
  15 All the objects in this library are just wrappers around some OpenSSL
  16 data structures and groups of functions.
  17
  18
  19
  20 Digest calculation
  21 ------------------
  22
  23 Module **ctypescrypto.digest** contain **new()** function which produces
  24 objects simular to python **hashlib** module objects.
  25
  26 On the systems where hashlib is linked with libcrypto dynamically,
  27 hashlib even able to make use of digest types, provided by loadable
  28 engines.
  29
  30 This module would utilize same copy of libcrypto library as other
  31 ctypescrypto modules, so it would work with engine-provided digests.
  32
  33 Additionally there is **DigestType** class which may be needed to
  34 construct CMS SignedData objects or add signatures to them.
  35
  36 Symmetric ciphers
  37 -----------------
  38
  39 Module *ctypescrypto.cipher* contain *new()* function which provides
  40 way to create cipher objects. Cipher padding can be configure later.
  41 This object provides methods *update* and *finish* which allows to
  42 encrypt/decrypt data. All ciphers, supported by your version of OpenSSL
  43 and its loadable engines are supported.
  44
  45 Additionally the **CipherType** class instances may be used directly to
  46 pass to other functions such as CMS EnvelopedData or EncryptedData
  47 **create**
  48
  49 Public key operations
  50 ---------------------
  51
  52 Module **ctypescrypto.pkey** provides **PKey** object, which represents
  53 public/private key pair or just public key. With this object you can
  54 sign data, derive shared key and verify signatures.
  55
  56 This is quite low-level object, which can be used to implement some
  57 non-standard protocols and operations.
  58
  59 Additional module **ctypescrypto.ec** allows to create **PKey** objects
  60 with elliptic curve keys from just raw secret key as byte buffer or
  61 python big integer.
  62
  63 X509 certificates
  64 -----------------
  65
  66 Module **ctypescrypto.x509** contains objects **X509** which represents
  67 certificate (and can be constructed from string, contained PEM
  68 or DER certificate) and object **X509Store** which is a store of trusted
  69 CA certificates which can be used to high-level signature verifications
  70 (i.e. in PKCS7/CMS messages).
  71
  72 Certificate has properties corresponding to its subject and issuer
  73 names, public key (of course it is PKey object described above) and
  74 serial number. Subject and issuer names can be indexed by OIDs or by
  75 position of field. Unicode in the names is supported.
  76
  77 There is no support for certificate validity time yet.
  78
  79 **StackOfX509** implements collection of certificates, neccessary for
  80 some operations with CMS and certificate verification.
  81
  82 CMS documents
  83 -------------
  84
  85 There is basic constructor function **CMS()**, which parses PEM or der
  86 representation of cryptographic message and generates appropriate
  87 object. There are **SignedData**, **EnvelopedData** and
  88 **EncryptedData** clases. Each class has static method **create**
  89 allowing to create this subtype of message from raw data and appropriate
  90 keys and certificates.
  91
  92 **SignedData** has **verify()** method. **EnvelopedData** and
  93 **EncryptedData** - **decrypt** method.
  94
  95 Unfortunatly, **SignedAndEnvelopedData** seems to be unsupported in
  96 libcrypto as of version 1.0.1 of OpenSSL.
  97
  98 PBKDF2
  99 ------
 100
 101 Provices interface to password based keyderivation function
 102 Interface slightly differs from the **hashlib.pbkdf2_hmac** function,
 103 which have appeared in Python 2.7.8 but functionality is just same,
 104 although OpenSSL implementation might be faster.
 105
 106
 107
 108
 109 OID database
 110 ------------
 111
 112 OpenSSL conteins internal object identifiers (OID) database. Each OID
 113 have apart from dotted-decimal representation long name, short name and
 114 numeric identifer. Module **ctypescrypto.oid** provides interface to the
 115 database. **Oid** objects store numeric identifier internally and can
 116 return both long and short name and dotted-decimal representation.
 117
 118 BIO library
 119 -----------
 120
 121 OpenSSL contain BIO (basic input-output) abstraction. And all object
 122 serialization/deserialization use this library. Also human-readble
 123 representation of  ASN.1 structures use this library extensively. So,
 124 we've to develop python object which allow to read from python string
 125 via BIO abstraction or write to buffer, which can be returned as python
 126 string or unicode object.
 127
 128 Exceptions
 129 ----------
 130
 131 Exceptions, used in the **ctypescrypto** to report problems are tied
 132 closely with OpenSSL error-reporting functions, so if such an exception
 133 occurs, as much as possibly information from inside libcrypto would be
 134 available in the Python
 135
 136 Engine support
 137 --------------
 138
 139 There is just one function **ctypescrypt.engine.set_default**. which loads
 140 specified engine by id and makes it default for all algorithms,
 141 supported by it. It is enough for me to use Russian national
 142 cryptographic algoritms, provided by **gost** engine.
 143
 144 Test Suite
 145 ----------
 146
 147 Test suite is fairly incomplete. Contributions are welcome.