OpenSSLWiki - User contributions [en]

Use of Git

2017-04-20T01:32:21Z

Jonspillett: Fix link

Note: This is a superset of the information at https://www.openssl.org/source/gitrepo.html

== Background information about using the Git distributed version control system ==

This page provides examples for some of the <tt>git</tt> commands used when accessing OpenSSL source code, but does not provide complete coverage.

* Refer to the <tt>git</tt> man ages and http://git-scm.com/ for more complete instructions on using the command.
* Refer to https://github.com/ for more complete instructions on interacting with Github.

== Use of Git with OpenSSL source tree ==

The OpenSSL group hosts its own Git repository at openssl.org, and this contains the master copy of OpenSSL. You can browse this at https://git.openssl.org/gitweb/?p=openssl.git;a=tree, or get a clone (checkout) of it with the command <tt>git clone git://git.openssl.org/openssl.git</tt>.

Contributors to OpenSSL should make use of the Github copy of this repository at https://github.com/openssl/openssl. Github makes it easy to maintain your own fork of OpenSSL for developing your contributions, as well as making a "pull request" to share fixes with the OpenSSL team when finished. Changes in the master Git repository are represented in the Github copy within minutes.

You can view existing pull requests against any of the branches at https://github.com/openssl/openssl/pulls

=== Getting a copy of the OpenSSL source tree ===

If you want to quickly make a copy of the OpenSSL source tree and you do not plan to publish any changes for use by others, just create a clone on your own machine.

<pre>
$ git clone https://github.com/openssl/openssl.git
</pre>

(Refer to Github documentation for instructions on other means of cloning the source tree.)

If you plan to make changes to the sources that you will share with others, including contributing changes to OpenSSL, it is recommended that you create a fork of the OpenSSL tree using your own Github id. You can use this to share changes with others whether or not you intend to submit changes to the OpenSSL team. Refer to the documentation at https://help.github.com/articles/fork-a-repo, in particular the discussion about how to track changes in the real OpenSSL repository that you forked.

=== Branches ===

The Git repositories contain multiple branches, representing development levels of OpenSSL as well as current and upcoming stable branches. An easy way to see the available branches is with the branch selector at https://github.com/openssl/openssl. The branches which are of most interest to most users are

* master (development)
* OpenSSL_1_1_0-stable
* OpenSSL_1_0_2-stable

In order to access the code for a branch other than master, clone the Git repository then use the <tt>git checkout ''branchname''</tt> command to switch to a different branch. Consider using separate checkouts for each branch you are working in, with appropriate names for each, such as in the following example.

<pre>
$ git clone https://github.com/openssl/openssl.git OpenSSL-master
$ git clone https://github.com/openssl/openssl.git OpenSSL_1_1_0-stable
$ (cd OpenSSL_1_0_2-stable && git checkout OpenSSL_1_1_0-stable)
$ git clone https://github.com/openssl/openssl.git OpenSSL_1_0_2-stable
$ (cd OpenSSL_1_0_2-stable && git checkout OpenSSL_1_0_2-stable)
</pre>

If you've created your own fork of OpenSSL, replace the URL on the <tt>git clone</tt> command with the one for your fork. Also, you'll need to follow the instructions at https://help.github.com/articles/fork-a-repo for picking up changes from the master repository that you forked.

=== Making pull requests ===

After developing and testing changes to OpenSSL in your checkout (clone), push them to your fork of OpenSSL (<tt>git push</tt>), then use the Github interface to submit a pull request to the master OpenSSL repository for the particular revision(s).

Anyone can comment on PR's, and suggest changes. Before a PR is accepted, it must be approved by two OpenSSL team members.

== Use of Git with the OpenSSL web site ==

The OpenSSL web site is also maintained in git, and can be browsed at https://git.openssl.org/gitweb/?p=openssl-web.git;a=tree.

Unlike the source code, the OpenSSL web site repository is not copied to Github. You can only interact with it via git.openssl.org, so it is not possible to submit pull requests.

Check it out as follows:

<pre>
$ git clone git://git.openssl.org/openssl-web.git
</pre>

In order to submit corrections to the web site, create a patch as described above.

Only the master branch of the web site repository is used.

Developing For OpenSSL

2017-04-20T00:57:26Z

Jonspillett: Remove RT references, add GitHub ones

Periodically people ask us how to join the OpenSSL development team. This page is an attempt to answer that question.

Firstly it is important to understand that OpenSSL is complex. It is both a fully featured cryptography library as well as an SSL/TLS library. In addition the command line tools provide a wide array of capabilities. It can take quite a while to become proficient in coding in the internals. It is also clearly security sensitive. For those reasons joining the main development team is by invitation only. Most of the current development team have had an association with OpenSSL of one sort or another for a long time. Some have been on the project since the beginning, whilst many others joined later. For those joining later, without exception, everyone had a number of years of experience working with OpenSSL before they joined the team itself. The list of current development team members is available here: https://www.openssl.org/about/

However, there are still a number of ways to contribute to the project without joining the development team. We welcome such contributions:

* A good place to start is the openssl-users and openssl-dev mailing lists. The first of these forums will give you the opportunity to help out other users of OpenSSL, and learn from other experts in its use. The latter will give you an insight into some of the development issues that the team is tackling - and in particular issues being raised through the [https://github.com/openssl/openssl/issues GitHub issue tracking] system and responses to those issues.

* We are always looking for good people to help us build up the information held within this wiki. Documentation is one area where we are keen to improve things, and this wiki is an important location for people to come to. Information on how to get an account is available on the [[Welcome]] page.

* Bug fixes and enhancements to the code and documentation can be submitted via [https://github.com/openssl/openssl GitHub] as [https://github.com/openssl/openssl/issues issues] or [https://github.com/openssl/openssl/pulls pull requests]. See the README for details. If using GitHub pull requests please create and/or reference an issue so that it will automatically show up in the issue timeline.

Versioning

2017-04-20T00:41:18Z

Jonspillett: Added a versioning page with links

[[Category:Versioning]]
OpenSSL version numbers are formatted as n1.n2.n3x, where n1-3 are numbers and x, if present, is one or more letters. These can change depending on the release type:

- '''Major releases''' that change one/both of the first two digits, which can break compatibility with previous versions

- '''Minor releases''' that change the last digit, e.g. 1.1.0 vs. 1.1.1, can and are likely to contain new features, but in a way that does not break binary compatibility. This means that an application compiled and dynamically linked with 1.1.0 does not need to be recompiled when the shared library is updated to 1.1.1. It should be noted that some features are transparent to the application such as the maximum negotiated TLS version and cipher suites, performance improvements and so on. There is no need to recompile applications to benefit from these features.

- '''Letter releases''', such as 1.0.2a, exclusively contain bug and security fixes and no new features.

The full release strategy for OpenSSL is available [https://www.openssl.org/policies/releasestrat.html here]

== Finding the current version ==

The command line tool [https://www.openssl.org/docs/manmaster/apps/version.html version] can be used to determine the installed OpenSSL version.

Header file [https://github.com/openssl/openssl/blob/master/include/openssl/opensslv.h opensslv.h] also contains information about the version number.

Main Page

2017-04-20T00:07:37Z

Jonspillett:

This is the OpenSSL wiki. The main site is https://www.openssl.org . If this is your first visit or to get an account please see the [[Welcome]] page. Your participation and [[Contributions]] are valued.

This wiki is intended as a place for collecting, organizing, and refining useful information about OpenSSL that is currently strewn among multiple locations and formats.

== OpenSSL Quick Links ==

<TABLE border=0>
<TR>
<TD>[[OpenSSL Overview]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Compilation and Installation]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Internals]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Mailing Lists]] </TD>
</TR>
<TR>
<TD>[[libcrypto API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[libssl API]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Examples]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Documentation Index|Index of all API functions]]</TD>
</TR>
<TR>
<TD>[[License]] </TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Command Line Utilities]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Related Links]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[Binaries]]</TD>
</TR>
<TR>
<TD>[[SSL and TLS Protocols]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[1.1 API Changes]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
<TD>[[FIPS modules]]</TD>
<TD>[[Image:HTAB.png]][[Image:HTAB.png]]</TD>
</TR>
</TABLE>

== Administrivia ==
Site guidelines, legal and admininstrative issues.
:* [[Basic rules]], [[Commercial Product Disclaimer]], [[Contributions]], [[Copyright]], [[License]]
:* Using This Wiki
:: [http://meta.wikimedia.org/wiki/Help:Contents Wiki User's Guide], [http://www.mediawiki.org/wiki/Manual:Configuration_settings Configuration settings list], [http://www.mediawiki.org/wiki/Manual:FAQ MediaWiki FAQ], [https://lists.wikimedia.org/mailman/listinfo/mediawiki-announce MediaWiki Mailing List]

== Reference ==
This section contains the automagically generated man pages from the OpenSSL git repository, and similar "man" style reference documentation. The man pages are automatically imported from the OpenSSL git repository and local wiki modifications are submitted as patches.
:* OpenSSL Manual Pages
::* [[Manual:Openssl(1)]], [[Manual:Ssl(3)]], [[Manual:Crypto(3)]], [[Documentation Index]]
:: If you wish to edit any of the Manual page content please refer to the [[Guidelines for Manual Page Authors]] page.
:* [[API]], [[Libcrypto API]], [[Libssl API]]
:* [[FIPS mode()]], [[FIPS_mode_set()]]

== Usage and Programming ==
This section has discussions of practical issues in using OpenSSL
:* Building from Source
:: Where to find it, the different versions, how to build and install it.
:* [[OpenSSL Overview]]
:* [[Versioning]]
:* [[Compilation and Installation]]
:* [[EVP]]
:: Programming techniques and example code
:: Use of EVP is preferred for most applications and circumstances
::* [[EVP Asymmetric Encryption and Decryption of an Envelope]]
::* [[EVP Authenticated Encryption and Decryption]]
::* [[EVP Symmetric Encryption and Decryption]]
::* [[EVP Key and Parameter Generation]]
::* [[EVP Key Agreement]]
::* [[EVP Message Digests]]
::* [[EVP Key Derivation]]
::* [[EVP Signing and Verifying|EVP Signing and Verifying (including MAC codes)]]
:* [[STACK API]]
:* Low Level APIs
::[[Creating an OpenSSL Engine to use indigenous ECDH ECDSA and HASH Algorithms]]
:: More specialized non-EVP usage
::* [[Diffie-Hellman parameters]]
:* [[FIPS Mode]]
:* [[Simple TLS Server]]

== Concepts and Theory ==
Discussions of basic cryptographic theory and concepts
Discussions of common operational issues
:* [[Base64]]
:* [http://wiki.openssl.org/index.php/Category:FIPS_140 FIPS 140-2]
:* [[Random Numbers]]
:* [[Diffie Hellman]]
:* [[Elliptic Curve Diffie Hellman]]
:* [[Elliptic Curve Cryptography]]

== Security Advisories ==
:* [https://www.openssl.org/policies/secpolicy.html OpenSSL Security Policy]
:* [https://www.openssl.org/news/vulnerabilities.html OpenSSL Vulnerabilities List]
:* [[Security_Advisories|Security Advisories Additional Information]]

== Feedback and Contributions ==
:* [https://www.openssl.org/support/faq.html#BUILD18 How to notify us of suspected security vulnerabilities]
:* [https://www.openssl.org/community/#bugs How to report bugs, other than for suspected vulnerabilities]
:* [[Contributions|General background on source and documentation contributions - '''must read''']]
:* Contributing code fixes, other than for suspected vulnerabilities, as well as fixes and other improvements to manual pages:
::* If you are unsure as to whether a feature will be useful for the general OpenSSL community please discuss it on the [https://www.openssl.org/support/community.html openssl-dev mailing list] first. Someone may be already working on the same thing or there may be a good reason as to why that feature isn't implemented.
::* Follow the [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|instructions for accessing source code]] in the appropriate branches. Note that manual pages and the FAQ are maintained with the source code.
::* Submit a pull request for each separate fix (also documented [[Use of Git#Use_of_Git_with_OpenSSL_source_tree|there]])
::* Submit a bug report (see second bullet, above) and reference the pull request. Or you can attach the patch to the ticket.
:* Contributing fixes and other improvements to the web site
::* Follow the [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|instructions for accessing web site sources]]
::* Create a patch (also documented [[Use_of_Git#Use_of_Git_with_the_OpenSSL_web_site|there]])
::* Submit a bug report and add the patch as an attachment
:* [[Developing For OpenSSL]]
:* [[KnownPatches|Known patches not part of OpenSSL]]
:* [[Welcome|Contributing to this wiki]]

== Internals and Development ==
This section is for internal details of primary interest to OpenSSL maintainers and power users
:* [[Code reformatting]]

:* [[Internals]]
:* [[Code Quality]]
:* [[Static and Dynamic Analysis]]
:* [[OCB|OCB Licence details]]
:* [[Defect and Feature Review Process]]
:* [[Unit Testing]] (includes other automated testing information)