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 Rationale
  15 ---------
  16
  17 Why have yet another crypto extension for Python? There is pyopenssl,
  18 m2crypto, hashlib in the standard library and many more.
  19
  20 But most of these extension implement interfaces to particular set of
  21 cryptoalgorthms. This extension takes an another approach — it uses
  22 algorithm-agnostic EVP layer whenever possible, and so support any
  23 algorithms which are supported by underlying library, even this
  24 algorithms are implemented in the loadable modules (engines). Algorithms
  25 which you've just added to library, should be supported too.
  26
  27 Also, this extension takes some care of correctly converting textual
  28 information from ASN.1 structures into unicode.
  29
  30
  31
  32 Digest calculation
  33 ------------------
  34
  35 Module **ctypescrypto.digest** contain **new()** function which produces
  36 objects simular to python **hashlib** module objects.
  37
  38 On the systems where hashlib is linked with libcrypto dynamically,
  39 hashlib even able to make use of digest types, provided by loadable
  40 engines.
  41
  42 This module would utilize same copy of libcrypto library as other
  43 ctypescrypto modules, so it would work with engine-provided digests.
  44
  45 Additionally there is **DigestType** class which may be needed to
  46 construct CMS SignedData objects or add signatures to them.
  47
  48 Symmetric ciphers
  49 -----------------
  50
  51 Module *ctypescrypto.cipher* contain *new()* function which provides
  52 way to create cipher objects. Cipher padding can be configure later.
  53 This object provides methods *update* and *finish* which allows to
  54 encrypt/decrypt data. All ciphers, supported by your version of OpenSSL
  55 and its loadable engines are supported.
  56
  57 Additionally the **CipherType** class instances may be used directly to
  58 pass to other functions such as CMS EnvelopedData or EncryptedData
  59 **create**
  60
  61 Public key operations
  62 ---------------------
  63
  64 Module **ctypescrypto.pkey** provides **PKey** object, which represents
  65 public/private key pair or just public key. With this object you can
  66 sign data, derive shared key and verify signatures.
  67
  68 This is quite low-level object, which can be used to implement some
  69 non-standard protocols and operations.
  70
  71 It is possible to extract public key from the certificate as PKey
  72 object (see below).
  73
  74 Additional module **ctypescrypto.ec** allows to create **PKey** objects
  75 with elliptic curve keys from just raw secret key as byte buffer or
  76 python big integer.
  77
  78 X509 certificates
  79 -----------------
  80
  81 Module **ctypescrypto.x509** contains objects **X509** which represents
  82 certificate (and can be constructed from string, contained PEM
  83 or DER certificate) and object **X509Store** which is a store of trusted
  84 CA certificates which can be used to high-level signature verifications
  85 (i.e. in PKCS7/CMS messages).
  86
  87 There is no support for creating and signing certificates, i.e. to
  88 perform Certificate Authority functions. This library for now focuses on
  89 cryptography user functionality.
  90
  91 Certificate has properties corresponding to its subject and issuer
  92 names, public key (of course it is PKey object described above) and
  93 serial number. Subject and issuer names can be indexed by OIDs or by
  94 position of field. Unicode in the names is supported.
  95
  96 Support for visualising certificate extensions is minimal for now.
  97 Extension object can be converted into string, extension Oid can be
  98 retrieved and critical flag is checked.
  99
 100 **StackOfX509** implements collection of certificates, necessary for
 101 some operations with CMS and certificate verification.
 102
 103 CMS documents
 104 -------------
 105
 106 There is basic factory function **CMS()**, which parses PEM or der
 107 representation of cryptographic message and generates appropriate
 108 object. There are **SignedData**, **EnvelopedData** and
 109 **EncryptedData** classes. Each class has static method **create**
 110 allowing to create this subtype of message from raw data and appropriate
 111 keys and certificates.
 112
 113 **SignedData** has **verify()** method. **EnvelopedData** and
 114 **EncryptedData** - **decrypt** method.
 115
 116 Unfortunately, **SignedAndEnvelopedData** seems to be unsupported in
 117 libcrypto as of version 1.0.1 of OpenSSL.
 118
 119 PBKDF2
 120 ------
 121
 122 Provides interface to password based key derivation function
 123 Interface slightly differs from the **hashlib.pbkdf2_hmac** function,
 124 which have appeared in Python 2.7.8 but functionality is just same,
 125 although OpenSSL implementation might be faster.
 126
 127
 128
 129 OID database
 130 ------------
 131
 132 OpenSSL contains internal object identifiers (OID) database. Each OID
 133 have apart from dotted-decimal representation long name, short name and
 134 numeric identifier. Module **ctypescrypto.oid** provides interface to the
 135 database. **Oid** objects store numeric identifier internally and can
 136 return both long and short name and dotted-decimal representation.
 137
 138 BIO library
 139 -----------
 140
 141 OpenSSL contain BIO (basic input-output) abstraction. And all object
 142 serialization/deserialization use this library. Also human-readable
 143 representation of  ASN.1 structures use this library extensively. So,
 144 we've to develop python object which allow to read from python string
 145 via BIO abstraction or write to buffer, which can be returned as python
 146 string or unicode object.
 147
 148 Exceptions
 149 ----------
 150
 151 Exceptions, used in the **ctypescrypto** to report problems are tied
 152 closely with OpenSSL error-reporting functions, so if such an exception
 153 occurs, as much as possibly information from inside libcrypto would be
 154 available in the Python
 155
 156 Engine support
 157 --------------
 158
 159 There is just one function **ctypescrypt.engine.set_default**, which loads
 160 specified engine by id and makes it default for all algorithms,
 161 supported by it. It is enough for me to use Russian national
 162 cryptographic algorithms, provided by **gost** engine.
 163
 164 Test Suite
 165 ----------
 166
 167 Tests can be run using
 168
 169     python setup.py test
 170
 171 Test suite is fairly incomplete. Contributions are welcome.
 172
 173 Possible future enhancements
 174 ----------------------------
 175
 176 1. Creation and signing of the certificate requests (PKCS#10)
 177 2. Parsing and analyzing CRLs
 178 3. OCSP ([RFC 6960](http://tools.ietf.org/html/rfc6960))request creation and response parsing
 179 4. Timestamping ([RFC 3161](http://tools.ietf.org/html/rfc3161))
 180 support.
 181 6. MAC support. Few people know that there is more MACs than just HMAC,
 182 and even fewer, that OpenSSL supports them.