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 Digest calculation
  32 ------------------
  33
  34 Module **ctypescrypto.digest** contain **new()** function which produces
  35 objects simular to python **hashlib** module objects.
  36
  37 On the systems where hashlib is linked with libcrypto dynamically,
  38 hashlib even able to make use of digest types, provided by loadable
  39 engines.
  40
  41 This module would utilize same copy of libcrypto library as other
  42 ctypescrypto modules, so it would work with engine-provided digests.
  43
  44 Additionally there is **DigestType** class which may be needed to
  45 construct CMS SignedData objects or add signatures to them.
  46
  47
  48 MAC calculation
  49 ---------------
  50
  51 Mac is Message Authentication Code - it is like keyed digest, which
  52 depends not only on message, but also on key, which should be used both
  53 when initially computing MAC and when verifying it. MACs can be viewed
  54 as "digital signatures with symmetric keys".
  55
  56 Most common type of MAC is HMAC (i.e. hash-based MAC), described in
  57 [RFC 2104](https://tools.ietf.org/html/rfc2104), but there are other,
  58 for instance [GOST 28147-89](https://tools.ietf.org/html/rfc5830) defines MAC based on symmetric cipher.
  59 Also GSM 0348 uses DES symmetric cipher as MAC. OpenSSL supports
  60 GOST mac via loadable engine module, but doesn't seem to support any
  61 non-HMAC MAC in the core. So, MAC is only test in the test suite which
  62 requires loadable engine.
  63
  64 Symmetric ciphers
  65 -----------------
  66
  67 Module *ctypescrypto.cipher* contain *new()* function which provides
  68 way to create cipher objects. Cipher padding can be configure later.
  69 This object provides methods *update* and *finish* which allows to
  70 encrypt/decrypt data. All ciphers, supported by your version of OpenSSL
  71 and its loadable engines are supported.
  72
  73 Additionally the **CipherType** class instances may be used directly to
  74 pass to other functions such as CMS EnvelopedData or EncryptedData
  75 **create**
  76
  77 Public key operations
  78 ---------------------
  79
  80 Module **ctypescrypto.pkey** provides **PKey** object, which represents
  81 public/private key pair or just public key. With this object you can
  82 sign data, derive shared key and verify signatures.
  83
  84 This is quite low-level object, which can be used to implement some
  85 non-standard protocols and operations.
  86
  87 It is possible to extract public key from the certificate as PKey
  88 object (see below).
  89
  90 Additional module **ctypescrypto.ec** allows to create **PKey** objects
  91 with elliptic curve keys from just raw secret key as byte buffer or
  92 python big integer.
  93
  94 X509 certificates
  95 -----------------
  96
  97 Certificates are cryptographically signed documents, which tie together
  98 public key and some attributes of key owner (certificate subject).
  99 Certificates are signed by some trusted organizations called Certificate
 100 Authorities (one which have issued given certificate, is called
 101 certificate issuer). Your browser or operating system typically have
 102 predefined store of the trusted CA certificates (although nothing
 103 prevent you from running your own CA using openssl command line utility,
 104 and trust only it).
 105
 106
 107
 108 Certificates are described in [RFC 5280](http://tools.ietf.org/html/rfc5280)
 109
 110 Module **ctypescrypto.x509** contains objects **X509** which represents
 111 certificate (and can be constructed from string, contained PEM
 112 or DER certificate) and object **X509Store** which is a store of trusted
 113 CA certificates which can be used to high-level signature verifications
 114 (i.e. in PKCS7/CMS messages).
 115
 116 There is no support for creating and signing certificates, i.e. to
 117 perform Certificate Authority functions. This library for now focuses on
 118 cryptography user functionality.
 119
 120 Certificate has properties corresponding to its subject and issuer
 121 names, public key (of course it is PKey object described above) and
 122 serial number. Subject and issuer names can be indexed by OIDs or by
 123 position of field. Unicode in the names is supported.
 124
 125 Support for visualising certificate extensions is minimal for now.
 126 Extension object can be converted into string, extension Oid can be
 127 retrieved and critical flag is checked.
 128
 129 **StackOfX509** implements collection of certificates, necessary for
 130 some operations with CMS and certificate verification.
 131
 132 CMS documents
 133 -------------
 134
 135 CMS stands for Cryptographic Message Syntax. It is defined in the
 136 [RFC 5652](http://tools.ietf.org/html/rfc5652).
 137 CMS defines several types of documents. There is **SignedData**,
 138 which can be read by anyone, but is protected from authorized changes
 139 by digital signature of its author. There is **EnvelopedData** protected
 140 from unauthorized reading by cipher and allowed to be read only by
 141 owners of certain private keys, and there is **EncryptedData**, which
 142 are protected by symmetric cipher keys.
 143
 144
 145 There is basic factory function **CMS()**, which parses PEM or der
 146 representation of cryptographic message and generates appropriate
 147 object. There are **SignedData**, **EnvelopedData** and
 148 **EncryptedData** classes. Each class has static method **create**
 149 allowing to create this subtype of message from raw data and appropriate
 150 keys and certificates.
 151
 152 **SignedData** has **verify()** method. **EnvelopedData** and
 153 **EncryptedData** - **decrypt** method.
 154
 155 Unfortunately, **SignedAndEnvelopedData** seems to be unsupported in
 156 libcrypto as of version 1.0.1 of OpenSSL.
 157
 158 PBKDF2
 159 ------
 160
 161 Provides interface to password based key derivation function
 162 Interface slightly differs from the **hashlib.pbkdf2_hmac** function,
 163 which have appeared in Python 2.7.8 but functionality is just same,
 164 although OpenSSL implementation might be faster.
 165
 166
 167
 168 OID database
 169 ------------
 170
 171 OpenSSL contains internal object identifiers (OID) database. Each OID
 172 have apart from dotted-decimal representation long name, short name and
 173 numeric identifier. Module **ctypescrypto.oid** provides interface to the
 174 database. **Oid** objects store numeric identifier internally and can
 175 return both long and short name and dotted-decimal representation.
 176
 177 BIO library
 178 -----------
 179
 180 OpenSSL contain BIO (basic input-output) abstraction. And all object
 181 serialization/deserialization use this library. Also human-readable
 182 representation of  ASN.1 structures use this library extensively. So,
 183 we've to develop python object which allow to read from python string
 184 via BIO abstraction or write to buffer, which can be returned as python
 185 string or unicode object.
 186
 187 Exceptions
 188 ----------
 189
 190 Exceptions, used in the **ctypescrypto** to report problems are tied
 191 closely with OpenSSL error-reporting functions, so if such an exception
 192 occurs, as much as possibly information from inside libcrypto would be
 193 available in the Python
 194
 195 Engine support
 196 --------------
 197
 198 There is just one function **ctypescrypt.engine.set_default**, which loads
 199 specified engine by id and makes it default for all algorithms,
 200 supported by it. It is enough for me to use Russian national
 201 cryptographic algorithms, provided by **gost** engine.
 202
 203 Test Suite
 204 ----------
 205
 206 Tests can be run using
 207
 208     python setup.py test
 209
 210 Test suite is fairly incomplete. Contributions are welcome.
 211
 212 Note that you need properly installed OpenSSL library with set of CA
 213 certificates in the certs directory, otherwise default certstore test
 214 would fail.
 215
 216 You also need gost engine to be available (check with
 217
 218    openssl engine gost
 219
 220 ) otherwise mac test would crash with error. Unfortunately there is no
 221 non-HMAC MAC in the openssl core, so GOST MAC is only option.
 222
 223 Possible future enhancements
 224 ----------------------------
 225
 226 1. Creation and signing of the certificate requests (PKCS#10)
 227 2. Parsing and analyzing CRLs
 228 3. OCSP ([RFC 6960](http://tools.ietf.org/html/rfc6960))request creation and response parsing
 229 4. Timestamping ([RFC 3161](http://tools.ietf.org/html/rfc3161))
 230 support.
 231
 232   vim: spelllang=en tw=72