4 Python interface to some openssl function based on ctypes module
6 This module is based on works from
8 http://code.google.com/p/ctypescrypto/
10 most recent version can be checked out from
12 https://github.com/vbwagner/ctypescrypto.git
17 Why have yet another crypto extension for Python? There is pyopenssl,
18 m2crypto, hashlib in the standard library and many more.
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.
27 Also, this extension takes some care of correctly converting textual
28 information from ASN.1 structures into unicode.
34 Module **ctypescrypto.digest** contain **new()** function which produces
35 objects simular to python **hashlib** module objects.
37 On the systems where hashlib is linked with libcrypto dynamically,
38 hashlib even able to make use of digest types, provided by loadable
41 This module would utilize same copy of libcrypto library as other
42 ctypescrypto modules, so it would work with engine-provided digests.
44 Additionally there is **DigestType** class which may be needed to
45 construct CMS SignedData objects or add signatures to them.
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".
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.
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.
73 Additionally the **CipherType** class instances may be used directly to
74 pass to other functions such as CMS EnvelopedData or EncryptedData
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.
84 This is quite low-level object, which can be used to implement some
85 non-standard protocols and operations.
87 It is possible to extract public key from the certificate as PKey
90 Additional module **ctypescrypto.ec** allows to create **PKey** objects
91 with elliptic curve keys from just raw secret key as byte buffer or
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,
108 Certificates are described in [RFC 5280](http://tools.ietf.org/html/rfc5280)
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).
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.
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.
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.
129 **StackOfX509** implements collection of certificates, necessary for
130 some operations with CMS and certificate verification.
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.
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.
152 **SignedData** has **verify()** method. **EnvelopedData** and
153 **EncryptedData** - **decrypt** method.
155 Unfortunately, **SignedAndEnvelopedData** seems to be unsupported in
156 libcrypto as of version 1.0.1 of OpenSSL.
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.
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.
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.
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
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.
206 Tests can be run using
210 Test suite is fairly incomplete. Contributions are welcome.
212 Possible future enhancements
213 ----------------------------
215 1. Creation and signing of the certificate requests (PKCS#10)
216 2. Parsing and analyzing CRLs
217 3. OCSP ([RFC 6960](http://tools.ietf.org/html/rfc6960))request creation and response parsing
218 4. Timestamping ([RFC 3161](http://tools.ietf.org/html/rfc3161))
221 vim: spelllang=en tw=72