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 Certificates are cryptographically signed documents, which tie together
  82 public key and some attributes of key owner (certificate subject).
  83 Certificates are signed by some trusted organizations called Certificate
  84 Authorities (one which have issued given certificate, is called
  85 certificate issuer). Your browser or operating system typically have
  86 predefined store of the trusted CA certificates (although nothing
  87 prevent you from running your own CA using openssl command line utility,
  88 and trust only it).
  89
  90
  91
  92 Certificates are described in [RFC 5280](http://tools.ietf.org/html/rfc5280)
  93
  94 Module **ctypescrypto.x509** contains objects **X509** which represents
  95 certificate (and can be constructed from string, contained PEM
  96 or DER certificate) and object **X509Store** which is a store of trusted
  97 CA certificates which can be used to high-level signature verifications
  98 (i.e. in PKCS7/CMS messages).
  99
 100 There is no support for creating and signing certificates, i.e. to
 101 perform Certificate Authority functions. This library for now focuses on
 102 cryptography user functionality.
 103
 104 Certificate has properties corresponding to its subject and issuer
 105 names, public key (of course it is PKey object described above) and
 106 serial number. Subject and issuer names can be indexed by OIDs or by
 107 position of field. Unicode in the names is supported.
 108
 109 Support for visualising certificate extensions is minimal for now.
 110 Extension object can be converted into string, extension Oid can be
 111 retrieved and critical flag is checked.
 112
 113 **StackOfX509** implements collection of certificates, necessary for
 114 some operations with CMS and certificate verification.
 115
 116 CMS documents
 117 -------------
 118
 119 CMS stands for Cryptographic Message Syntax. It is defined in the
 120 [RFC 5652](http://tools.ietf.org/html/rfc5652).
 121 CMS defines several types of documents. There is **SignedData**,
 122 which can be read by anyone, but is protected from authorized changes
 123 by digital signature of its author. There is **EnvelopedData** protected
 124 from unauthorized reading by cipher and allowed to be read only by
 125 owners of certain private keys, and there is **EncryptedData**, which
 126 are protected by symmetric cipher keys.
 127
 128
 129 There is basic factory function **CMS()**, which parses PEM or der
 130 representation of cryptographic message and generates appropriate
 131 object. There are **SignedData**, **EnvelopedData** and
 132 **EncryptedData** classes. Each class has static method **create**
 133 allowing to create this subtype of message from raw data and appropriate
 134 keys and certificates.
 135
 136 **SignedData** has **verify()** method. **EnvelopedData** and
 137 **EncryptedData** - **decrypt** method.
 138
 139 Unfortunately, **SignedAndEnvelopedData** seems to be unsupported in
 140 libcrypto as of version 1.0.1 of OpenSSL.
 141
 142 PBKDF2
 143 ------
 144
 145 Provides interface to password based key derivation function
 146 Interface slightly differs from the **hashlib.pbkdf2_hmac** function,
 147 which have appeared in Python 2.7.8 but functionality is just same,
 148 although OpenSSL implementation might be faster.
 149
 150
 151
 152 OID database
 153 ------------
 154
 155 OpenSSL contains internal object identifiers (OID) database. Each OID
 156 have apart from dotted-decimal representation long name, short name and
 157 numeric identifier. Module **ctypescrypto.oid** provides interface to the
 158 database. **Oid** objects store numeric identifier internally and can
 159 return both long and short name and dotted-decimal representation.
 160
 161 BIO library
 162 -----------
 163
 164 OpenSSL contain BIO (basic input-output) abstraction. And all object
 165 serialization/deserialization use this library. Also human-readable
 166 representation of  ASN.1 structures use this library extensively. So,
 167 we've to develop python object which allow to read from python string
 168 via BIO abstraction or write to buffer, which can be returned as python
 169 string or unicode object.
 170
 171 Exceptions
 172 ----------
 173
 174 Exceptions, used in the **ctypescrypto** to report problems are tied
 175 closely with OpenSSL error-reporting functions, so if such an exception
 176 occurs, as much as possibly information from inside libcrypto would be
 177 available in the Python
 178
 179 Engine support
 180 --------------
 181
 182 There is just one function **ctypescrypt.engine.set_default**, which loads
 183 specified engine by id and makes it default for all algorithms,
 184 supported by it. It is enough for me to use Russian national
 185 cryptographic algorithms, provided by **gost** engine.
 186
 187 Test Suite
 188 ----------
 189
 190 Tests can be run using
 191
 192     python setup.py test
 193
 194 Test suite is fairly incomplete. Contributions are welcome.
 195
 196 Possible future enhancements
 197 ----------------------------
 198
 199 1. Creation and signing of the certificate requests (PKCS#10)
 200 2. Parsing and analyzing CRLs
 201 3. OCSP ([RFC 6960](http://tools.ietf.org/html/rfc6960))request creation and response parsing
 202 4. Timestamping ([RFC 3161](http://tools.ietf.org/html/rfc3161))
 203 support.
 204 6. MAC support. Few people know that there is more MACs than just HMAC,
 205 and even fewer, that OpenSSL supports them.
 206
 207   vim: spelllang=en tw=72