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