<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Introduction — pyOpenSSL 16.1.0 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="genindex.html"/>
<link rel="search" title="Search" href="search.html"/>
<link rel="top" title="pyOpenSSL 16.1.0 documentation" href="index.html"/>
<link rel="next" title="Installation" href="install.html"/>
<link rel="prev" title="Welcome to pyOpenSSL’s documentation!" href="index.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> pyOpenSSL
</a>
<div class="version">
16.1.0
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Introduction</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#history">History</a></li>
<li class="toctree-l2"><a class="reference internal" href="#development">Development</a></li>
<li class="toctree-l2"><a class="reference internal" href="#contributing">Contributing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#filing-bug-reports">Filing bug reports</a></li>
<li class="toctree-l3"><a class="reference internal" href="#patches">Patches</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#code">Code</a></li>
<li class="toctree-l4"><a class="reference internal" href="#documentation">Documentation</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#review">Review</a></li>
<li class="toctree-l3"><a class="reference internal" href="#finding-help">Finding Help</a></li>
<li class="toctree-l3"><a class="reference internal" href="#security">Security</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="install.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html"><code class="docutils literal"><span class="pre">OpenSSL</span></code> — Python interface to OpenSSL</a></li>
<li class="toctree-l1"><a class="reference internal" href="internals.html">Internals</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="backward-compatibility.html">Backward Compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">pyOpenSSL</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>Introduction</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/introduction.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="introduction">
<span id="intro"></span><h1>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h1>
<div class="section" id="history">
<h2>History<a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h2>
<p>pyOpenSSL was originally created by Martin Sjögren because the SSL support in the standard library in Python 2.1 (the contemporary version of Python when the pyOpenSSL project was begun) was severely limited.
Other OpenSSL wrappers for Python at the time were also limited, though in different ways.</p>
<p>Later it was maintained by <a class="reference external" href="https://github.com/exarkun">Jean-Paul Calderone</a> who among other things managed to make pyOpenSSL a pure Python project which the current maintainers are <em>very</em> grateful for.</p>
<p>Over the time the standard library’s <code class="docutils literal"><span class="pre">ssl</span></code> module improved, never reaching the completeness of pyOpenSSL’s API coverage.
Despite <a class="reference external" href="https://www.python.org/dev/peps/pep-0466/">PEP 466</a> many useful features remain Python 3-only and pyOpenSSL remains the only alternative for full-featured TLS code across all noteworthy Python versions from 2.6 through 3.5 and <a class="reference external" href="http://pypy.org">PyPy</a>.</p>
</div>
<div class="section" id="development">
<h2>Development<a class="headerlink" href="#development" title="Permalink to this headline">¶</a></h2>
<p>pyOpenSSL is collaboratively developed by the Python Cryptography Authority (<a class="reference external" href="https://github.com/pyca">PyCA</a>) that also maintains the low-level bindings called <a class="reference external" href="https://github.com/pyca/cryptography">cryptography</a>.</p>
<p>Current maintainer and release manager is <a class="reference external" href="https://hynek.me/">Hynek Schlawack</a>.</p>
</div>
<div class="section" id="contributing">
<h2>Contributing<a class="headerlink" href="#contributing" title="Permalink to this headline">¶</a></h2>
<p>First of all, thank you for your interest in contributing to pyOpenSSL!
This project has no company backing its development therefore we’re dependent on help by the community.</p>
<div class="section" id="filing-bug-reports">
<h3>Filing bug reports<a class="headerlink" href="#filing-bug-reports" title="Permalink to this headline">¶</a></h3>
<p>Bug reports are very welcome.
Please file them on the <a class="reference external" href="https://github.com/pyca/pyopenssl/issues">GitHub issue tracker</a>.
Good bug reports come with extensive descriptions of the error and how to reproduce it.
Reporters are strongly encouraged to include an <a class="reference external" href="http://www.sscce.org/">short, self contained, correct example</a>.</p>
</div>
<div class="section" id="patches">
<h3>Patches<a class="headerlink" href="#patches" title="Permalink to this headline">¶</a></h3>
<p>All patches to pyOpenSSL should be submitted in the form of pull requests to the main pyOpenSSL repository, <a class="reference external" href="https://github.com/pyca/pyopenssl">pyca/pyopenssl</a>.
These pull requests should satisfy the following properties:</p>
<div class="section" id="code">
<h4>Code<a class="headerlink" href="#code" title="Permalink to this headline">¶</a></h4>
<ul class="simple">
<li>The pull request should focus on one particular improvement to pyOpenSSL.
Create different pull requests for unrelated features or bugfixes.</li>
<li>Code should follow <a class="reference external" href="https://www.python.org/dev/peps/pep-0008/">PEP 8</a>, especially in the “do what code around you does” sense.
Follow OpenSSL naming for callables whenever possible is preferred.</li>
<li>New tests should use <a class="reference external" href="https://pytest.org/latest/assert.html">py.test-style assertions</a> instead of the old <code class="docutils literal"><span class="pre">self.assertXYZ</span></code>-style.</li>
<li>Pull requests that introduce code must test all new behavior they introduce as well as for previously untested or poorly tested behavior that they touch.</li>
<li>Pull requests are not allowed to break existing tests.
We usually don’t comment on pull requests that are breaking the CI because we consider them work in progress.
Please note that not having 100% code coverage for the code you wrote/touched also causes our CI to fail.</li>
</ul>
</div>
<div class="section" id="documentation">
<h4>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h4>
<p>When introducing new functionality, please remember to write documentation.</p>
<ul>
<li><p class="first">New functions and methods should have a docstring describing what they do, what parameters they takes, what types those parameters are, and what they return.</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">dump_publickey</span><span class="p">(</span><span class="nb">type</span><span class="p">,</span> <span class="n">pkey</span><span class="p">):</span>
<span class="sd">"""</span>
<span class="sd"> Dump a public key to a buffer.</span>
<span class="sd"> :param type: The file type (one of :data:`FILETYPE_PEM` or</span>
<span class="sd"> :data:`FILETYPE_ASN1`).</span>
<span class="sd"> :param PKey pkey: The PKey to dump.</span>
<span class="sd"> :return: The buffer with the dumped key in it.</span>
<span class="sd"> :rtype: bytes</span>
<span class="sd"> """</span>
</pre></div>
</div>
<p>Don’t forget to add an <code class="docutils literal"><span class="pre">..</span> <span class="pre">auto(function|class|method)::</span></code> statement to the relevant API document found in <code class="docutils literal"><span class="pre">doc/api/</span></code> to actually add your function to the Sphinx documentation.</p>
</li>
<li><p class="first">Do <em>not</em> use <code class="docutils literal"><span class="pre">:py:</span></code> prefixes when cross-linking (Python is default).
Do <em>not</em> use the generic <code class="docutils literal"><span class="pre">:data:</span></code> or <code class="docutils literal"><span class="pre">:obj:</span></code>.
Instead use more specific types like <code class="docutils literal"><span class="pre">:class:</span></code>, <code class="docutils literal"><span class="pre">:func:</span></code> or <code class="docutils literal"><span class="pre">:meth:</span></code> if applicable.</p>
</li>
<li><p class="first">Pull requests that introduce features or fix bugs should note those changes in the <a class="reference external" href="https://github.com/pyca/pyopenssl/blob/master/CHANGELOG.rst">CHANGELOG.rst</a> file.
Please add new entries to the <em>top</em> of the <em>current</em> Changes section followed by a line linking to the relevant pull request:</p>
<div class="highlight-rst"><div class="highlight"><pre><span></span><span class="m">-</span> Added <span class="s">``OpenSSL.crypto.some_func()``</span> to do something awesome.
[<span class="s">`#1 </span><span class="si"><https://github.com/pyca/pyopenssl/pull/1></span><span class="s">`_</span>]
</pre></div>
</div>
</li>
<li><p class="first">Use <a class="reference external" href="http://rhodesmill.org/brandon/2012/one-sentence-per-line/">semantic newlines</a> in <a class="reference external" href="http://sphinx-doc.org/rest.html">reStructuredText</a> files (files ending in <code class="docutils literal"><span class="pre">.rst</span></code>).</p>
</li>
</ul>
</div>
</div>
<div class="section" id="review">
<h3>Review<a class="headerlink" href="#review" title="Permalink to this headline">¶</a></h3>
<p>Finally, pull requests must be reviewed before merging.
This process mirrors the <a class="reference external" href="https://cryptography.io/en/latest/development/reviewing-patches/">cryptography code review process</a>.
Everyone can perform reviews; this is a very valuable way to contribute, and is highly encouraged.</p>
<p>Pull requests are merged by <a class="reference external" href="https://github.com/orgs/pyca/people">members of PyCA</a>.
They should, of course, keep all the requirements detailed in this document as well as the <code class="docutils literal"><span class="pre">pyca/cryptography</span></code> merge requirements in mind.</p>
<p>The final responsibility for the reviewing of merged code lies with the person merging it.
Since pyOpenSSL is a sensitive project from a security perspective, reviewers are strongly encouraged to take this review and merge process very seriously.</p>
</div>
<div class="section" id="finding-help">
<h3>Finding Help<a class="headerlink" href="#finding-help" title="Permalink to this headline">¶</a></h3>
<p>If you need any help with the contribution process, you’ll find us hanging out at <code class="docutils literal"><span class="pre">#cryptography-dev</span></code> on <a class="reference external" href="https://freenode.net">Freenode</a> IRC.
You can also ask questions on our <a class="reference external" href="https://mail.python.org/mailman/listinfo/cryptography-dev">mailing list</a>.</p>
<p>Please note that this project is released with a Contributor <a class="reference external" href="https://github.com/pyca/pyopenssl/blob/master/CODE_OF_CONDUCT.rst">Code of Conduct</a>.
By participating in this project you agree to abide by its terms.</p>
</div>
<div class="section" id="security">
<h3>Security<a class="headerlink" href="#security" title="Permalink to this headline">¶</a></h3>
<p>If you feel that you found a security-relevant bug that you would prefer to discuss in private, please send us a <a class="reference external" href="https://en.wikipedia.org/wiki/GNU_Privacy_Guard">GPG</a>-encrypted e-mail.</p>
<p>The maintainer can be reached at <a class="reference external" href="mailto:hs%40ox.cx">hs<span>@</span>ox<span>.</span>cx</a> and his GPG key ID is <code class="docutils literal"><span class="pre">0xAE2536227F69F181</span></code> (Fingerprint: <code class="docutils literal"><span class="pre">C2A0</span> <span class="pre">4F86</span> <span class="pre">ACE2</span> <span class="pre">8ADC</span> <span class="pre">F817</span>  <span class="pre">DBB7</span> <span class="pre">AE25</span> <span class="pre">3622</span> <span class="pre">7F69</span> <span class="pre">F181</span></code>).
Feel free to cross-check this information with <a class="reference external" href="https://keybase.io/hynek">Keybase</a>.</p>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="install.html" class="btn btn-neutral float-right" title="Installation" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="index.html" class="btn btn-neutral" title="Welcome to pyOpenSSL’s documentation!" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2001-2017, The pyOpenSSL developers.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'16.1.0',
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>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
be48589b7b9611719bcc10d42dba172d
>
files
>
83
