Difference between revisions of "Contributions"

From OpenSSLWiki
Jump to navigationJump to search
(→‎Compatibility: fixed typos and formatting)
Line 41: Line 41:
  
 
==== Coding Style ====
 
==== Coding Style ====
Although there are some exceptions most of the OpenSSL code is indented in a rather
+
The OpenSSL coding style is available here:
quirky way. That style isn't documented but if you can't figure it out from looking
+
https://www.openssl.org/policies/codingstyle.html
at existing source you haven't spend nearly enough time with OpenSSL to think about
 
changing it. If a reviewer has to reformat everything to fit with the current code
 
style that counts against it.  
 
  
 
=== Documentation ===
 
=== Documentation ===

Revision as of 11:39, 30 November 2015

There are a number of reasons why code or documentation contributions may not be adopted by the OpenSSL maintainers. See http://www.opensslfoundation.com/contributions.html for a personal perspective on OpenSSL contributions.

Technical Concerns

Compatibility

Binary incompatible changes can only occur on major releases (the next is 1.1.0) and releases are often years apart. OpenSSL has a painful history of problems caused by references to OpenSSL internals, a history that has left the survivors very paranoid about referencing or changing APIs or structures (even those which seem to be clearly for internal use only).

New features cannot be added to existing stable releases as this violates the versioning rule. So adding new functionality to OpenSSL 0.9.8, 1.0.0 or 1.0.1 just isn't going to happen unless that new functionality is needed to address a security hole or bug.

Security Issues

It is all too easy to inadvertently introduce security vulnerabilities that may not be immediately apparent even to experts. For instance, side channel attacks that exploit subtle timing differences between different code paths.

Platform Portability

OpenSSL runs on an enormous variety of platforms -- processor architectures, operating systems, compilers -- some of which have subtle and obscure quirks. Any changes to OpenSSL should at a minimum not break support for any existing platforms. The typical contributor will not be aware of all the potential platform portability pitfalls and so the code will require careful review by the OpenSSL team.

Future Directions

(TBD)

Maintainability

Incorporation of new code into OpenSSL means an implicit obligation to support it forever. There are many subtleties about OpenSSL which even surprise the experts at times: new code may have unfortunate consequences and open up security holes. OpenSSL is used on a very wide range of applications including a sizeable proportions of the world's web servers and as a result the developers have to be pretty darned sure new additions wont have unfortunate consequences. Comments and/or documentation can help a lot here especially for addition of new features to OpenSSL itself.

Presentation

(TBD)

Patch Format

Methods of creating patches in the recommended format are covered in the documentation for accessing OpenSSL source code.

Coding Style

The OpenSSL coding style is available here: https://www.openssl.org/policies/codingstyle.html

Documentation

(TBD)

Code Maturity

With documentation there is another factor. People rely on documentation as showing the preferred way of using the software, and once documented an API it effectively "cast in stone" for future versions of OpenSSL. There is a reluctance to document features that may not yet be in a final form.

Abstraction Level

With OpenSSL there is usually a preferred general high-level API (EVP) and then many lower level function calls that can be used to achieve similar outcomes. The higher level abstractions are usually the best solution for all common application requirements. As a result there is a reluctance to adopt and publish documentation of low level APIs when the corresponding preferred high level approach is not yet adequately documented.

Licensing and Copyright

Is the code compatible with the OpenSSL license? New contributions will receive appropriate credit but they can't be expected to require every OpenSSL application to acknowledge the author in the documentation by adding additional attribution requirements.