blob: de9154502e6df66f6584655adeef29be9e28fd9a [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}{}
273Return a \em{borrowed reference} to a X509Name object representing the issuer
274of the certificate. When the corresponding X509 or X509Req object is
275destroyed, this object will be invalid!
276\end{methoddesc}
277
278\begin{methoddesc}[X509]{get_pubkey}{}
279Return a PKey object representing the public key of the certificate.
280\end{methoddesc}
281
282\begin{methoddesc}[X509]{get_serial_number}{}
283Return the certificate serial number.
284\end{methoddesc}
285
286\begin{methoddesc}[X509]{get_subject}{}
287Return a \em{borrowed reference} to a X509Name object representing the subject
288of the certificate. When the corresponding X509 or X509Req object is
289destroyed, this object will be invalid!
290\end{methoddesc}
291
292\begin{methoddesc}[X509]{get_version}{}
293Return the certificate version.
294\end{methoddesc}
295
296\begin{methoddesc}[X509]{gmtime_adj_notBefore}{time}
297Adjust the timestamp (in GMT) when the certificate starts being valid.
298\end{methoddesc}
299
300\begin{methoddesc}[X509]{gmtime_adj_notAfter}{time}
301Adjust the timestamp (in GMT) when the certificate stops being valid.
302\end{methoddesc}
303
304\begin{methoddesc}[X509]{has_expired}{}
305Checks the certificate's time stamp against current time. Returns true if the
306certificate has expired and false otherwise.
307\end{methoddesc}
308
309\begin{methoddesc}[X509]{set_issuer}{issuer}
310Set the issuer of the certificate to \var{issuer}.
311\end{methoddesc}
312
313\begin{methoddesc}[X509]{set_pubkey}{pkey}
314Set the public key of the certificate to \var{pkey}.
315\end{methoddesc}
316
317\begin{methoddesc}[X509]{set_serial_number}{serialno}
318Set the serial number of the certificate to \var{serialno}.
319\end{methoddesc}
320
321\begin{methoddesc}[X509]{set_subject}{subject}
322Set the subject of the certificate to \var{subject}.
323\end{methoddesc}
324
325\begin{methoddesc}[X509]{set_version}{version}
326Set the certificate version to \var{version}.
327\end{methoddesc}
328
329\begin{methoddesc}[X509]{sign}{pkey, digest}
330Sign the certificate, using the key \var{pkey} and the message digest algorithm
331identified by the string \var{digest}.
332\end{methoddesc}
333
334\begin{methoddesc}[X509]{subject_name_hash}{}
335Return the hash of the certificate subject.
336\end{methoddesc}
337
338\begin{methoddesc}[X509]{digest}{digest_name}
339Return a digest of the certificate, using the \var{digest_name} method.
340\end{methoddesc}
341
342\begin{methoddesc}[X509]{add_extensions}{extensions}
343Add the extensions in the sequence \var{extensions} to the certificate.
344\end{methoddesc}
345
346\subsubsection{X509Name objects \label{openssl-x509name}}
347
348X509Name objects have the following members:
349
350\begin{memberdesc}[X509Name]{countryName}
351The country of the entity. \code{C} may be used as an alias for
352\code{countryName}.
353\end{memberdesc}
354
355\begin{memberdesc}[X509Name]{stateOrProvinceName}
356The state or province of the entity. \code{ST} may be used as an alias for
357\code{stateOrProvinceName}·
358\end{memberdesc}
359
360\begin{memberdesc}[X509Name]{localityName}
361The locality of the entity. \code{L} may be used as an alias for
362\code{localityName}.
363\end{memberdesc}
364
365\begin{memberdesc}[X509Name]{organizationName}
366The organization name of the entity. \code{O} may be used as an alias for
367\code{organizationName}.
368\end{memberdesc}
369
370\begin{memberdesc}[X509Name]{organizationalUnitName}
371The organizational unit of the entity. \code{OU} may be used as an alias for
372\code{organizationalUnitName}.
373\end{memberdesc}
374
375\begin{memberdesc}[X509Name]{commonName}
376The common name of the entity. \code{CN} may be used as an alias for
377\code{commonName}.
378\end{memberdesc}
379
380\begin{memberdesc}[X509Name]{emailAddress}
381The e-mail address of the entity.
382\end{memberdesc}
383
384\subsubsection{X509Req objects \label{openssl-x509req}}
385
386X509Req objects have the following methods:
387
388\begin{methoddesc}[X509Req]{get_pubkey}{}
389Return a PKey object representing the public key of the certificate request.
390\end{methoddesc}
391
392\begin{methoddesc}[X509Req]{get_subject}{}
393Return a \em{borrowed reference} to a X509Name object representing the subject
394of the certificate. When the corresponding X509 or X509Req object is
395destroyed, this object will be invalid!
396\end{methoddesc}
397
398\begin{methoddesc}[X509Req]{set_pubkey}{pkey}
399Set the public key of the certificate request to \var{pkey}.
400\end{methoddesc}
401
402\begin{methoddesc}[X509Req]{sign}{pkey, digest}
403Sign the certificate request, using the key \var{pkey} and the message digest
404algorithm identified by the string \var{digest}.
405\end{methoddesc}
406
407\begin{methoddesc}[X509Req]{verify}{pkey}
408Verify a certificate request using the public key \var{pkey}.
409\end{methoddesc}
410
411\subsubsection{X509Store objects \label{openssl-x509store}}
412
413The X509Store object has currently just one method:
414
415\begin{methoddesc}[X509Store]{add_cert}{cert}
416Add the certificate \var{cert} to the certificate store.
417\end{methoddesc}
418
419\subsubsection{PKey objects \label{openssl-pkey}}
420
421The PKey object has the following methods:
422
423\begin{methoddesc}[PKey]{bits}{}
424Return the number of bits of the key.
425\end{methoddesc}
426
427\begin{methoddesc}[PKey]{generate_key}{type, bits}
428Generate a public/private key pair of the type \var{type} (one of
429\constant{TYPE_RSA} and \constant{TYPE_DSA}) with the size \var{bits}.
430\end{methoddesc}
431
432\begin{methoddesc}[PKey]{type}{}
433Return the type of the key.
434\end{methoddesc}
435
436\subsubsection{PKCS7 objects \label{openssl-pkcs7}}
437
438PKCS7 objects have the following methods:
439
440\begin{methoddesc}[PKCS7]{type_is_signed}{}
441FIXME
442\end{methoddesc}
443
444\begin{methoddesc}[PKCS7]{type_is_enveloped}{}
445FIXME
446\end{methoddesc}
447
448\begin{methoddesc}[PKCS7]{type_is_signedAndEnveloped}{}
449FIXME
450\end{methoddesc}
451
452\begin{methoddesc}[PKCS7]{type_is_data}{}
453FIXME
454\end{methoddesc}
455
456\begin{methoddesc}[PKCS7]{get_type_name}{}
457Get the type name of the PKCS7.
458\end{methoddesc}
459
460\subsubsection{PKCS12 objects \label{openssl-pkcs12}}
461
462PKCS12 objects have the following methods:
463
464\begin{methoddesc}[PKCS12]{get_certificate}{}
465Return certificate portion of the PKCS12 structure.
466\end{methoddesc}
467
468\begin{methoddesc}[PKCS12]{get_privatekey}{}
469Return private key portion of the PKCS12 structure
470\end{methoddesc}
471
472\begin{methoddesc}[PKCS12]{get_ca_certificates}{}
473Return CA certificates within the PKCS12 object as a tuple. Returns
474None if no CA certificates are present.
475\end{methoddesc}
476
477\subsubsection{X509Extension objects \label{openssl-509ext}}
478
479X509Extension objects currently only have one method:
480
481\begin{methoddesc}[X509Extension]{get_critical}{}
482Return the critical field of the extension object.
483\end{methoddesc}
484
485\subsubsection{NetscapeSPKI objects \label{openssl-netscape-spki}}
486
487NetscapeSPKI objects have the following methods:
488
489\begin{methoddesc}[NetscapeSPKI]{b64_encode}{}
490Return a base64-encoded string representation of the object.
491\end{methoddesc}
492
493\begin{methoddesc}[NetscapeSPKI]{get_pubkey}{}
494Return the public key of object.
495\end{methoddesc}
496
497\begin{methoddesc}[NetscapeSPKI]{set_pubkey}{key}
498Set the public key of the object to \var{key}.
499\end{methoddesc}
500
501\begin{methoddesc}[NetscapeSPKI]{sign}{key, digest_name}
502Sign the NetscapeSPKI object using the given \var{key} and \var{digest_name}.
503\end{methoddesc}
504
505\begin{methoddesc}[NetscapeSPKI]{verify}{key}
506Verify the NetscapeSPKI object using the given \var{key}.
507\end{methoddesc}
508
509
510% % % rand module
511
512\subsection{\module{rand} --- An interface to the OpenSSL pseudo random number generator \label{openssl-rand}}
513
514\declaremodule{extension}{rand}
515\modulesynopsis{An interface to the OpenSSL pseudo random number generator}
516
517This module handles the OpenSSL pseudo random number generator (PRNG) and
518declares the following:
519
520\begin{funcdesc}{add}{string, entropy}
521Mix bytes from \var{string} into the PRNG state. The \var{entropy} argument is
522(the lower bound of) an estimate of how much randomness is contained in
523\var{string}, measured in bytes. For more information, see e.g. \rfc{1750}.
524\end{funcdesc}
525
526\begin{funcdesc}{egd}{path\optional{, bytes}}
527Query the Entropy Gathering Daemon\footnote{See
528\url{http://www.lothar.com/tech/crypto/}} on socket \var{path} for \var{bytes}
529bytes of random data and and uses \function{add} to seed the PRNG. The default
530value of \var{bytes} is 255.
531\end{funcdesc}
532
533\begin{funcdesc}{load_file}{path\optional{, bytes}}
534Read \var{bytes} bytes (or all of it, if \var{bytes} is negative) of data from
535the file \var{path} to seed the PRNG. The default value of \var{bytes} is -1.
536\end{funcdesc}
537
538\begin{funcdesc}{screen}{}
539Add the current contents of the screen to the PRNG state.
540Availability: Windows.
541\end{funcdesc}
542
543\begin{funcdesc}{seed}{string}
544This is equivalent to calling \function{add} with \var{entropy} as the length
545of the string.
546\end{funcdesc}
547
548\begin{funcdesc}{status}{}
549Returns true if the PRNG has been seeded with enough data, and false otherwise.
550\end{funcdesc}
551
552\begin{funcdesc}{write_file}{path}
553Write a number of random bytes (currently 1024) to the file \var{path}. This
554file can then be used with \function{load_file} to seed the PRNG again.
555\end{funcdesc}
556
557
558
559% % % SSL module
560
561\subsection{\module{SSL} --- An interface to the SSL-specific parts of OpenSSL \label{openssl-ssl}}
562
563\declaremodule{extension}{SSL}
564\modulesynopsis{An interface to the SSL-specific parts of OpenSSL}
565
566This module handles things specific to SSL. There are two objects defined:
567Context, Connection.
568
569\begin{datadesc}{SSLv2_METHOD}
570\dataline{SSLv3_METHOD}
571\dataline{SSLv23_METHOD}
572\dataline{TLSv1_METHOD}
573These constants represent the different SSL methods to use when creating a
574context object.
575\end{datadesc}
576
577\begin{datadesc}{VERIFY_NONE}
578\dataline{VERIFY_PEER}
579\dataline{VERIFY_FAIL_IF_NO_PEER_CERT}
580These constants represent the verification mode used by the Context
581object's \method{set_verify} method.
582\end{datadesc}
583
584\begin{datadesc}{FILETYPE_PEM}
585\dataline{FILETYPE_ASN1}
586File type constants used with the \method{use_certificate_file} and
587\method{use_privatekey_file} methods of Context objects.
588\end{datadesc}
589
590\begin{datadesc}{OP_SINGLE_DH_USE}
591\dataline{OP_EPHEMERAL_RSA}
592\dataline{OP_NO_SSLv2}
593\dataline{OP_NO_SSLv3}
594\dataline{OP_NO_TLSv1}
595Constants used with \method{set_options} of Context objects.
596\constant{OP_SINGLE_DH_USE} means to always create a new key when using ephemeral
597Diffie-Hellman. \constant{OP_EPHEMERAL_RSA} means to always use ephemeral RSA keys
598when doing RSA operations. \constant{OP_NO_SSLv2}, \constant{OP_NO_SSLv3} and
599\constant{OP_NO_TLSv1} means to disable those specific protocols. This is
600interesting if you're using e.g. \constant{SSLv23_METHOD} to get an SSLv2-compatible
601handshake, but don't want to use SSLv2.
602\end{datadesc}
603
604\begin{datadesc}{ContextType}
605A Python type object representing the Context object type.
606\end{datadesc}
607
608\begin{funcdesc}{Context}{method}
609Factory function that creates a new Context object given an SSL method. The
610method should be \constant{SSLv2_METHOD}, \constant{SSLv3_METHOD},
611\constant{SSLv23_METHOD} or \constant{TLSv1_METHOD}.
612\end{funcdesc}
613
614\begin{datadesc}{ConnectionType}
615A Python type object representing the Connection object type.
616\end{datadesc}
617
618\begin{funcdesc}{Connection}{context, socket}
619Factory fucnction that creates a new Connection object given an SSL context and
620a socket \footnote{Actually, all that is required is an object that
621\emph{behaves} like a socket, you could even use files, even though it'd be
622tricky to get the handshakes right!} object.
623\end{funcdesc}
624
625\begin{excdesc}{Error}
626This exception is used as a base class for the other SSL-related
627exceptions, but may also be raised directly.
628
629Whenever this exception is raised directly, it has a list of error messages
630from the OpenSSL error queue, where each item is a tuple \code{(\var{lib},
631\var{function}, \var{reason})}. Here \var{lib}, \var{function} and \var{reason}
632are all strings, describing where and what the problem is. See \manpage{err}{3}
633for more information.
634\end{excdesc}
635
636\begin{excdesc}{ZeroReturnError}
637This exception matches the error return code \code{SSL_ERROR_ZERO_RETURN}, and
638is raised when the SSL Connection has been closed. In SSL 3.0 and TLS 1.0, this
639only occurs if a closure alert has occurred in the protocol, i.e. the
640connection has been closed cleanly. Note that this does not necessarily
641mean that the transport layer (e.g. a socket) has been closed.
642
643It may seem a little strange that this is an exception, but it does match an
644\code{SSL_ERROR} code, and is very convenient.
645\end{excdesc}
646
647\begin{excdesc}{WantReadError}
648The operation did not complete; the same I/O method should be called again
649later, with the same arguments. Any I/O method can lead to this since new
650handshakes can occur at any time.
651\end{excdesc}
652
653\begin{excdesc}{WantWriteError}
654See \exception{WantReadError}.
655\end{excdesc}
656
657\begin{excdesc}{WantX509LookupError}
658The operation did not complete because an application callback has asked to be
659called again. The I/O method should be called again later, with the same
660arguments. Note: This won't occur in this version, as there are no such
661callbacks in this version.
662\end{excdesc}
663
664\begin{excdesc}{SysCallError}
665The \exception{SysCallError} occurs when there's an I/O error and OpenSSL's
666error queue does not contain any information. This can mean two things: An
667error in the transport protocol, or an end of file that violates the protocol.
668The parameter to the exception is always a pair \code{(\var{errnum},
669\var{errstr})}.
670\end{excdesc}
671
672
673\subsubsection{Context objects \label{openssl-context}}
674
675Context objects have the following methods:
676
677\begin{methoddesc}[Context]{check_privatekey}{}
678Check if the private key (loaded with \method{use_privatekey\optional{_file}})
679matches the certificate (loaded with \method{use_certificate\optional{_file}}).
680Returns true if they match, false otherwise.
681\end{methoddesc}
682
683\begin{methoddesc}[Context]{get_app_data}{}
684Retrieve application data as set by \method{set_app_data}.
685\end{methoddesc}
686
687\begin{methoddesc}[Context]{get_cert_store}{}
688Retrieve the certificate store (a X509Store object) that the context uses.
689This can be used to add "trusted" certificates without using the.
690\method{load_verify_locations()} method.
691\end{methoddesc}
692
693\begin{methoddesc}[Context]{get_timeout}{}
694Retrieve session timeout, as set by \method{set_timeout}. The default is 300
695seconds.
696\end{methoddesc}
697
698\begin{methoddesc}[Context]{get_verify_depth}{}
699Retrieve the Context object's verify depth, as set by
700\method{set_verify_depth}.
701\end{methoddesc}
702
703\begin{methoddesc}[Context]{get_verify_mode}{}
704Retrieve the Context object's verify mode, as set by \method{set_verify_mode}.
705\end{methoddesc}
706
707\begin{methoddesc}[Context]{load_client_ca}{pemfile}
708Read a file with PEM-formatted certificates that will be sent to the client
709when requesting a client certificate.
710\end{methoddesc}
711
712\begin{methoddesc}[Context]{load_verify_locations}{pemfile}
713Specify where CA certificates for verification purposes are located. These are
714trusted certificates. Note that the certificates have to be in PEM format.
715\end{methoddesc}
716
717\begin{methoddesc}[Context]{load_tmp_dh}{dhfile}
718Load parameters for Ephemeral Diffie-Hellman from \var{dhfile}.
719\end{methoddesc}
720
721\begin{methoddesc}[Context]{set_app_data}{data}
722Associate \var{data} with this Context object. \var{data} can be retrieved
723later using the \method{get_app_data} method.
724\end{methoddesc}
725
726\begin{methoddesc}[Context]{set_cipher_list}{ciphers}
727Set the list of ciphers to be used in this context. See the OpenSSL manual for
728more information (e.g. ciphers(1))
729\end{methoddesc}
730
731\begin{methoddesc}[Context]{set_info_callback}{callback}
732Set the information callback to \var{callback}. This function will be called
733from time to time during SSL handshakes.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500734\var{callback} should take three arguments: a Connection object and two
735integers. The first integer specifies where in the SSL handshake the function
736was called, and the other the return code from a (possibly failed) internal
737function call.
738\end{methoddesc}
739
740\begin{methoddesc}[Context]{set_options}{options}
741Add SSL options. Options you have set before are not cleared!
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500742This method should be used with the \constant{OP_*} constants.
743\end{methoddesc}
744
745\begin{methoddesc}[Context]{set_passwd_cb}{callback\optional{, userdata}}
746Set the passphrase callback to \var{callback}. This function will be called
747when a private key with a passphrase is loaded.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500748\var{callback} should take a boolean argument \var{repeat} and an arbitrary
749argument \var{data} and return the passphrase entered by the user. If
750\var{repeat} is true then \var{callback} should ask for the passphrase twice
751and make sure that the two entries are equal. The \var{data} argument is the
752\var{userdata} variable passed to the \method{set_passwd_cb} method. If an
753error occurs, \var{callback} should return a false value (e.g. an empty
754string).
755\end{methoddesc}
756
757\begin{methoddesc}[Context]{set_session_id}{name}
758Set the context \var{name} within which a session can be reused for this
759Context object. This is needed when doing session resumption, because there is
760no way for a stored session to know which Context object it is associated with.
761\var{name} may be any binary data.
762\end{methoddesc}
763
764\begin{methoddesc}[Context]{set_timeout}{timeout}
765Set the timeout for newly created sessions for this Context object to
766\var{timeout}. \var{timeout} must be given in (whole) seconds. The default
767value is 300 seconds. See the OpenSSL manual for more information (e.g.
768SSL_CTX_set_timeout(3)).
769\end{methoddesc}
770
771\begin{methoddesc}[Context]{set_verify}{mode, callback}
772Set the verification flags for this Context object to \var{mode} and specify
773that \var{callback} should be used for verification callbacks. \var{mode}
774should be one of \constant{VERIFY_NONE} and \constant{VERIFY_PEER}. If
775\constant{VERIFY_PEER} is used, \var{mode} can be OR:ed with
776\constant{VERIFY_FAIL_IF_NO_PEER_CERT} and \constant{VERIFY_CLIENT_ONCE} to
777further control the behaviour.
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500778\var{callback} should take five arguments: A Connection object, an X509 object,
779and three integer variables, which are in turn potential error number, error
780depth and return code. \var{callback} should return true if verification passes
781and false otherwise.
782\end{methoddesc}
783
784\begin{methoddesc}[Context]{set_verify_depth}{depth}
785Set the maximum depth for the certificate chain verification that shall be
786allowed for this Context object.
787\end{methoddesc}
788
789\begin{methoddesc}[Context]{use_certificate}{cert}
790Use the certificate \var{cert} which has to be a X509 object.
791\end{methoddesc}
792
Jean-Paul Calderone87b40602008-02-19 21:13:25 -0500793\begin{methoddesc}[Context]{add_extra_chain_cert}{cert}
794Adds the certificate \var{cert}, which has to be a X509 object, to the
795certificate chain presented together with the certificate.
796\end{methoddesc}
797
Jean-Paul Calderone897bc252008-02-18 20:50:23 -0500798\begin{methoddesc}[Context]{use_certificate_chain_file}{file}
799Load a certificate chain from \var{file} which must be PEM encoded.
800\end{methoddesc}
801
802\begin{methoddesc}[Context]{use_privatekey}{pkey}
803Use the private key \var{pkey} which has to be a PKey object.
804\end{methoddesc}
805
806\begin{methoddesc}[Context]{use_certificate_file}{file\optional{, format}}
807Load the first certificate found in \var{file}. The certificate must be in the
808format specified by \var{format}, which is either \constant{FILETYPE_PEM} or
809\constant{FILETYPE_ASN1}. The default is \constant{FILETYPE_PEM}.
810\end{methoddesc}
811
812\begin{methoddesc}[Context]{use_privatekey_file}{file\optional{, format}}
813Load the first private key found in \var{file}. The private key must be in the
814format specified by \var{format}, which is either \constant{FILETYPE_PEM} or
815\constant{FILETYPE_ASN1}. The default is \constant{FILETYPE_PEM}.
816\end{methoddesc}
817
818
819\subsubsection{Connection objects \label{openssl-connection}}
820
821Connection objects have the following methods:
822
823\begin{methoddesc}[Connection]{accept}{}
824Call the \method{accept} method of the underlying socket and set up SSL on the
825returned socket, using the Context object supplied to this Connection object at
826creation. Returns a pair \code{(\var{conn}, \var{address})}. where \var{conn}
827is the new Connection object created, and \var{address} is as returned by the
828socket's \method{accept}.
829\end{methoddesc}
830
831\begin{methoddesc}[Connection]{bind}{address}
832Call the \method{bind} method of the underlying socket.
833\end{methoddesc}
834
835\begin{methoddesc}[Connection]{close}{}
836Call the \method{close} method of the underlying socket. Note: If you want
837correct SSL closure, you need to call the \method{shutdown} method first.
838\end{methoddesc}
839
840\begin{methoddesc}[Connection]{connect}{address}
841Call the \method{connect} method of the underlying socket and set up SSL on the
842socket, using the Context object supplied to this Connection object at
843creation.
844\end{methoddesc}
845
846\begin{methoddesc}[Connection]{connect_ex}{address}
847Call the \method{connect_ex} method of the underlying socket and set up SSL on
848the socket, using the Context object supplied to this Connection object at
849creation. Note that if the \method{connect_ex} method of the socket doesn't
850return 0, SSL won't be initialized.
851\end{methoddesc}
852
853\begin{methoddesc}[Connection]{do_handshake}{}
854Perform an SSL handshake (usually called after \method{renegotiate} or one of
855\method{set_accept_state} or \method{set_accept_state}). This can raise the
856same exceptions as \method{send} and \method{recv}.
857\end{methoddesc}
858
859\begin{methoddesc}[Connection]{fileno}{}
860Retrieve the file descriptor number for the underlying socket.
861\end{methoddesc}
862
863\begin{methoddesc}[Connection]{listen}{backlog}
864Call the \method{listen} method of the underlying socket.
865\end{methoddesc}
866
867\begin{methoddesc}[Connection]{get_app_data}{}
868Retrieve application data as set by \method{set_app_data}.
869\end{methoddesc}
870
871\begin{methoddesc}[Connection]{get_cipher_list}{}
872Retrieve the list of ciphers used by the Connection object. WARNING: This API
873has changed. It used to take an optional parameter and just return a string,
874but not it returns the entire list in one go.
875\end{methoddesc}
876
877\begin{methoddesc}[Connection]{get_context}{}
878Retrieve the Context object associated with this Connection.
879\end{methoddesc}
880
881\begin{methoddesc}[Connection]{get_peer_certificate}{}
882Retrieve the other side's certificate (if any)
883\end{methoddesc}
884
885\begin{methoddesc}[Connection]{getpeername}{}
886Call the \method{getpeername} method of the underlying socket.
887\end{methoddesc}
888
889\begin{methoddesc}[Connection]{getsockname}{}
890Call the \method{getsockname} method of the underlying socket.
891\end{methoddesc}
892
893\begin{methoddesc}[Connection]{getsockopt}{level, optname\optional{, buflen}}
894Call the \method{getsockopt} method of the underlying socket.
895\end{methoddesc}
896
897\begin{methoddesc}[Connection]{pending}{}
898Retrieve the number of bytes that can be safely read from the SSL buffer.
899\end{methoddesc}
900
901\begin{methoddesc}[Connection]{recv}{bufsize}
902Receive data from the Connection. The return value is a string representing the
903data received. The maximum amount of data to be received at once, is specified
904by \var{bufsize}.
905\end{methoddesc}
906
907\begin{methoddesc}[Connection]{renegotiate}{}
908Renegotiate the SSL session. Call this if you wish to change cipher suites or
909anything like that.
910\end{methoddesc}
911
912\begin{methoddesc}[Connection]{send}{string}
913Send the \var{string} data to the Connection.
914\end{methoddesc}
915
916\begin{methoddesc}[Connection]{sendall}{string}
917Send all of the \var{string} data to the Connection. This calls \method{send}
918repeatedly until all data is sent. If an error occurs, it's impossible to tell
919how much data has been sent.
920\end{methoddesc}
921
922\begin{methoddesc}[Connection]{set_accept_state}{}
923Set the connection to work in server mode. The handshake will be handled
924automatically by read/write.
925\end{methoddesc}
926
927\begin{methoddesc}[Connection]{set_app_data}{data}
928Associate \var{data} with this Connection object. \var{data} can be retrieved
929later using the \method{get_app_data} method.
930\end{methoddesc}
931
932\begin{methoddesc}[Connection]{set_connect_state}{}
933Set the connection to work in client mode. The handshake will be handled
934automatically by read/write.
935\end{methoddesc}
936
937\begin{methoddesc}[Connection]{setblocking}{flag}
938Call the \method{setblocking} method of the underlying socket.
939\end{methoddesc}
940
941\begin{methoddesc}[Connection]{setsockopt}{level, optname, value}
942Call the \method{setsockopt} method of the underlying socket.
943\end{methoddesc}
944
945\begin{methoddesc}[Connection]{shutdown}{}
946Send the shutdown message to the Connection. Returns true if the shutdown
947message exchange is completed and false otherwise (in which case you call
948\method{recv()} or \method{send()} when the connection becomes
949readable/writeable.
950\end{methoddesc}
951
952\begin{methoddesc}[Connection]{sock_shutdown}{how}
953Call the \method{shutdown} method of the underlying socket.
954\end{methoddesc}
955
956\begin{methoddesc}[Connection]{state_string}{}
957Retrieve a verbose string detailing the state of the Connection.
958\end{methoddesc}
959
960\begin{methoddesc}[Connection]{want_read}{}
961Checks if more data has to be read from the transport layer to complete an
962operation.
963\end{methoddesc}
964
965\begin{methoddesc}[Connection]{want_write}{}
966Checks if there is data to write to the transport layer to complete an
967operation.
968\end{methoddesc}
969
970
971
972\section{Internals \label{internals}}
973
974We ran into three main problems developing this: Exceptions, callbacks and
975accessing socket methods. This is what this chapter is about.
976
977\subsection{Exceptions \label{exceptions}}
978
979We realized early that most of the exceptions would be raised by the I/O
980functions of OpenSSL, so it felt natural to mimic OpenSSL's error code system,
981translating them into Python exceptions. This naturally gives us the exceptions
982\exception{SSL.ZeroReturnError}, \exception{SSL.WantReadError},
983\exception{SSL.WantWriteError}, \exception{SSL.WantX509LookupError} and
984\exception{SSL.SysCallError}.
985
986For more information about this, see section \ref{openssl-ssl}.
987
988
989\subsection{Callbacks \label{callbacks}}
990
991There are a number of problems with callbacks. First of all, OpenSSL is written
992as a C library, it's not meant to have Python callbacks, so a way around that
993is needed. Another problem is thread support. A lot of the OpenSSL I/O
994functions can block if the socket is in blocking mode, and then you want other
995Python threads to be able to do other things. The real trouble is if you've
996released the thread lock to do a potentially blocking operation, and the
997operation calls a callback. Then we must take the thread lock back\footnote{I'm
998not sure why this is necessary, but otherwise I get a segmentation violation on
999\cfunction{PyEval_CallObject}}.
1000
1001There are two solutions to the first problem, both of which are necessary. The
1002first solution to use is if the C callback allows ''userdata'' to be passed to
1003it (an arbitrary pointer normally). This is great! We can set our Python
1004function object as the real userdata and emulate userdata for the Python
1005function in another way. The other solution can be used if an object with an
1006''app_data'' system always is passed to the callback. For example, the SSL
1007object in OpenSSL has app_data functions and in e.g. the verification
1008callbacks, you can retrieve the related SSL object. What we do is to set our
1009wrapper \class{Connection} object as app_data for the SSL object, and we can
1010easily find the Python callback.
1011
1012The other problem is also partially solved by app_data. Since we're associating
1013our wrapper objects with the ''real'' objects, we can easily access data from
1014the \class{Connection} object. The solution then is to simply include a
1015\ctype{PyThreadState} variable in the \class{Connection} declaration, and write
1016macros similar to \cfunction{Py_BEGIN_ALLOW_THREADS} and
1017\cfunction{Py_END_ALLOW_THREADS} that allows specifying of the
1018\ctype{PyThreadState} variable to use. Now we can simply ''begin allow
1019threads'' before a potentially blocking operation, and ''end allow threads''
1020before calling a callback.
1021
1022
1023\subsection{Acessing Socket Methods \label{socket-methods}}
1024
1025We quickly saw the benefit of wrapping socket methods in the
1026\class{SSL.Connection} class, for an easy transition into using SSL. The
1027problem here is that the \module{socket} module lacks a C API, and all the
1028methods are declared static. One approach would be to have \module{OpenSSL} as
1029a submodule to the \module{socket} module, placing all the code in
1030\file{socketmodule.c}, but this is obviously not a good solution, since you
1031might not want to import tonnes of extra stuff you're not going to use when
1032importing the \module{socket} module. The other approach is to somehow get a
1033pointer to the method to be called, either the C function, or a callable Python
1034object. This is not really a good solution either, since there's a lot of
1035lookups involved.
1036
1037The way it works is that you have to supply a ``\class{socket}-like'' transport
1038object to the \class{SSL.Connection}. The only requirement of this object is
1039that it has a \method{fileno()} method that returns a file descriptor that's
1040valid at the C level (i.e. you can use the system calls read and write). If you
1041want to use the \method{connect()} or \method{accept()} methods of the
1042\class{SSL.Connection} object, the transport object has to supply such
1043methods too. Apart from them, any method lookups in the \class{SSL.Connection}
1044object that fail are passed on to the underlying transport object.
1045
1046Future changes might be to allow Python-level transport objects, that instead
1047of having \method{fileno()} methods, have \method{read()} and \method{write()}
1048methods, so more advanced features of Python can be used. This would probably
1049entail some sort of OpenSSL ``BIOs'', but converting Python strings back and
1050forth is expensive, so this shouldn't be used unless necessary. Other nice
1051things would be to be able to pass in different transport objects for reading
1052and writing, but then the \method{fileno()} method of \class{SSL.Connection}
1053becomes virtually useless. Also, should the method resolution be used on the
1054read-transport or the write-transport?
1055
1056
1057\end{document}