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 Symmetric ciphers
  34 -----------------
  35
  36 Module *ctypescrypto.cipher* contain *new()* function which provides
  37 way to create cipher objects. Cipher padding can be configure later.
  38 This object provides methods *update* and *finish* which allows to
  39 encrypt/decrypt data. All ciphers, supported by your version of OpenSSL
  40 and its loadable engines are supported.
  41
  42 Public key operations
  43 ---------------------
  44
  45 Module *ctypescrypto.pkey* provides *PKey* object, which represents
  46 public/private key pair or just public key. With this object you can
  47 sign data, derive shared key and verify signatures.
  48
  49 This is quite low-level object, which can be used to implement some
  50 non-standard protocols and operations.
  51
  52 X509 certificates
  53 -----------------
  54
  55 Module *ctypescrypto.x509* contains objects *X509* which represents
  56 certificate (and can be constructed from string, contained PEM
  57 or DER certificate) and object *X509Store* which is a store of trusted
  58 CA certificates which can be used to high-level signature verifications
  59 (i.e. in PKCS7/CMS messages).
  60
  61 Certificate has properties corresponding to its subject and issuer
  62 names, public key (of course it is PKey object described above) and
  63 serial number. Subject and issuer names can be indexed by OIDs or by
  64 position of field. Unicode in the names is supported.
  65
  66 There is no support for certificate validity time yet.
  67
  68 OID database
  69 ------------
  70
  71 OpenSSL conteins internal object identifiers (OID) database. Each OID
  72 have apart from dotted-decimal representation long name, short name and
  73 numeric identifer. Module *ctypescrypto.oid* provides interface to the
  74 database. *Oid* objects store numeric identifier internally and can
  75 return both long and short name and dotted-decimal representation.
  76
  77 BIO library
  78 -----------
  79
  80 OpenSSL contain BIO (basic input-output) abstraction. And all object
  81 serialization/deserialization use this library. Also human-readble
  82 representation of  ASN.1 structures use this library extensively. So,
  83 we've to develop python object which allow to read from python string
  84 via BIO abstraction or write to buffer, which can be returned as python
  85 string or unicode object.
  86
  87 Exceptions
  88 ----------
  89
  90 Exceptions, used in the *ctypescrypto* to report problems are tied
  91 closely with OpenSSL error-reporting functions, so if such an exception
  92 occurs, as much as possibly information from inside libcrypto would be
  93 available in the Python
  94
  95 Engine support
  96 --------------
  97
  98 There is just one function *ctypescrypt.engine.set_default*. which loads
  99 specified engine by id and makes it default for all algorithms,
 100 supported by it. It is enough for me to use Russian national
 101 cryptographic algoritms, provided by *gost* engine.
 102