This file is indexed.

/usr/share/doc/python-openssl-doc/html/internals.html is in python-openssl-doc 0.15.1-2ubuntu0.2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Internals &mdash; pyOpenSSL 0.15.1 documentation</title>
    
    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '0.15.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="pyOpenSSL 0.15.1 documentation" href="index.html" />
    <link rel="prev" title="SSL — An interface to the SSL-specific parts of OpenSSL" href="api/ssl.html" /> 
  </head>
  <body role="document">
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="api/ssl.html" title="SSL — An interface to the SSL-specific parts of OpenSSL"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">pyOpenSSL 0.15.1 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="internals">
<span id="id1"></span><h1>Internals<a class="headerlink" href="#internals" title="Permalink to this headline"></a></h1>
<p>We ran into three main problems developing this: Exceptions, callbacks and
accessing socket methods. This is what this chapter is about.</p>
<div class="section" id="exceptions">
<span id="id2"></span><h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline"></a></h2>
<p>We realized early that most of the exceptions would be raised by the I/O
functions of OpenSSL, so it felt natural to mimic OpenSSL&#8217;s error code system,
translating them into Python exceptions. This naturally gives us the exceptions
<a class="reference internal" href="api/ssl.html#OpenSSL.SSL.ZeroReturnError" title="OpenSSL.SSL.ZeroReturnError"><code class="xref py py-exc docutils literal"><span class="pre">SSL.ZeroReturnError</span></code></a>, <a class="reference internal" href="api/ssl.html#OpenSSL.SSL.WantReadError" title="OpenSSL.SSL.WantReadError"><code class="xref py py-exc docutils literal"><span class="pre">SSL.WantReadError</span></code></a>,
<a class="reference internal" href="api/ssl.html#OpenSSL.SSL.WantWriteError" title="OpenSSL.SSL.WantWriteError"><code class="xref py py-exc docutils literal"><span class="pre">SSL.WantWriteError</span></code></a>, <a class="reference internal" href="api/ssl.html#OpenSSL.SSL.WantX509LookupError" title="OpenSSL.SSL.WantX509LookupError"><code class="xref py py-exc docutils literal"><span class="pre">SSL.WantX509LookupError</span></code></a> and
<a class="reference internal" href="api/ssl.html#OpenSSL.SSL.SysCallError" title="OpenSSL.SSL.SysCallError"><code class="xref py py-exc docutils literal"><span class="pre">SSL.SysCallError</span></code></a>.</p>
<p>For more information about this, see section <a class="reference internal" href="api/ssl.html#openssl-ssl"><span>SSL &#8212; An interface to the SSL-specific parts of OpenSSL</span></a>.</p>
</div>
<div class="section" id="callbacks">
<span id="id3"></span><h2>Callbacks<a class="headerlink" href="#callbacks" title="Permalink to this headline"></a></h2>
<p>Callbacks were more of a problem when pyOpenSSL was written in C.
Having switched to being written in Python using cffi, callbacks are now straightforward.
The problems that originally existed no longer do
(if you are interested in the details you can find descriptions of those problems in the version control history for this document).</p>
</div>
<div class="section" id="accessing-socket-methods">
<span id="socket-methods"></span><h2>Accessing Socket Methods<a class="headerlink" href="#accessing-socket-methods" title="Permalink to this headline"></a></h2>
<p>We quickly saw the benefit of wrapping socket methods in the
<a class="reference internal" href="api/ssl.html#OpenSSL.SSL.Connection" title="OpenSSL.SSL.Connection"><code class="xref py py-class docutils literal"><span class="pre">SSL.Connection</span></code></a> class, for an easy transition into using SSL. The
problem here is that the <code class="xref py py-mod docutils literal"><span class="pre">socket</span></code> module lacks a C API, and all the
methods are declared static. One approach would be to have <a class="reference internal" href="api.html#module-OpenSSL" title="OpenSSL: Python interface to OpenSSL"><code class="xref py py-mod docutils literal"><span class="pre">OpenSSL</span></code></a> as
a submodule to the <code class="xref py py-mod docutils literal"><span class="pre">socket</span></code> module, placing all the code in
<code class="docutils literal"><span class="pre">socketmodule.c</span></code>, but this is obviously not a good solution, since you
might not want to import tonnes of extra stuff you&#8217;re not going to use when
importing the <code class="xref py py-mod docutils literal"><span class="pre">socket</span></code> module. The other approach is to somehow get a
pointer to the method to be called, either the C function, or a callable Python
object. This is not really a good solution either, since there&#8217;s a lot of
lookups involved.</p>
<p>The way it works is that you have to supply a <code class="xref py py-class docutils literal"><span class="pre">socket</span></code>- <strong>like</strong> transport
object to the <a class="reference internal" href="api/ssl.html#OpenSSL.SSL.Connection" title="OpenSSL.SSL.Connection"><code class="xref py py-class docutils literal"><span class="pre">SSL.Connection</span></code></a>. The only requirement of this object is
that it has a <code class="xref py py-meth docutils literal"><span class="pre">fileno()</span></code> method that returns a file descriptor that&#8217;s
valid at the C level (i.e. you can use the system calls read and write). If you
want to use the <code class="xref py py-meth docutils literal"><span class="pre">connect()</span></code> or <code class="xref py py-meth docutils literal"><span class="pre">accept()</span></code> methods of the
<a class="reference internal" href="api/ssl.html#OpenSSL.SSL.Connection" title="OpenSSL.SSL.Connection"><code class="xref py py-class docutils literal"><span class="pre">SSL.Connection</span></code></a> object, the transport object has to supply such
methods too. Apart from them, any method lookups in the <a class="reference internal" href="api/ssl.html#OpenSSL.SSL.Connection" title="OpenSSL.SSL.Connection"><code class="xref py py-class docutils literal"><span class="pre">SSL.Connection</span></code></a>
object that fail are passed on to the underlying transport object.</p>
<p>Future changes might be to allow Python-level transport objects, that instead
of having <code class="xref py py-meth docutils literal"><span class="pre">fileno()</span></code> methods, have <code class="xref py py-meth docutils literal"><span class="pre">read()</span></code> and <code class="xref py py-meth docutils literal"><span class="pre">write()</span></code>
methods, so more advanced features of Python can be used. This would probably
entail some sort of OpenSSL <strong>BIOs</strong>, but converting Python strings back and
forth is expensive, so this shouldn&#8217;t be used unless necessary. Other nice
things would be to be able to pass in different transport objects for reading
and writing, but then the <code class="xref py py-meth docutils literal"><span class="pre">fileno()</span></code> method of <a class="reference internal" href="api/ssl.html#OpenSSL.SSL.Connection" title="OpenSSL.SSL.Connection"><code class="xref py py-class docutils literal"><span class="pre">SSL.Connection</span></code></a>
becomes virtually useless. Also, should the method resolution be used on the
read-transport or the write-transport?</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Internals</a><ul>
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
<li><a class="reference internal" href="#callbacks">Callbacks</a></li>
<li><a class="reference internal" href="#accessing-socket-methods">Accessing Socket Methods</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="api/ssl.html"
                        title="previous chapter"><code class="docutils literal"><span class="pre">SSL</span></code> &#8212; An interface to the SSL-specific parts of OpenSSL</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/internals.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="api/ssl.html" title="SSL — An interface to the SSL-specific parts of OpenSSL"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">pyOpenSSL 0.15.1 documentation</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &copy; Copyright 2011, Jean-Paul Calderone.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.6.
    </div>
  </body>
</html>