<div dir="ltr"><div><div><div><div>Paul,<br></div><br></div>I understand your point, and made an attempt at what you're suggesting with my initial post to this mailing list (addressing a different target audience):<br><br>"Surviving
 a Compromise of PyPI" proposes how the Python Package Index (PyPI) can 
be 
amended to better protect end users from altered or malicious packages, 
and to minimize the extent of PyPI compromises against affected users.  
The proposed integration allows package managers such as pip to be more 
secure against various types of security attacks on PyPI and defend end
 users from attackers responding to package requests. Specifically, 
these PEPs describe how PyPI processes should be adapted to generate and
 incorporate repository metadata, which are signed text files that 
describe the packages and metadata available on PyPI.  Package managers 
request (along with the packages) the metadata on PyPI to 
verify the authenticity of packages before they are installed.  The 
changes to PyPI and 
tools will be minimal by leveraging a library, <a href="https://github.com/theupdateframework/tuf" target="_blank">The Update Framework</a>, that generates and transparently validates the relevant metadata.<br><br>The first stage of the proposal (<a href="http://legacy.python.org/dev/peps/pep-0458/" target="_blank">PEP 458</a>) uses
 a basic security model that supports verification of PyPI packages 
signed with cryptographic keys stored on PyPI, requires no 
action from developers and end users, and protects against malicious 
CDNs and public mirrors. To support continuous delivery of uploaded 
packages, PyPI administrators sign for uploaded packages with an online key 
stored on PyPI infrastructure. This level of security prevents packages 
from being accidentally or deliberately tampered with by a mirror or a 
CDN because the mirror or CDN will not have any of the keys required to 
sign for projects."<br><br></div>Perhaps parts of this introduction (and your suggestion) will work better as an abstract, instead of assuming that the PyPI admins will be the only ones reading PEP 458.<br><br></div>Thanks again for all the feedback.<br></div><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Jan 2, 2015 at 12:23 PM, Paul Moore <span dir="ltr"><<a href="mailto:p.f.moore@gmail.com" target="_blank">p.f.moore@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 2 January 2015 at 16:14, Vladimir Diaz <<a href="mailto:vladimir.v.diaz@gmail.com">vladimir.v.diaz@gmail.com</a>> wrote:<br>
> There's a lot of background documentation and technical details excluded<br>
> from the PEPs (to avoid turning the PEP into a 15+ page behemoth), but I do<br>
> agree that we should explicitly cover some of these implementation details<br>
> in PEP 458.  Subsections on the exact format of metadata, explanation on how<br>
> metadata is signed, and how the roles are "delegated" with the library,<br>
> still remain.  As Paul as indicated, terminology can also be improved so as<br>
> to be more readable for "non-experts."<br>
<br>
</span>There's a tension here, in that while the detail is useful, the<br>
non-expert content needs to be *less* words, not more - the problem is<br>
one of an intimidating wall of text, much more than that the concepts<br>
are difficult. Adding more content, however necessary it is to the<br>
implementation side, probably detracts here.<br>
<br>
Just as an example, take the first paragraph of the abstract:<br>
<br>
"""<br>
This PEP proposes how the Python Package Index (PyPI [1] ) should be<br>
integrated with The Update Framework [2] (TUF). TUF was designed to be<br>
a flexible security add-on to a software updater or package manager.<br>
The framework integrates best security practices such as separating<br>
role responsibilities, adopting the many-man rule for signing<br>
packages, keeping signing keys offline, and revocation of expired or<br>
compromised signing keys. For example, attackers would have to steal<br>
multiple signing keys stored independently to compromise a role<br>
responsible for specifying a repository's available files. Another<br>
role responsible for indicating the latest snapshot of the repository<br>
may have to be similarly compromised, and independent of the first<br>
compromised role.<br>
"""<br>
<br>
There's no way I, even with the benefit of the discussions both on the<br>
list here and off-list, can skim that sentence and get anything more<br>
meaningful than "blah, blah, blah" from it. Taking a moment to think<br>
about it is fine, but at that point you've lost me (in terms of<br>
encouraging me to read the document, rather than just debate based on<br>
what I think it's going to say).<br>
<br>
None of the "best security practices" mentioned in sentence 3 mean<br>
anything to me - they all basically look like "do more security stuff"<br>
to me, and "doing security stuff" unfortunately, from my experience,<br>
translates to "jump through annoying hoops that stop me getting my job<br>
done"... Similarly, the last 2 sentences (the example) read as saying<br>
"attackers have to work harder". Well good, I'd sort of hope the PEP<br>
provided a benefit of some sort :-)<br>
<br>
The following (somewhat off the cuff) may work better:<br>
<br>
"""<br>
This PEP proposes some changes to the Python Package Index (PyPI)<br>
infrastructure to enhance its resistance to attack without requiring<br>
any changes in workflow from project authors. It is similar to recent<br>
changes to use TLS for all PyPI traffic, but offers additional<br>
security over TLS. Future PEPs may look at further security<br>
enhancements that could require additional action from project<br>
authors, but this PEP is restricted to the PyPI infrastructure and<br>
mirroring software.<br>
"""<br>
<br>
Sorry for what is pretty much a hatchet job on a single paragraph take<br>
out of context from the PEP, but hopefully you can see what I'm trying<br>
to say - skip details of security concepts, attack vectors, etc, and<br>
concentrate on "we're making things better - it's as low impact as the<br>
change to TLS - project authors won't need to do anything (at this<br>
stage)". Those are the key messages to get across straight away. A few<br>
more paragraphs in the abstract explaining in non-technical terms<br>
what's being done and why, and you're done. You can say "the rest of<br>
the document is the technical details for people with an understanding<br>
of (or interest in) the security concepts" and get on with the<br>
specifics.<br>
<br>
If you can get the non-specialists to read just the abstract section,<br>
and go away knowing they are happy to let the expects get on with the<br>
process, you've won. Put the details and the scary terms in the "for<br>
experts and interested parties only" main body.<br>
<span class="HOEnZb"><font color="#888888"><br>
Paul.<br>
</font></span></blockquote></div><br></div>