cleaned up documentation

diff --git a/README.md b/README.md
index 2054f7bc5730d733c3f3b3d202797e3a503a3a3a..27991db27b447735a1e444ca4fcd520b18b3b641 100644 (file)
--- a/README.md
+++ b/README.md
@@ -7,48 +7,96 @@ This module is based on works from
 
 http://code.google.com/p/ctypescrypto/
 
-It is aimed to provide Python interface to OpenSSL libcrypto function
-
-Now supported:
-
-bio.py - interfase to OpenSSL stream abstraction BIO. Now supports
-       memory BIOs this module intended to use for parsing/serializing
-       various ASN.1 based formats like private keys or certificates
-       Status: bare minimum functionality is implemented and covered by
-       rests
-
-oid.py - interface to OpenSSL ASN.1 Object Identifier databsase.
-       Allows to convert numeric identifier (NIDs) returned by various
-       OpenSSL function to readable names or dotted-decimal OIDs and back
-       Status: Fully implemented and covered by tests.
-
-engine.py - interface to loadable modules with alternate implementations
-    of cryptoalgorithms.
-       Status: Bare minumum, neccessary to use GOST algorithms is
-       implemented.
-
-rand.py - interface to pseudo-random number generator.
-       Status: Implemented. Tests now only ensure that no segfault occurs
-       if arugments are passed correctly
-
-digests.py  - Interface  to EVP\_Digest\* family of functions. 
-       Really does almost same as hashlib, which even is able to take
-       advantage of loaded engines if compiled against dynamic libcrypto
-       Status: fully implemented and covered by tests
-
-ciphers.py - Interface to EVP\_Cipher family of function. 
-       Status: Needs test coverage
-
-pkey.py - Low-level private key operations (like pkey, genpkey and p
-    keyutl command line ops), all via algorithm-agnostic EVP interface.
-       Status: Designed and started to implement but most functionality 
-       not yet covered by tests
-
-exception.py OpenSSL error stack to python exception conversion
-       Implemented.
-
-x509 X509 certificates. Support parsing of X509 certificates,
-       verification and extracting of field values. Possible extnesion -
-       support creattion of PKCS10 certificate requests.
-       Status: Interface designed and partially implemented
+most recent version can be checked out from
+
+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.
+
+
+
+Digest calculation
+------------------
+
+Module *ctypescrypto.digest* contain *new()* function which produces
+objects simular to python *hashlib* module objects. 
+
+On the systems where hashlib is linked with libcrypto dynamically,
+hashlib even able to make use of digest types, provided by loadable
+engines. 
+
+This module would utilize same copy of libcrypto library as other
+ctypescrypto modules, so it would work with engine-provided digests.
+
+Symmetric ciphers
+-----------------
+
+Module *ctypescrypto.cipher* contain *new()* function which provides
+way to create cipher objects. Cipher padding can be configure later.
+This object provides methods *update* and *finish* which allows to
+encrypt/decrypt data. All ciphers, supported by your version of OpenSSL
+and its loadable engines are supported.
+
+Public key operations
+---------------------
+
+Module *ctypescrypto.pkey* provides *PKey* object, which represents
+public/private key pair or just public key. With this object you can
+sign data, derive shared key and verify signatures.
+
+This is quite low-level object, which can be used to implement some
+non-standard protocols and operations.
+
+X509 certificates
+-----------------
+
+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
+CA certificates which can be used to high-level signature verifications
+(i.e. in PKCS7/CMS messages).
+
+Certificate has properties corresponding to its subject and issuer
+names, public key (of course it is PKey object described above) and
+serial number. Subject and issuer names can be indexed by OIDs or by
+position of field. Unicode in the names is supported.
+
+There is no support for certificate validity time yet.
+
+OID database
+------------
+
+OpenSSL conteins internal object identifiers (OID) database. Each OID
+have apart from dotted-decimal representation long name, short name and
+numeric identifer. Module *ctypescrypto.oid* provides interface to the
+database. *Oid* objects store numeric identifier internally and can
+return both long and short name and dotted-decimal representation.
+
+BIO library
+-----------
+
+OpenSSL contain BIO (basic input-output) abstraction. And all object
+serialization/deserialization use this library. Also human-readble
+representation of  ASN.1 structures use this library extensively. So,
+we've to develop python object which allow to read from python string
+via BIO abstraction or write to buffer, which can be returned as python
+string or unicode object. 
+
+Exceptions
+----------
+
+Exceptions, used in the *ctypescrypto* to report problems are tied
+closely with OpenSSL error-reporting functions, so if such an exception
+occurs, as much as possibly information from inside libcrypto would be
+available in the Python
+
+Engine support
+--------------
+
+There is just one function *ctypescrypt.engine.set_default*. which loads 
+specified engine by id and makes it default for all algorithms,
+supported by it. It is enough for me to use Russian national
+cryptographic algoritms, provided by *gost* engine.
 

diff --git a/ctypescrypto/__init__.py b/ctypescrypto/__init__.py
index d4dcf7c103374f834aea36b70f0ca0fabd3ecd72..27ad0c50b8a9efa0f91a851a7381e83cb9f7a809 100644 (file)
--- a/ctypescrypto/__init__.py
+++ b/ctypescrypto/__init__.py
@@ -3,7 +3,15 @@
 
 """
 
-from ctypes import CDLL
+from ctypes import CDLL,c_char_p
+
+def config(filename=None):
+       """
+               Loads OpenSSL Config file. If none are specified, loads default
+               (compiled in) one
+       """
+       libcrypto.OPENSSL_config(filename)
 
 libcrypto = CDLL("libcrypto.so.1.0.0")
+libcrypto.OPENSSL_config.argtypes=(c_char_p,)
 libcrypto.OPENSSL_add_all_algorithms_conf()

diff --git a/ctypescrypto/bio.py b/ctypescrypto/bio.py
index f8150f72cebc25db4b8604a33c88f6a1c64f727d..a33310572cdc54213a70c10881044e0bce0c6fc9 100644 (file)
--- a/ctypescrypto/bio.py
+++ b/ctypescrypto/bio.py
@@ -1,3 +1,6 @@
+"""
+Interface to OpenSSL BIO library
+"""
 from ctypescrypto import libcrypto
 from ctypes import c_char_p, c_void_p, c_int, string_at, c_long,POINTER,byref, create_string_buffer
 class Membio:

diff --git a/ctypescrypto/cipher.py b/ctypescrypto/cipher.py
index 3320d2f95031116e1e1f0d172f9241f05ee4c93c..c2053e988354574d299e0bd1c36e6cf98c7ff701 100644 (file)
--- a/ctypescrypto/cipher.py
+++ b/ctypescrypto/cipher.py
@@ -1,3 +1,7 @@
+"""
+access to symmetric ciphers from libcrypto
+
+"""
 from ctypes import create_string_buffer,c_char_p,c_void_p,c_int,c_long,byref,POINTER
 from ctypescrypto import libcrypto
 from ctypescrypto.exception import LibCryptoError

diff --git a/ctypescrypto/ec.py b/ctypescrypto/ec.py
new file mode 100644 (file)
index 0000000..d325212
--- /dev/null
+++ b/ctypescrypto/ec.py
@@ -0,0 +1,33 @@
+"""
+Support for EC keypair operation missing form public libcrypto API
+"""
+
+
+def create(curve,num):
+       """
+               Creates EC keypair from the just secret key and curve name
+               
+               @param curve - name of elliptic curve
+               @param num - long number representing key
+       """
+       p=libcrypto.EVP_PKEY_new()
+       ec=libcrypto.EC_KEY_new_by_curvename(curve.nid)
+       group=libcrypto.EC_KEY_get0_group(ec)
+       EC_KEY_set_private_key(ec,bn)
+       priv_key=libcrypt.BN_new()
+       ctx=BN_CTX_new()
+       h="%x"%(num)
+       libcrypto.BN_hex2bn(byref(priv_key),h)
+       libcrypto.EC_KEY_set_private_key(ec,priv_key)
+       pub_key=libcrypto.EC_POINT_new(group)
+       libcrypto.EC_POINT_mul(group,pub_key,priv_key,None,None,ctx)
+       libcrypto.BN_free(a)
+       libcrypto.EVP_PKEY_set1_EC_KEY(p,ec)
+       libcrypto.EC_KEY_free(ec)
+       return PKey(ptr=p,cansign=True)
+
+
+libcrypto.EVP_PKEY_new.restype=c_void_p
+libcrypto.BN_new.restype=c_void_p
+libcrypto.BN_hex2bn.argtypes(POINTER(c_void_p),c_char_p)
+libcrypto.EC_KEY_set_private_key

diff --git a/ctypescrypto/engine.py b/ctypescrypto/engine.py
index f05fcb0a49200e2d65149d9166983e6b024f05ab..dd7c0281b34a255670d55ab868322128b10a3d93 100644 (file)
--- a/ctypescrypto/engine.py
+++ b/ctypescrypto/engine.py
@@ -1,9 +1,16 @@
+"""
+engine loading and configuration
+"""
 from ctypes import *
 from ctypescrypto import libcrypto
 from ctypescrypto.exception import LibCryptoError
 default=None
 
 def set_default(engine):
+       """
+               Loads specified engine and sets it as default for all 
+               algorithms, supported by it
+       """
        global default
        e=libcrypto.ENGINE_by_id(engine)
        if e is None:

diff --git a/ctypescrypto/exception.py b/ctypescrypto/exception.py
index f0f3c5343238cabcd382c68ebe03e9738760c7fc..c4710eca32742a817bfb1204a0d7550bcce8d433 100644 (file)
--- a/ctypescrypto/exception.py
+++ b/ctypescrypto/exception.py
@@ -1,3 +1,6 @@
+"""
+Exception which extracts libcrypto error information
+"""
 from ctypes import *
 from ctypescrypto import libcrypto
 strings_loaded=False

diff --git a/ctypescrypto/oid.py b/ctypescrypto/oid.py
index 9852043e0b936cf8e5b9dc5b0c25cbbed2011734..976cd3f8e5b7cf07cc6ab86e93e1400d4acac52d 100644 (file)
--- a/ctypescrypto/oid.py
+++ b/ctypescrypto/oid.py
@@ -1,5 +1,6 @@
 """    
  Interface to OpenSSL object identifier database.
+
  It is primarily intended to deal with OIDs which are compiled into the
  database or defined in the openssl configuration files.
 

diff --git a/ctypescrypto/pkey.py b/ctypescrypto/pkey.py
index e4c8c0257c27924e22f458a529a374517a46c372..f011443a2173ede8058e21c4323ba2967462ace2 100644 (file)
--- a/ctypescrypto/pkey.py
+++ b/ctypescrypto/pkey.py
@@ -1,3 +1,11 @@
+"""
+low-level private/public keypair operation
+
+PKey object of this module is wrapper around OpenSSL EVP_PKEY object.
+"""
+
+This module provides interface for 
+
 from ctypes import c_char_p,c_void_p,byref,c_int,c_long, c_longlong, create_string_buffer,CFUNCTYPE,POINTER
 from ctypescrypto import libcrypto
 from ctypescrypto.exception import LibCryptoError,clear_err_stack
@@ -8,6 +16,11 @@ class PKeyError(LibCryptoError):
 
 CALLBACK_FUNC=CFUNCTYPE(c_int,c_char_p,c_int,c_int,c_char_p)
 def password_callback(buf,length,rwflag,u):
+"""
+Example password callback for private key. Assumes that 
+password is store in the userdata parameter, so allows to pass password
+from constructor arguments to the libcrypto keyloading functions
+"""
        cnt=len(u)
        if length<cnt:
                cnt=length

diff --git a/tests/testcipher.py b/tests/testcipher.py
index d9857cfeb18cb16e32608b9e7ec9f775dd253f2e..3cc848c0a963600841d271c59d0cd6916d924f3a 100644 (file)
--- a/tests/testcipher.py
+++ b/tests/testcipher.py
@@ -1,6 +1,7 @@
 from ctypescrypto.oid import Oid
 from ctypescrypto import cipher
 import unittest
+import sys
 
 
 class TestCipherType(unittest.TestCase):
@@ -84,6 +85,8 @@ class TestEncryptDecrypt(unittest.TestCase):
                c=cipher.new("bf-ofb",encryptkey,iv=iv)
                ciphertext=c.update(data)+c.finish()
                decryptkey=encryptkey[0:5]+encryptkey[5:]
+               with open("cipher.txt","w") as f:
+                       f.write(repr(ciphertext)+"\n")
                d=cipher.new("bf-ofb",decryptkey,encrypt=False,iv=iv)
                deciph=d.update(ciphertext)+d.finish()
                self.assertEqual(deciph,data)