blob: ec8831de17c1a141d73d282e90e1c689a1619ee5 [file] [log] [blame]
Jean-Paul Calderone897bc252008-02-18 20:50:23 -05001\documentclass{howto}
2
3\title{Python OpenSSL Manual}
4
5\release{0.6}
6
7\author{Martin Sjögren}
8\authoraddress{\email{martin@strakt.com}}
9
10\usepackage[english]{babel}
11\usepackage[T1]{fontenc}
12
13\begin{document}
14
15\maketitle
16
17\begin{abstract}
18\noindent
19This module is a rather thin wrapper around (a subset of) the OpenSSL library.
20With thin wrapper I mean that a lot of the object methods do nothing more than
21calling a corresponding function in the OpenSSL library.
22\end{abstract}
23
24\tableofcontents
25
26
27\section{Introduction \label{intro}}
28
29The reason this module exists at all is that the SSL support in the socket
30module in the Python 2.1 distribution (which is what we used, of course I
31cannot speak for later versions) is severely limited.
32
33When asking about SSL on the comp.lang.python newsgroup (or on
34python-list@python.org) people usually pointed you to the M2Crypto package.
35The M2Crypto.SSL module does implement a lot of OpenSSL's functionality but
36unfortunately its error handling system does not seem to be finished,
37especially for non-blocking I/O. I think that much of the reason for this
38is that M2Crypto\footnote{See \url{http://www.post1.com/home/ngps/m2/}} is
39developed using SWIG\footnote{See \url{http://swig.sourceforge.net/}}. This
40makes it awkward to create functions that e.g. can return both an integer and
41NULL since (as far as I know) you basically write C functions and SWIG makes
42wrapper functions that parses the Python argument list and calls your C
43function, and finally transforms your return value to a Python object.
44
45
46\section{Building and Installing \label{building}}
47
48These instructions can also be found in the file \verb|INSTALL|.
49
50I have tested this on Debian Linux systems (woody and sid), Solaris 2.6 and
512.7. Others have successfully compiled it on Windows and NT.
52
53\subsection{Building the Module on a Unix System \label{building-unix}}
54
55pyOpenSSL uses distutils, so there really shouldn't be any problems. To build
56the library:
57\begin{verbatim}
58python setup.py build
59\end{verbatim}
60
61If your OpenSSL header files aren't in \verb|/usr/include|, you may need to
62supply the \verb|-I| flag to let the setup script know where to look. The same
63goes for the libraries of course, use the \verb|-L| flag. Note that
64\verb|build| won't accept these flags, so you have to run first
65\verb|build_ext| and then \verb|build|! Example:
66\begin{verbatim}
67python setup.py build_ext -I/usr/local/ssl/include -L/usr/local/ssl/lib
68python setup.py build
69\end{verbatim}
70
71Now you should have a directory called \verb|OpenSSL| that contains e.g.
72\verb|SSL.so| and \verb|__init__.py| somewhere in the build dicrectory,
73so just:
74\begin{verbatim}
75python setup.py install
76\end{verbatim}
77
78If you, for some arcane reason, don't want the module to appear in the
79\verb|site-packages| directory, use the \verb|--prefix| option.
80
81You can, of course, do
82\begin{verbatim}
83python setup.py --help
84\end{verbatim}
85
86to find out more about how to use the script.
87
88\subsection{Building the Module on a Windows System \label{building-windows}}
89
90Big thanks to Itamar Shtull-Trauring and Oleg Orlov for their help with
91Windows build instructions. Same as for Unix systems, we have to separate
92the \verb|build_ext| and the \verb|build|.
93
94Building the library:
95
96\begin{verbatim}
97setup.py build_ext -I ...\openssl\inc32 -L ...\openssl\out32dll
98setup.py build
99\end{verbatim}
100
101Where \verb|...\openssl| is of course the location of your OpenSSL installation.
102
103Installation is the same as for Unix systems:
104\begin{verbatim}
105setup.py install
106\end{verbatim}
107
108And similarily, you can do
109\begin{verbatim}
110setup.py --help
111\end{verbatim}
112
113to get more information.
114
115
116\section{\module{OpenSSL} --- Python interface to OpenSSL \label{openssl}}
117
118\declaremodule{extension}{OpenSSL}
119\modulesynopsis{Python interface to OpenSSL}
120
121This package provides a high-level interface to the functions in the
122OpenSSL library. The following modules are defined:
123
124\begin{datadesc}{crypto}
125Generic cryptographic module. Note that if anything is incomplete, this module is!
126\end{datadesc}
127
128\begin{datadesc}{rand}
129An interface to the OpenSSL pseudo random number generator.
130\end{datadesc}
131
132\begin{datadesc}{SSL}
133An interface to the SSL-specific parts of OpenSSL.
134\end{datadesc}
135
136
137% % % crypto moduleOpenSSL
138
139\subsection{\module{crypto} --- Generic cryptographic module \label{openssl-crypto}}
140
141\declaremodule{extension}{crypto}
142\modulesynopsis{Generic cryptographic module}
143
144\begin{datadesc}{X509Type}
145A Python type object representing the X509 object type.
146\end{datadesc}
147
148\begin{funcdesc}{X509}{}
149Factory function that creates an X509 object.
150\end{funcdesc}
151
152\begin{datadesc}{X509NameType}
153A Python type object representing the X509Name object type.
154\end{datadesc}
155
156\begin{funcdesc}{X509Name}{x509name}
157Factory function that creates a copy of \var{x509name}.
158\end{funcdesc}
159
160\begin{datadesc}{X509ReqType}
161A Python type object representing the X509Req object type.
162\end{datadesc}
163
164\begin{funcdesc}{X509Req}{}
165Factory function that creates an X509Req object.
166\end{funcdesc}
167
168\begin{datadesc}{X509StoreType}
169A Python type object representing the X509Store object type.
170\end{datadesc}
171
172\begin{datadesc}{PKeyType}
173A Python type object representing the PKey object type.
174\end{datadesc}
175
176\begin{funcdesc}{PKey}{}
177Factory function that creates a PKey object.
178\end{funcdesc}
179
180\begin{datadesc}{PKCS7Type}
181A Python type object representing the PKCS7 object type.
182\end{datadesc}
183
184\begin{datadesc}{PKCS12Type}
185A Python type object representing the PKCS12 object type.
186\end{datadesc}
187
188\begin{datadesc}{X509ExtensionType}
189A Python type object representing the X509Extension object type.
190\end{datadesc}
191
192\begin{funcdesc}{X509Extension}{typename, critical, value}
193Factory function that creates a X509Extension object.
194\end{funcdesc}
195
196\begin{datadesc}{NetscapeSPKIType}
197A Python type object representing the NetscapeSPKI object type.
198\end{datadesc}
199
200\begin{funcdesc}{NetscapeSPKI}{\optional{enc}}
201Factory function that creates a NetscapeSPKI object. If the \var{enc} argument
202is present, it should be a base64-encoded string representing a NetscapeSPKI
203object, as returned by the \method{b64_encode} method.
204\end{funcdesc}
205
206\begin{datadesc}{FILETYPE_PEM}
207\dataline{FILETYPE_ASN1}
208File type constants.
209\end{datadesc}
210
211\begin{datadesc}{TYPE_RSA}
212\dataline{TYPE_DSA}
213Key type constants.
214\end{datadesc}
215
216\begin{excdesc}{Error}
217Generic exception used in the \module{crypto} module.
218\end{excdesc}
219
220\begin{funcdesc}{dump_certificate}{type, cert}
221Dump the certificate \var{cert} into a buffer string encoded with the type
222\var{type}.
223\end{funcdesc}
224
225\begin{funcdesc}{dump_certificate_request}{type, req}
226Dump the certificate request \var{req} into a buffer string encoded with the
227type \var{type}.
228\end{funcdesc}
229
230\begin{funcdesc}{dump_privatekey}{type, pkey\optional{, cipher, passphrase}}
231Dump the private key \var{pkey} into a buffer string encoded with the type
232\var{type}, optionally (if \var{type} is \constant{FILETYPE_PEM}) encrypting it
233using \var{cipher} and \var{passphrase}.
234
235\var{passphrase} must be either a string or a callback for providing the
236pass phrase.
237\end{funcdesc}
238
239\begin{funcdesc}{load_certificate}{type, buffer}
240Load a certificate (X509) from the string \var{buffer} encoded with the
241type \var{type}.
242\end{funcdesc}
243
244\begin{funcdesc}{load_certificate_request}{type, buffer}
245Load a certificate request (X509Req) from the string \var{buffer} encoded with
246the type \var{type}.
247\end{funcdesc}
248
249\begin{funcdesc}{load_privatekey}{type, buffer\optional{, passphrase}}
250Load a private key (PKey) from the string \var{buffer} encoded with
251the type \var{type} (must be one of \constant{FILETYPE_PEM} and
252\constant{FILETYPE_ASN1}).
253
254\var{passphrase} must be either a string or a callback for providing the
255pass phrase.
256\end{funcdesc}
257
258\begin{funcdesc}{load_pkcs7_data}{type, buffer}
259Load pkcs7 data from the string \var{buffer} encoded with the type \var{type}.
260\end{funcdesc}
261
262\begin{funcdesc}{load_pkcs12}{buffer\optional{, passphrase}}
263Load pkcs12 data from the string \var{buffer}. If the pkcs12 structure is
264encrypted, a \var{passphrase} must be included.
265\end{funcdesc}
266
267
268\subsubsection{X509 objects \label{openssl-x509}}
269
270X509 objects have the following methods:
271
272\begin{methoddesc}[X509]{get_issuer}{}
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500273Return an X509Name object representing the issuer of the certificate.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500274\end{methoddesc}
275
276\begin{methoddesc}[X509]{get_pubkey}{}
277Return a PKey object representing the public key of the certificate.
278\end{methoddesc}
279
280\begin{methoddesc}[X509]{get_serial_number}{}
281Return the certificate serial number.
282\end{methoddesc}
283
284\begin{methoddesc}[X509]{get_subject}{}
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500285Return an X509Name object representing the subject of the certificate.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500286\end{methoddesc}
287
288\begin{methoddesc}[X509]{get_version}{}
289Return the certificate version.
290\end{methoddesc}
291
Jean-Paul Calderone525ef802008-03-09 20:39:42 -0400292\begin{methoddesc}[X509]{get_notBefore}{}
293Return a string giving the time before which the certificate is not valid. The
294string is formatted as an ASN1 GENERALIZEDTIME:
295\begin{verbatim}
296 YYYYMMDDhhmmssZ
297 YYYYMMDDhhmmss+hhmm
298 YYYYMMDDhhmmss-hhmm
299\end{verbatim}
300\end{methoddesc}
301
302\begin{methoddesc}[X509]{get_notAfter}{}
303Return a string giving the time after which the certificate is not valid. The
304string is formatted as an ASN1 GENERALIZEDTIME:
305\begin{verbatim}
306 YYYYMMDDhhmmssZ
307 YYYYMMDDhhmmss+hhmm
308 YYYYMMDDhhmmss-hhmm
309\end{verbatim}
310\end{methoddesc}
311
312\begin{methoddesc}[X509]{set_notBefore}{when}
313Change the time before which the certificate is not valid. \var{when} is a
314string formatted as an ASN1 GENERALIZEDTIME:
315\begin{verbatim}
316 YYYYMMDDhhmmssZ
317 YYYYMMDDhhmmss+hhmm
318 YYYYMMDDhhmmss-hhmm
319\end{verbatim}
320\end{methoddesc}
321
322\begin{methoddesc}[X509]{set_notAfter}{when}
323Change the time after which the certificate is not valid. \var{when} is a
324string formatted as an ASN1 GENERALIZEDTIME:
325\begin{verbatim}
326 YYYYMMDDhhmmssZ
327 YYYYMMDDhhmmss+hhmm
328 YYYYMMDDhhmmss-hhmm
329\end{verbatim}
330\end{methoddesc}
331
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500332\begin{methoddesc}[X509]{gmtime_adj_notBefore}{time}
333Adjust the timestamp (in GMT) when the certificate starts being valid.
334\end{methoddesc}
335
336\begin{methoddesc}[X509]{gmtime_adj_notAfter}{time}
337Adjust the timestamp (in GMT) when the certificate stops being valid.
338\end{methoddesc}
339
340\begin{methoddesc}[X509]{has_expired}{}
341Checks the certificate's time stamp against current time. Returns true if the
342certificate has expired and false otherwise.
343\end{methoddesc}
344
345\begin{methoddesc}[X509]{set_issuer}{issuer}
346Set the issuer of the certificate to \var{issuer}.
347\end{methoddesc}
348
349\begin{methoddesc}[X509]{set_pubkey}{pkey}
350Set the public key of the certificate to \var{pkey}.
351\end{methoddesc}
352
353\begin{methoddesc}[X509]{set_serial_number}{serialno}
354Set the serial number of the certificate to \var{serialno}.
355\end{methoddesc}
356
357\begin{methoddesc}[X509]{set_subject}{subject}
358Set the subject of the certificate to \var{subject}.
359\end{methoddesc}
360
361\begin{methoddesc}[X509]{set_version}{version}
362Set the certificate version to \var{version}.
363\end{methoddesc}
364
365\begin{methoddesc}[X509]{sign}{pkey, digest}
366Sign the certificate, using the key \var{pkey} and the message digest algorithm
367identified by the string \var{digest}.
368\end{methoddesc}
369
370\begin{methoddesc}[X509]{subject_name_hash}{}
371Return the hash of the certificate subject.
372\end{methoddesc}
373
374\begin{methoddesc}[X509]{digest}{digest_name}
375Return a digest of the certificate, using the \var{digest_name} method.
376\end{methoddesc}
377
378\begin{methoddesc}[X509]{add_extensions}{extensions}
379Add the extensions in the sequence \var{extensions} to the certificate.
380\end{methoddesc}
381
382\subsubsection{X509Name objects \label{openssl-x509name}}
383
384X509Name objects have the following members:
385
386\begin{memberdesc}[X509Name]{countryName}
387The country of the entity. \code{C} may be used as an alias for
388\code{countryName}.
389\end{memberdesc}
390
391\begin{memberdesc}[X509Name]{stateOrProvinceName}
392The state or province of the entity. \code{ST} may be used as an alias for
393\code{stateOrProvinceName}·
394\end{memberdesc}
395
396\begin{memberdesc}[X509Name]{localityName}
397The locality of the entity. \code{L} may be used as an alias for
398\code{localityName}.
399\end{memberdesc}
400
401\begin{memberdesc}[X509Name]{organizationName}
402The organization name of the entity. \code{O} may be used as an alias for
403\code{organizationName}.
404\end{memberdesc}
405
406\begin{memberdesc}[X509Name]{organizationalUnitName}
407The organizational unit of the entity. \code{OU} may be used as an alias for
408\code{organizationalUnitName}.
409\end{memberdesc}
410
411\begin{memberdesc}[X509Name]{commonName}
412The common name of the entity. \code{CN} may be used as an alias for
413\code{commonName}.
414\end{memberdesc}
415
416\begin{memberdesc}[X509Name]{emailAddress}
417The e-mail address of the entity.
418\end{memberdesc}
419
420\subsubsection{X509Req objects \label{openssl-x509req}}
421
422X509Req objects have the following methods:
423
424\begin{methoddesc}[X509Req]{get_pubkey}{}
425Return a PKey object representing the public key of the certificate request.
426\end{methoddesc}
427
428\begin{methoddesc}[X509Req]{get_subject}{}
Jean-Paul Calderone2aa2b332008-03-06 21:43:14 -0500429Return an X509Name object representing the subject of the certificate.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500430\end{methoddesc}
431
432\begin{methoddesc}[X509Req]{set_pubkey}{pkey}
433Set the public key of the certificate request to \var{pkey}.
434\end{methoddesc}
435
436\begin{methoddesc}[X509Req]{sign}{pkey, digest}
437Sign the certificate request, using the key \var{pkey} and the message digest
438algorithm identified by the string \var{digest}.
439\end{methoddesc}
440
441\begin{methoddesc}[X509Req]{verify}{pkey}
442Verify a certificate request using the public key \var{pkey}.
443\end{methoddesc}
444
445\subsubsection{X509Store objects \label{openssl-x509store}}
446
447The X509Store object has currently just one method:
448
449\begin{methoddesc}[X509Store]{add_cert}{cert}
450Add the certificate \var{cert} to the certificate store.
451\end{methoddesc}
452
453\subsubsection{PKey objects \label{openssl-pkey}}
454
455The PKey object has the following methods:
456
457\begin{methoddesc}[PKey]{bits}{}
458Return the number of bits of the key.
459\end{methoddesc}
460
461\begin{methoddesc}[PKey]{generate_key}{type, bits}
462Generate a public/private key pair of the type \var{type} (one of
463\constant{TYPE_RSA} and \constant{TYPE_DSA}) with the size \var{bits}.
464\end{methoddesc}
465
466\begin{methoddesc}[PKey]{type}{}
467Return the type of the key.
468\end{methoddesc}
469
470\subsubsection{PKCS7 objects \label{openssl-pkcs7}}
471
472PKCS7 objects have the following methods:
473
474\begin{methoddesc}[PKCS7]{type_is_signed}{}
475FIXME
476\end{methoddesc}
477
478\begin{methoddesc}[PKCS7]{type_is_enveloped}{}
479FIXME
480\end{methoddesc}
481
482\begin{methoddesc}[PKCS7]{type_is_signedAndEnveloped}{}
483FIXME
484\end{methoddesc}
485
486\begin{methoddesc}[PKCS7]{type_is_data}{}
487FIXME
488\end{methoddesc}
489
490\begin{methoddesc}[PKCS7]{get_type_name}{}
491Get the type name of the PKCS7.
492\end{methoddesc}
493
494\subsubsection{PKCS12 objects \label{openssl-pkcs12}}
495
496PKCS12 objects have the following methods:
497
498\begin{methoddesc}[PKCS12]{get_certificate}{}
499Return certificate portion of the PKCS12 structure.
500\end{methoddesc}
501
502\begin{methoddesc}[PKCS12]{get_privatekey}{}
503Return private key portion of the PKCS12 structure
504\end{methoddesc}
505
506\begin{methoddesc}[PKCS12]{get_ca_certificates}{}
507Return CA certificates within the PKCS12 object as a tuple. Returns
508None if no CA certificates are present.
509\end{methoddesc}
510
511\subsubsection{X509Extension objects \label{openssl-509ext}}
512
513X509Extension objects currently only have one method:
514
515\begin{methoddesc}[X509Extension]{get_critical}{}
516Return the critical field of the extension object.
517\end{methoddesc}
518
519\subsubsection{NetscapeSPKI objects \label{openssl-netscape-spki}}
520
521NetscapeSPKI objects have the following methods:
522
523\begin{methoddesc}[NetscapeSPKI]{b64_encode}{}
524Return a base64-encoded string representation of the object.
525\end{methoddesc}
526
527\begin{methoddesc}[NetscapeSPKI]{get_pubkey}{}
528Return the public key of object.
529\end{methoddesc}
530
531\begin{methoddesc}[NetscapeSPKI]{set_pubkey}{key}
532Set the public key of the object to \var{key}.
533\end{methoddesc}
534
535\begin{methoddesc}[NetscapeSPKI]{sign}{key, digest_name}
536Sign the NetscapeSPKI object using the given \var{key} and \var{digest_name}.
537\end{methoddesc}
538
539\begin{methoddesc}[NetscapeSPKI]{verify}{key}
540Verify the NetscapeSPKI object using the given \var{key}.
541\end{methoddesc}
542
543
544% % % rand module
545
546\subsection{\module{rand} --- An interface to the OpenSSL pseudo random number generator \label{openssl-rand}}
547
548\declaremodule{extension}{rand}
549\modulesynopsis{An interface to the OpenSSL pseudo random number generator}
550
551This module handles the OpenSSL pseudo random number generator (PRNG) and
552declares the following:
553
554\begin{funcdesc}{add}{string, entropy}
555Mix bytes from \var{string} into the PRNG state. The \var{entropy} argument is
556(the lower bound of) an estimate of how much randomness is contained in
557\var{string}, measured in bytes. For more information, see e.g. \rfc{1750}.
558\end{funcdesc}
559
560\begin{funcdesc}{egd}{path\optional{, bytes}}
561Query the Entropy Gathering Daemon\footnote{See
562\url{http://www.lothar.com/tech/crypto/}} on socket \var{path} for \var{bytes}
563bytes of random data and and uses \function{add} to seed the PRNG. The default
564value of \var{bytes} is 255.
565\end{funcdesc}
566
567\begin{funcdesc}{load_file}{path\optional{, bytes}}
568Read \var{bytes} bytes (or all of it, if \var{bytes} is negative) of data from
569the file \var{path} to seed the PRNG. The default value of \var{bytes} is -1.
570\end{funcdesc}
571
572\begin{funcdesc}{screen}{}
573Add the current contents of the screen to the PRNG state.
574Availability: Windows.
575\end{funcdesc}
576
577\begin{funcdesc}{seed}{string}
578This is equivalent to calling \function{add} with \var{entropy} as the length
579of the string.
580\end{funcdesc}
581
582\begin{funcdesc}{status}{}
583Returns true if the PRNG has been seeded with enough data, and false otherwise.
584\end{funcdesc}
585
586\begin{funcdesc}{write_file}{path}
587Write a number of random bytes (currently 1024) to the file \var{path}. This
588file can then be used with \function{load_file} to seed the PRNG again.
589\end{funcdesc}
590
591
592
593% % % SSL module
594
595\subsection{\module{SSL} --- An interface to the SSL-specific parts of OpenSSL \label{openssl-ssl}}
596
597\declaremodule{extension}{SSL}
598\modulesynopsis{An interface to the SSL-specific parts of OpenSSL}
599
600This module handles things specific to SSL. There are two objects defined:
601Context, Connection.
602
603\begin{datadesc}{SSLv2_METHOD}
604\dataline{SSLv3_METHOD}
605\dataline{SSLv23_METHOD}
606\dataline{TLSv1_METHOD}
607These constants represent the different SSL methods to use when creating a
608context object.
609\end{datadesc}
610
611\begin{datadesc}{VERIFY_NONE}
612\dataline{VERIFY_PEER}
613\dataline{VERIFY_FAIL_IF_NO_PEER_CERT}
614These constants represent the verification mode used by the Context
615object's \method{set_verify} method.
616\end{datadesc}
617
618\begin{datadesc}{FILETYPE_PEM}
619\dataline{FILETYPE_ASN1}
620File type constants used with the \method{use_certificate_file} and
621\method{use_privatekey_file} methods of Context objects.
622\end{datadesc}
623
624\begin{datadesc}{OP_SINGLE_DH_USE}
625\dataline{OP_EPHEMERAL_RSA}
626\dataline{OP_NO_SSLv2}
627\dataline{OP_NO_SSLv3}
628\dataline{OP_NO_TLSv1}
629Constants used with \method{set_options} of Context objects.
630\constant{OP_SINGLE_DH_USE} means to always create a new key when using ephemeral
631Diffie-Hellman. \constant{OP_EPHEMERAL_RSA} means to always use ephemeral RSA keys
632when doing RSA operations. \constant{OP_NO_SSLv2}, \constant{OP_NO_SSLv3} and
633\constant{OP_NO_TLSv1} means to disable those specific protocols. This is
634interesting if you're using e.g. \constant{SSLv23_METHOD} to get an SSLv2-compatible
635handshake, but don't want to use SSLv2.
636\end{datadesc}
637
638\begin{datadesc}{ContextType}
639A Python type object representing the Context object type.
640\end{datadesc}
641
642\begin{funcdesc}{Context}{method}
643Factory function that creates a new Context object given an SSL method. The
644method should be \constant{SSLv2_METHOD}, \constant{SSLv3_METHOD},
645\constant{SSLv23_METHOD} or \constant{TLSv1_METHOD}.
646\end{funcdesc}
647
648\begin{datadesc}{ConnectionType}
649A Python type object representing the Connection object type.
650\end{datadesc}
651
652\begin{funcdesc}{Connection}{context, socket}
653Factory fucnction that creates a new Connection object given an SSL context and
654a socket \footnote{Actually, all that is required is an object that
655\emph{behaves} like a socket, you could even use files, even though it'd be
656tricky to get the handshakes right!} object.
657\end{funcdesc}
658
659\begin{excdesc}{Error}
660This exception is used as a base class for the other SSL-related
661exceptions, but may also be raised directly.
662
663Whenever this exception is raised directly, it has a list of error messages
664from the OpenSSL error queue, where each item is a tuple \code{(\var{lib},
665\var{function}, \var{reason})}. Here \var{lib}, \var{function} and \var{reason}
666are all strings, describing where and what the problem is. See \manpage{err}{3}
667for more information.
668\end{excdesc}
669
670\begin{excdesc}{ZeroReturnError}
671This exception matches the error return code \code{SSL_ERROR_ZERO_RETURN}, and
672is raised when the SSL Connection has been closed. In SSL 3.0 and TLS 1.0, this
673only occurs if a closure alert has occurred in the protocol, i.e. the
674connection has been closed cleanly. Note that this does not necessarily
675mean that the transport layer (e.g. a socket) has been closed.
676
677It may seem a little strange that this is an exception, but it does match an
678\code{SSL_ERROR} code, and is very convenient.
679\end{excdesc}
680
681\begin{excdesc}{WantReadError}
682The operation did not complete; the same I/O method should be called again
683later, with the same arguments. Any I/O method can lead to this since new
684handshakes can occur at any time.
685\end{excdesc}
686
687\begin{excdesc}{WantWriteError}
688See \exception{WantReadError}.
689\end{excdesc}
690
691\begin{excdesc}{WantX509LookupError}
692The operation did not complete because an application callback has asked to be
693called again. The I/O method should be called again later, with the same
694arguments. Note: This won't occur in this version, as there are no such
695callbacks in this version.
696\end{excdesc}
697
698\begin{excdesc}{SysCallError}
699The \exception{SysCallError} occurs when there's an I/O error and OpenSSL's
700error queue does not contain any information. This can mean two things: An
701error in the transport protocol, or an end of file that violates the protocol.
702The parameter to the exception is always a pair \code{(\var{errnum},
703\var{errstr})}.
704\end{excdesc}
705
706
707\subsubsection{Context objects \label{openssl-context}}
708
709Context objects have the following methods:
710
711\begin{methoddesc}[Context]{check_privatekey}{}
712Check if the private key (loaded with \method{use_privatekey\optional{_file}})
713matches the certificate (loaded with \method{use_certificate\optional{_file}}).
Jean-Paul Calderonef05fbbe2008-03-06 21:52:35 -0500714Returns \code{None} if they match, raises \exception{Error} otherwise.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500715\end{methoddesc}
716
717\begin{methoddesc}[Context]{get_app_data}{}
718Retrieve application data as set by \method{set_app_data}.
719\end{methoddesc}
720
721\begin{methoddesc}[Context]{get_cert_store}{}
722Retrieve the certificate store (a X509Store object) that the context uses.
723This can be used to add "trusted" certificates without using the.
724\method{load_verify_locations()} method.
725\end{methoddesc}
726
727\begin{methoddesc}[Context]{get_timeout}{}
728Retrieve session timeout, as set by \method{set_timeout}. The default is 300
729seconds.
730\end{methoddesc}
731
732\begin{methoddesc}[Context]{get_verify_depth}{}
733Retrieve the Context object's verify depth, as set by
734\method{set_verify_depth}.
735\end{methoddesc}
736
737\begin{methoddesc}[Context]{get_verify_mode}{}
738Retrieve the Context object's verify mode, as set by \method{set_verify_mode}.
739\end{methoddesc}
740
741\begin{methoddesc}[Context]{load_client_ca}{pemfile}
742Read a file with PEM-formatted certificates that will be sent to the client
743when requesting a client certificate.
744\end{methoddesc}
745
746\begin{methoddesc}[Context]{load_verify_locations}{pemfile}
747Specify where CA certificates for verification purposes are located. These are
748trusted certificates. Note that the certificates have to be in PEM format.
749\end{methoddesc}
750
751\begin{methoddesc}[Context]{load_tmp_dh}{dhfile}
752Load parameters for Ephemeral Diffie-Hellman from \var{dhfile}.
753\end{methoddesc}
754
755\begin{methoddesc}[Context]{set_app_data}{data}
756Associate \var{data} with this Context object. \var{data} can be retrieved
757later using the \method{get_app_data} method.
758\end{methoddesc}
759
760\begin{methoddesc}[Context]{set_cipher_list}{ciphers}
761Set the list of ciphers to be used in this context. See the OpenSSL manual for
762more information (e.g. ciphers(1))
763\end{methoddesc}
764
765\begin{methoddesc}[Context]{set_info_callback}{callback}
766Set the information callback to \var{callback}. This function will be called
767from time to time during SSL handshakes.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500768\var{callback} should take three arguments: a Connection object and two
769integers. The first integer specifies where in the SSL handshake the function
770was called, and the other the return code from a (possibly failed) internal
771function call.
772\end{methoddesc}
773
774\begin{methoddesc}[Context]{set_options}{options}
775Add SSL options. Options you have set before are not cleared!
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500776This method should be used with the \constant{OP_*} constants.
777\end{methoddesc}
778
779\begin{methoddesc}[Context]{set_passwd_cb}{callback\optional{, userdata}}
780Set the passphrase callback to \var{callback}. This function will be called
781when a private key with a passphrase is loaded.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500782\var{callback} should take a boolean argument \var{repeat} and an arbitrary
783argument \var{data} and return the passphrase entered by the user. If
784\var{repeat} is true then \var{callback} should ask for the passphrase twice
785and make sure that the two entries are equal. The \var{data} argument is the
786\var{userdata} variable passed to the \method{set_passwd_cb} method. If an
787error occurs, \var{callback} should return a false value (e.g. an empty
788string).
789\end{methoddesc}
790
791\begin{methoddesc}[Context]{set_session_id}{name}
792Set the context \var{name} within which a session can be reused for this
793Context object. This is needed when doing session resumption, because there is
794no way for a stored session to know which Context object it is associated with.
795\var{name} may be any binary data.
796\end{methoddesc}
797
798\begin{methoddesc}[Context]{set_timeout}{timeout}
799Set the timeout for newly created sessions for this Context object to
800\var{timeout}. \var{timeout} must be given in (whole) seconds. The default
801value is 300 seconds. See the OpenSSL manual for more information (e.g.
802SSL_CTX_set_timeout(3)).
803\end{methoddesc}
804
805\begin{methoddesc}[Context]{set_verify}{mode, callback}
806Set the verification flags for this Context object to \var{mode} and specify
807that \var{callback} should be used for verification callbacks. \var{mode}
808should be one of \constant{VERIFY_NONE} and \constant{VERIFY_PEER}. If
809\constant{VERIFY_PEER} is used, \var{mode} can be OR:ed with
810\constant{VERIFY_FAIL_IF_NO_PEER_CERT} and \constant{VERIFY_CLIENT_ONCE} to
811further control the behaviour.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500812\var{callback} should take five arguments: A Connection object, an X509 object,
813and three integer variables, which are in turn potential error number, error
814depth and return code. \var{callback} should return true if verification passes
815and false otherwise.
816\end{methoddesc}
817
818\begin{methoddesc}[Context]{set_verify_depth}{depth}
819Set the maximum depth for the certificate chain verification that shall be
820allowed for this Context object.
821\end{methoddesc}
822
823\begin{methoddesc}[Context]{use_certificate}{cert}
824Use the certificate \var{cert} which has to be a X509 object.
825\end{methoddesc}
826
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500827\begin{methoddesc}[Context]{add_extra_chain_cert}{cert}
828Adds the certificate \var{cert}, which has to be a X509 object, to the
829certificate chain presented together with the certificate.
830\end{methoddesc}
831
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500832\begin{methoddesc}[Context]{use_certificate_chain_file}{file}
833Load a certificate chain from \var{file} which must be PEM encoded.
834\end{methoddesc}
835
836\begin{methoddesc}[Context]{use_privatekey}{pkey}
837Use the private key \var{pkey} which has to be a PKey object.
838\end{methoddesc}
839
840\begin{methoddesc}[Context]{use_certificate_file}{file\optional{, format}}
841Load the first certificate found in \var{file}. The certificate must be in the
842format specified by \var{format}, which is either \constant{FILETYPE_PEM} or
843\constant{FILETYPE_ASN1}. The default is \constant{FILETYPE_PEM}.
844\end{methoddesc}
845
846\begin{methoddesc}[Context]{use_privatekey_file}{file\optional{, format}}
847Load the first private key found in \var{file}. The private key must be in the
848format specified by \var{format}, which is either \constant{FILETYPE_PEM} or
849\constant{FILETYPE_ASN1}. The default is \constant{FILETYPE_PEM}.
850\end{methoddesc}
851
852
853\subsubsection{Connection objects \label{openssl-connection}}
854
855Connection objects have the following methods:
856
857\begin{methoddesc}[Connection]{accept}{}
858Call the \method{accept} method of the underlying socket and set up SSL on the
859returned socket, using the Context object supplied to this Connection object at
860creation. Returns a pair \code{(\var{conn}, \var{address})}. where \var{conn}
861is the new Connection object created, and \var{address} is as returned by the
862socket's \method{accept}.
863\end{methoddesc}
864
865\begin{methoddesc}[Connection]{bind}{address}
866Call the \method{bind} method of the underlying socket.
867\end{methoddesc}
868
869\begin{methoddesc}[Connection]{close}{}
870Call the \method{close} method of the underlying socket. Note: If you want
871correct SSL closure, you need to call the \method{shutdown} method first.
872\end{methoddesc}
873
874\begin{methoddesc}[Connection]{connect}{address}
875Call the \method{connect} method of the underlying socket and set up SSL on the
876socket, using the Context object supplied to this Connection object at
877creation.
878\end{methoddesc}
879
880\begin{methoddesc}[Connection]{connect_ex}{address}
881Call the \method{connect_ex} method of the underlying socket and set up SSL on
882the socket, using the Context object supplied to this Connection object at
883creation. Note that if the \method{connect_ex} method of the socket doesn't
884return 0, SSL won't be initialized.
885\end{methoddesc}
886
887\begin{methoddesc}[Connection]{do_handshake}{}
888Perform an SSL handshake (usually called after \method{renegotiate} or one of
889\method{set_accept_state} or \method{set_accept_state}). This can raise the
890same exceptions as \method{send} and \method{recv}.
891\end{methoddesc}
892
893\begin{methoddesc}[Connection]{fileno}{}
894Retrieve the file descriptor number for the underlying socket.
895\end{methoddesc}
896
897\begin{methoddesc}[Connection]{listen}{backlog}
898Call the \method{listen} method of the underlying socket.
899\end{methoddesc}
900
901\begin{methoddesc}[Connection]{get_app_data}{}
902Retrieve application data as set by \method{set_app_data}.
903\end{methoddesc}
904
905\begin{methoddesc}[Connection]{get_cipher_list}{}
906Retrieve the list of ciphers used by the Connection object. WARNING: This API
907has changed. It used to take an optional parameter and just return a string,
908but not it returns the entire list in one go.
909\end{methoddesc}
910
911\begin{methoddesc}[Connection]{get_context}{}
912Retrieve the Context object associated with this Connection.
913\end{methoddesc}
914
915\begin{methoddesc}[Connection]{get_peer_certificate}{}
916Retrieve the other side's certificate (if any)
917\end{methoddesc}
918
919\begin{methoddesc}[Connection]{getpeername}{}
920Call the \method{getpeername} method of the underlying socket.
921\end{methoddesc}
922
923\begin{methoddesc}[Connection]{getsockname}{}
924Call the \method{getsockname} method of the underlying socket.
925\end{methoddesc}
926
927\begin{methoddesc}[Connection]{getsockopt}{level, optname\optional{, buflen}}
928Call the \method{getsockopt} method of the underlying socket.
929\end{methoddesc}
930
931\begin{methoddesc}[Connection]{pending}{}
Jean-Paul Calderoneb6f57be2008-03-06 21:22:16 -0500932Retrieve the number of bytes that can be safely read from the SSL buffer
933(\emph{not} the underlying transport buffer).
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500934\end{methoddesc}
935
936\begin{methoddesc}[Connection]{recv}{bufsize}
937Receive data from the Connection. The return value is a string representing the
938data received. The maximum amount of data to be received at once, is specified
939by \var{bufsize}.
940\end{methoddesc}
941
942\begin{methoddesc}[Connection]{renegotiate}{}
943Renegotiate the SSL session. Call this if you wish to change cipher suites or
944anything like that.
945\end{methoddesc}
946
947\begin{methoddesc}[Connection]{send}{string}
948Send the \var{string} data to the Connection.
949\end{methoddesc}
950
951\begin{methoddesc}[Connection]{sendall}{string}
952Send all of the \var{string} data to the Connection. This calls \method{send}
953repeatedly until all data is sent. If an error occurs, it's impossible to tell
954how much data has been sent.
955\end{methoddesc}
956
957\begin{methoddesc}[Connection]{set_accept_state}{}
958Set the connection to work in server mode. The handshake will be handled
959automatically by read/write.
960\end{methoddesc}
961
962\begin{methoddesc}[Connection]{set_app_data}{data}
963Associate \var{data} with this Connection object. \var{data} can be retrieved
964later using the \method{get_app_data} method.
965\end{methoddesc}
966
967\begin{methoddesc}[Connection]{set_connect_state}{}
968Set the connection to work in client mode. The handshake will be handled
969automatically by read/write.
970\end{methoddesc}
971
972\begin{methoddesc}[Connection]{setblocking}{flag}
973Call the \method{setblocking} method of the underlying socket.
974\end{methoddesc}
975
976\begin{methoddesc}[Connection]{setsockopt}{level, optname, value}
977Call the \method{setsockopt} method of the underlying socket.
978\end{methoddesc}
979
980\begin{methoddesc}[Connection]{shutdown}{}
981Send the shutdown message to the Connection. Returns true if the shutdown
982message exchange is completed and false otherwise (in which case you call
983\method{recv()} or \method{send()} when the connection becomes
984readable/writeable.
985\end{methoddesc}
986
Jean-Paul Calderone72b8f0f2008-02-21 23:57:40 -0500987\begin{methoddesc}[Connection]{get_shutdown}{}
988Get the shutdown state of the Connection. Returns a bitvector of either or
989both of \var{SENT_SHUTDOWN} and \var{RECEIVED_SHUTDOWN}.
990\end{methoddesc}
991
992\begin{methoddesc}[Connection]{set_shutdown}{state}
993Set the shutdown state of the Connection. \var{state} is a bitvector of
994either or both of \var{SENT_SHUTDOWN} and \var{RECEIVED_SHUTDOWN}.
995\end{methoddesc}
996
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500997\begin{methoddesc}[Connection]{sock_shutdown}{how}
998Call the \method{shutdown} method of the underlying socket.
999\end{methoddesc}
1000
1001\begin{methoddesc}[Connection]{state_string}{}
1002Retrieve a verbose string detailing the state of the Connection.
1003\end{methoddesc}
1004
1005\begin{methoddesc}[Connection]{want_read}{}
1006Checks if more data has to be read from the transport layer to complete an
1007operation.
1008\end{methoddesc}
1009
1010\begin{methoddesc}[Connection]{want_write}{}
1011Checks if there is data to write to the transport layer to complete an
1012operation.
1013\end{methoddesc}
1014
1015
1016
1017\section{Internals \label{internals}}
1018
1019We ran into three main problems developing this: Exceptions, callbacks and
1020accessing socket methods. This is what this chapter is about.
1021
1022\subsection{Exceptions \label{exceptions}}
1023
1024We realized early that most of the exceptions would be raised by the I/O
1025functions of OpenSSL, so it felt natural to mimic OpenSSL's error code system,
1026translating them into Python exceptions. This naturally gives us the exceptions
1027\exception{SSL.ZeroReturnError}, \exception{SSL.WantReadError},
1028\exception{SSL.WantWriteError}, \exception{SSL.WantX509LookupError} and
1029\exception{SSL.SysCallError}.
1030
1031For more information about this, see section \ref{openssl-ssl}.
1032
1033
1034\subsection{Callbacks \label{callbacks}}
1035
1036There are a number of problems with callbacks. First of all, OpenSSL is written
1037as a C library, it's not meant to have Python callbacks, so a way around that
1038is needed. Another problem is thread support. A lot of the OpenSSL I/O
1039functions can block if the socket is in blocking mode, and then you want other
1040Python threads to be able to do other things. The real trouble is if you've
1041released the thread lock to do a potentially blocking operation, and the
1042operation calls a callback. Then we must take the thread lock back\footnote{I'm
1043not sure why this is necessary, but otherwise I get a segmentation violation on
1044\cfunction{PyEval_CallObject}}.
1045
1046There are two solutions to the first problem, both of which are necessary. The
1047first solution to use is if the C callback allows ''userdata'' to be passed to
1048it (an arbitrary pointer normally). This is great! We can set our Python
1049function object as the real userdata and emulate userdata for the Python
1050function in another way. The other solution can be used if an object with an
1051''app_data'' system always is passed to the callback. For example, the SSL
1052object in OpenSSL has app_data functions and in e.g. the verification
1053callbacks, you can retrieve the related SSL object. What we do is to set our
1054wrapper \class{Connection} object as app_data for the SSL object, and we can
1055easily find the Python callback.
1056
1057The other problem is also partially solved by app_data. Since we're associating
1058our wrapper objects with the ''real'' objects, we can easily access data from
1059the \class{Connection} object. The solution then is to simply include a
1060\ctype{PyThreadState} variable in the \class{Connection} declaration, and write
1061macros similar to \cfunction{Py_BEGIN_ALLOW_THREADS} and
1062\cfunction{Py_END_ALLOW_THREADS} that allows specifying of the
1063\ctype{PyThreadState} variable to use. Now we can simply ''begin allow
1064threads'' before a potentially blocking operation, and ''end allow threads''
1065before calling a callback.
1066
1067
1068\subsection{Acessing Socket Methods \label{socket-methods}}
1069
1070We quickly saw the benefit of wrapping socket methods in the
1071\class{SSL.Connection} class, for an easy transition into using SSL. The
1072problem here is that the \module{socket} module lacks a C API, and all the
1073methods are declared static. One approach would be to have \module{OpenSSL} as
1074a submodule to the \module{socket} module, placing all the code in
1075\file{socketmodule.c}, but this is obviously not a good solution, since you
1076might not want to import tonnes of extra stuff you're not going to use when
1077importing the \module{socket} module. The other approach is to somehow get a
1078pointer to the method to be called, either the C function, or a callable Python
1079object. This is not really a good solution either, since there's a lot of
1080lookups involved.
1081
1082The way it works is that you have to supply a ``\class{socket}-like'' transport
1083object to the \class{SSL.Connection}. The only requirement of this object is
1084that it has a \method{fileno()} method that returns a file descriptor that's
1085valid at the C level (i.e. you can use the system calls read and write). If you
1086want to use the \method{connect()} or \method{accept()} methods of the
1087\class{SSL.Connection} object, the transport object has to supply such
1088methods too. Apart from them, any method lookups in the \class{SSL.Connection}
1089object that fail are passed on to the underlying transport object.
1090
1091Future changes might be to allow Python-level transport objects, that instead
1092of having \method{fileno()} methods, have \method{read()} and \method{write()}
1093methods, so more advanced features of Python can be used. This would probably
1094entail some sort of OpenSSL ``BIOs'', but converting Python strings back and
1095forth is expensive, so this shouldn't be used unless necessary. Other nice
1096things would be to be able to pass in different transport objects for reading
1097and writing, but then the \method{fileno()} method of \class{SSL.Connection}
1098becomes virtually useless. Also, should the method resolution be used on the
1099read-transport or the write-transport?
1100
1101
1102\end{document}