https://github.com/vbwagner/ctypescrypto.git
-It is aimed to provide Python interface to OpenSSL libcrypto functions.
-All the objects in this library are just wrappers around some OpenSSL
-data structures and groups of functions.
+Rationale
+---------
+Why have yet another crypto extension for Python? There is pyopenssl,
+m2crypto, hashlib in the standard library and many more.
+
+But most of these extension implement interfaces to particular set of
+cryptoalgorthms. This extension takes an another approach — it uses
+algorithm-agnostic EVP layer whenever possible, and so support any
+algorithms which are supported by underlying library, even this
+algorithms are implemented in the loadable modules (engines). Algorithms
+which you've just added to library, should be supported too.
+
+Also, this extension takes some care of correctly converting textual
+information from ASN.1 structures into unicode.
Digest calculation
Additionally there is **DigestType** class which may be needed to
construct CMS SignedData objects or add signatures to them.
+
+MAC calculation
+---------------
+
+Mac is Message Authentication Code - it is like keyed digest, which
+depends not only on message, but also on key, which should be used both
+when initially computing MAC and when verifying it. MACs can be viewed
+as "digital signatures with symmetric keys".
+
+Most common type of MAC is HMAC (i.e. hash-based MAC), described in
+[RFC 2104](https://tools.ietf.org/html/rfc2104), but there are other,
+for instance [GOST 28147-89](https://tools.ietf.org/html/rfc5830) defines MAC based on symmetric cipher.
+Also GSM 0348 uses DES symmetric cipher as MAC. OpenSSL supports
+GOST mac via loadable engine module, but doesn't seem to support any
+non-HMAC MAC in the core. So, MAC is only test in the test suite which
+requires loadable engine.
+
Symmetric ciphers
-----------------
This is quite low-level object, which can be used to implement some
non-standard protocols and operations.
+It is possible to extract public key from the certificate as PKey
+object (see below).
+
Additional module **ctypescrypto.ec** allows to create **PKey** objects
with elliptic curve keys from just raw secret key as byte buffer or
python big integer.
X509 certificates
-----------------
+Certificates are cryptographically signed documents, which tie together
+public key and some attributes of key owner (certificate subject).
+Certificates are signed by some trusted organizations called Certificate
+Authorities (one which have issued given certificate, is called
+certificate issuer). Your browser or operating system typically have
+predefined store of the trusted CA certificates (although nothing
+prevent you from running your own CA using openssl command line utility,
+and trust only it).
+
+
+
+Certificates are described in [RFC 5280](http://tools.ietf.org/html/rfc5280)
+
Module **ctypescrypto.x509** contains objects **X509** which represents
certificate (and can be constructed from string, contained PEM
or DER certificate) and object **X509Store** which is a store of trusted
serial number. Subject and issuer names can be indexed by OIDs or by
position of field. Unicode in the names is supported.
-Support for visualising certificate extensions is missing for now.
+Support for visualising certificate extensions is minimal for now.
+Extension object can be converted into string, extension Oid can be
+retrieved and critical flag is checked.
**StackOfX509** implements collection of certificates, necessary for
some operations with CMS and certificate verification.
CMS documents
-------------
+CMS stands for Cryptographic Message Syntax. It is defined in the
+[RFC 5652](http://tools.ietf.org/html/rfc5652).
+CMS defines several types of documents. There is **SignedData**,
+which can be read by anyone, but is protected from authorized changes
+by digital signature of its author. There is **EnvelopedData** protected
+from unauthorized reading by cipher and allowed to be read only by
+owners of certain private keys, and there is **EncryptedData**, which
+are protected by symmetric cipher keys.
+
+
There is basic factory function **CMS()**, which parses PEM or der
representation of cryptographic message and generates appropriate
object. There are **SignedData**, **EnvelopedData** and
Test Suite
----------
+Tests can be run using
+
+ python setup.py test
+
Test suite is fairly incomplete. Contributions are welcome.
+Note that you need properly installed OpenSSL library with set of CA
+certificates in the certs directory, otherwise default certstore test
+would fail.
+
+You also need gost engine to be available (check with
+
+ openssl engine gost
+
+) otherwise mac test would crash with error. Unfortunately there is no
+non-HMAC MAC in the openssl core, so GOST MAC is only option.
+
+OpenSSL 1.0 includes GOST engine by default. For OpenSSL 1.1 and above
+GOST engine is developed as separate project and can be downloaded from
+[https://github.com/gost-engine/engine](https://github.com/gost-engine/engine)
+Debian buster and above includes gost engine as
+libengine-gost-openssl1.1 package.
+
+
Possible future enhancements
----------------------------
-1. Certificate extension support
-2. Create and signing of the certificate requests (PKCS#10)
-3. Parsing and analyzing CRLs
-4. OCSP request creation and response parsing
-5. Timestamping ([RFC 3161](http://www.ietf.org/rfc/rfc3161.txt))
+1. Creation and signing of the certificate requests (PKCS#10)
+2. Parsing and analyzing CRLs
+3. OCSP ([RFC 6960](http://tools.ietf.org/html/rfc6960))request creation and response parsing
+4. Timestamping ([RFC 3161](http://tools.ietf.org/html/rfc3161))
support.
-6. MAC support. Few people know that there is more MACs than just HMAC,
-and even fewer, that OpenSSL supports them.
+
+ vim: spelllang=en tw=72
projects / oss / ctypescrypto.git / blobdiff