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