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