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