pyGnuTLS is a Python wrapping for GnuTLS

pyGnuTLS - Python wrappings for the GnuTLS Library
--------

GnuTLS is an LGPL library which implements TLS (which you might know as
SSL, they aren't quite the same thing but almost). GnuTLS is written in
C and has excellent documentation for its C functions.

pyGnuTLS lets you call GnuTLS functions from Python. This package has
two version numbers, the first is the version of GnuTLS it was written
against. You should make sure that you install this version of GnuTLS.
The second number is the version of the wrapper code.

This package ships with a .c file and a setup.py file. If you're looking
for a quick solution try:
	./setup.py install
That should do something sensible on most systems. Note that you need to
have GnuTLS installed first.

If you intend on editing anything a quick glance at the gnutls.c file
will show you that changes are not made there. See the HACKING section at
the bottom.

CHANGES
-------

0.2.1 - Patch from Johan Rydberg;
           Expections now contain the number of the error - not the string value
           Added function certificate_server_set_request 
           Added function set_x509_trust
           Several functions failed to keep references to
             objects which were passed to C functions as pointer leading to all
             manner of badness when those objects were collected

BUGS
----

It probably has them, probably many. Reports can be sent to
agl@imperialviolet.org. You get better service if you include a patch.

If you find a problem please *make sure that you're running Python 2.4*
(or greater). If you want to send a patch which makes it work under
lesser versions (and there's no reason that it shouldn't) - wonderful.
But I'm not really interested in supporting old versions of Python.

COVERAGE
--------

The wrappers currently don't cover these areas of GnuTLS:
	OpenPGP
	CRL
	CRQ
	SRP
	PKCS12
	PKCS7

If you have a pressing need for these features I'll probably get round
to writing them, but emailing me to let me know that there's demand will
get it done faster. Better yet, see the HACKING section, do it yourself
and teach yourself Pyrex at the same time!


USAGE
-----

If you're just trying to install pyGnuTLS you should be done. As a test,
try this:
	$ python
	Python 2.4.1 (#1, Apr  6 2005, 21:02:58) 
	[GCC 3.4.2  (Gentoo Linux 3.4.2-r2, ssp-3.4.1-1, pie-8.7.6.5)] on
	linux2
	Type "help", "copyright", "credits" or "license" for more
	information.
	>>> import gnutls
	>>>
If you see something like that it's all working. Smile.

So, you're wanting to write code that uses GnuTLS. Firstly, you'll need
the GnuTLS documentation open in front of you. This wrapper very
closely follows the C functions of GnuTLS.

(it may be helpful to have a look at the files in examples/ before
reading the rest of this)

The following classes exist:
	Session
	AnonServerCred
	AnonClientCred
	CertificateCred
	X509Cert
	X509Privkey

If there exists a function which takes one of these as the first
argument (e.g. gnutls_session_t functions are in the Session class) then
you can probably drop change "gnutls_session_X" into Session.X.

Arguments of type gnutls_datum_t are passed as Python strings.

Enum values exist without the GNUTLS_ prefix. For each enum there is a
reverse lookup dictionary. Thus GNUTLS_CLIENT is in the enum
gnutls_connection_end_t so:
	>>> gnutls.connection_end[gnutls.CLIENT]
	'CLIENT'
and so on. (Note that the "gnutls_" and "_t" are removed from the name)

Functions which take a flags parameter at the end probably have a
default value of 0 for it. Functions which take a format parameter at
the end probably have a default value of X509_FMT_PEM.

A few functions deserve special mention:
	Session.send/recv
		use these names rather than record_send/record_recv (though they
		also work)
	Session.server_name_get
		functions which take an index argument will raise IndexError
		when the index is too great. They will also have a version which
		returns all the values in a list. In this case that is called
		server_names_get
	Session.*_set_priority
		pass a list of enum values
	Session.certificate_client_retrieve_function
		In GnuTLS this function acts on a credentials structure. in
		pyGnuTLS is acts on both a session and a credentials structure.

		The reason for this is that we need somewhere to store the
		pointer to the Python callback function, since the C code cannot
		call it directly. This pointer is stored in the Session object.
		Thus *once this function has been called on a credentials object
		it must be called with that object on every session which uses
		it*. Let me try that again - calling this function on SESSION
		and CRED changes CRED such that it expects a callback function.
		If you link CRED with another Session object, SESSION2, using
		credentials_set you must also call this function.

		The callback function gets passed (Session, string, [int]) where
		the string the DER encoded list of acceptable CAs and the list
		of ints is a list of pk algorithms. The function should return
		([X509Cert], X509Privkey) or may return (None, None) if no
		certificates are valid.
	any function which would be called `import'
		... will be called import_data since import is a Python keyword
	get_*_key_id
	get_subject_alt_name
	get_ca_status
	get_key_usage
	get_extension_by_oid
		these functions return a tuple where the first element is the 
		key id and the second is a boolean called is_critical (see
		GnuTLS documentation)

HACKING
-------

The gnutls.c file is generated by Pyrex. The input to Pyrex is, itself,
generated from a small Python script and a number of Pyrex fragments. If
you want to hack pyGnuTLS you'll need to install Pyrex from
http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/.

Most of the actual guts can be found in the gnutls-footer.py file. This is
actually a Pyrex (.pyx) file, but I call it .py because that's what my
python mode bindings are triggered by (lame I know).

Once you've edited the gnutls-footer.py file you should need to edit the
Makefile and fix the paths in it. After that, running make should
generate gnutls.pyx, then gnutls.c and then build gnutls.so.