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 There is no support for creating and signing certificates, i.e. to
  73 perform Certificate Authority functions. This library for now focuses on
  74 cryptography user functionality.
  75
  76 Certificate has properties corresponding to its subject and issuer
  77 names, public key (of course it is PKey object described above) and
  78 serial number. Subject and issuer names can be indexed by OIDs or by
  79 position of field. Unicode in the names is supported.
  80
  81 Support for visualising certificate extensions is missing for now.
  82
  83 **StackOfX509** implements collection of certificates, necessary for
  84 some operations with CMS and certificate verification.
  85
  86 CMS documents
  87 -------------
  88
  89 There is basic factory function **CMS()**, which parses PEM or der
  90 representation of cryptographic message and generates appropriate
  91 object. There are **SignedData**, **EnvelopedData** and
  92 **EncryptedData** classes. Each class has static method **create**
  93 allowing to create this subtype of message from raw data and appropriate
  94 keys and certificates.
  95
  96 **SignedData** has **verify()** method. **EnvelopedData** and
  97 **EncryptedData** - **decrypt** method.
  98
  99 Unfortunately, **SignedAndEnvelopedData** seems to be unsupported in
 100 libcrypto as of version 1.0.1 of OpenSSL.
 101
 102 PBKDF2
 103 ------
 104
 105 Provides interface to password based key derivation function
 106 Interface slightly differs from the **hashlib.pbkdf2_hmac** function,
 107 which have appeared in Python 2.7.8 but functionality is just same,
 108 although OpenSSL implementation might be faster.
 109
 110
 111
 112 OID database
 113 ------------
 114
 115 OpenSSL contains internal object identifiers (OID) database. Each OID
 116 have apart from dotted-decimal representation long name, short name and
 117 numeric identifier. Module **ctypescrypto.oid** provides interface to the
 118 database. **Oid** objects store numeric identifier internally and can
 119 return both long and short name and dotted-decimal representation.
 120
 121 BIO library
 122 -----------
 123
 124 OpenSSL contain BIO (basic input-output) abstraction. And all object
 125 serialization/deserialization use this library. Also human-readable
 126 representation of  ASN.1 structures use this library extensively. So,
 127 we've to develop python object which allow to read from python string
 128 via BIO abstraction or write to buffer, which can be returned as python
 129 string or unicode object.
 130
 131 Exceptions
 132 ----------
 133
 134 Exceptions, used in the **ctypescrypto** to report problems are tied
 135 closely with OpenSSL error-reporting functions, so if such an exception
 136 occurs, as much as possibly information from inside libcrypto would be
 137 available in the Python
 138
 139 Engine support
 140 --------------
 141
 142 There is just one function **ctypescrypt.engine.set_default**, which loads
 143 specified engine by id and makes it default for all algorithms,
 144 supported by it. It is enough for me to use Russian national
 145 cryptographic algorithms, provided by **gost** engine.
 146
 147 Test Suite
 148 ----------
 149
 150 Test suite is fairly incomplete. Contributions are welcome.
 151
 152 Possible future enhancements
 153 ----------------------------
 154
 155 1. Certificate extension support
 156 2. Create and signing of the certificate requests (PKCS#10)
 157 3. Parsing and analyzing CRLs
 158 4. OCSP request creation and response parsing
 159 5. Timestamping ([RFC 3161](http://www.ietf.org/rfc/rfc3161.txt))
 160 support.
 161 6. MAC support. Few people know that there is more MACs than just HMAC,
 162 and even fewer, that OpenSSL supports them.