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