-Description
-===========
+[![openssl logo][]][www.openssl.org]
-The OpenSSL Project is a collaborative effort to develop a robust,
-commercial-grade, fully featured, and Open Source toolkit implementing the
-Transport Layer Security (TLS) protocols (including SSLv3) as well as a
-full-strength general purpose cryptographic library.
+[![travis badge][]][travis jobs]
+[![appveyor badge][]][appveyor jobs]
+
+
+
+Welcome to the OpenSSL Project
+==============================
+
+OpenSSL is a robust, commercial-grade, full-featured Open Source Toolkit
+for the Transport Layer Security (TLS) protocol formerly known as the
+Secure Sockets Layer (SSL) protocol. The protocol implementation is based
+on a full-strength general purpose cryptographic library, which can also
+be used stand-alone.
OpenSSL is descended from the SSLeay library developed by Eric A. Young
and Tim J. Hudson.
-The OpenSSL toolkit is licensed under the Apache License 2.0, which means
-that you are free to get and use it for commercial and non-commercial
-purposes as long as you fulfill its conditions.
+The official Home Page of the OpenSSL Project is [www.openssl.org][].
+
+
+Table of Contents
+=================
+
+ - [Overview](#overview)
+ - [Download](#download)
+ - [Build and Install](#build-and-install)
+ - [Documentation](#documentation)
+ - [License](#license)
+ - [Support](#support)
+ - [Contributing](#contributing)
+ - [Legalities](#legalities)
Overview
========
The OpenSSL toolkit includes:
- * **libssl**
- Provides the client and server-side implementations for SSLv3 and TLS.
+- **libssl**
+ an implementation of all TLS protocol versions up to TLSv1.3 ([RFC 8446][]).
+
+- **libcrypto**
+ a full-strength general purpose cryptographic library. It constitutes the
+ basis of the TLS implementation, but can also be used independently.
+
+- **openssl**
+ the OpenSSL command line tool, a swiss army knife for cryptographic tasks,
+ testing and analyzing. It can be used for
+ - creation of key parameters
+ - creation of X.509 certificates, CSRs and CRLs
+ - calculation of message digests
+ - encryption and decryption
+ - SSL/TLS client and server tests
+ - handling of S/MIME signed or encrypted mail
+ - and more...
+
+Download
+========
- * **libcrypto:**
- Provides general cryptographic and X.509 support needed by SSL/TLS but
- not logically part of it.
+For Production Use
+------------------
- * **openssl:**
- A command line tool that can be used for:
- Creation of key parameters
- Creation of X.509 certificates, CSRs and CRLs
- Calculation of message digests
- Encryption and decryption
- SSL/TLS client and server tests
- Handling of S/MIME signed or encrypted mail
- And more...
+Source code tarballs of the official releases can be downloaded from
+[www.openssl.org/source](https://www.openssl.org/source).
+The OpenSSL project does not distribute the toolkit in binary form.
-Installation
-============
+However, for a large variety of operating systems precompiled versions
+of the OpenSSL toolkit are available. In particular on Linux and other
+Unix operating systems it is normally recommended to link against the
+precompiled shared libraries provided by the distributor or vendor.
-See the appropriate file:
- * [INSTALL](INSTALL): General installation instructions for all platforms
- * Additional instructions for specific platforms
- * [NOTES.ANDROID](NOTES.ANDROID)
- * [NOTES.DJGPP](NOTES.DJGPP)
- * [NOTES.PERL](NOTES.PERL)
- * [NOTES.UNIX](NOTES.UNIX)
- * [NOTES.VALGRIND](NOTES.VALGRIND)
- * [NOTES.VMS](NOTES.VMS)
- * [NOTES.WIN](NOTES.WIN)
+For Testing and Development
+---------------------------
-Support
+Although testing and development could in theory also be done using
+the source tarballs, having a local copy of the git repository with
+the entire project history gives you much more insight into the
+code base.
+
+The official OpenSSL Git Repository is located at [git.openssl.org][].
+There is a GitHub mirror of the repository at [github.com/openssl/openssl][],
+which is updated automatically from the former on every commit.
+
+A local copy of the Git Repository can be obtained by cloning it from
+the original OpenSSL repository using
+
+ git clone git://git.openssl.org/openssl.git
+
+or from the GitHub mirror using
+
+ git clone https://github.com/openssl/openssl.git
+
+If you intend to contribute to OpenSSL, either to fix bugs or contribute
+new features, you need to fork the OpenSSL repository openssl/openssl on
+GitHub and clone your public fork instead.
+
+ git clone https://github.com/yourname/openssl.git
+
+This is necessary, because all development of OpenSSL nowadays is done via
+GitHub pull requests. For more details, see [Contributing](#contributing).
+
+
+Build and Install
+=================
+
+After obtaining the Source, have a look at the [INSTALL](INSTALL.md) file for
+detailed instructions about building and installing OpenSSL. For some
+platforms, the installation instructions are amended by a platform specific
+document.
+
+ * [NOTES.ANDROID](NOTES.ANDROID)
+ * [NOTES.DJGPP](NOTES.DJGPP)
+ * [NOTES.PERL](NOTES.PERL)
+ * [NOTES.UNIX](NOTES.UNIX)
+ * [NOTES.VALGRIND](NOTES.VALGRIND)
+ * [NOTES.VMS](NOTES.VMS)
+ * [NOTES.WIN](NOTES.WIN)
+
+
+Documentation
+=============
+
+Manual Pages
+------------
+
+The manual pages for the master branch and all current stable releases are
+available online.
+
+- [OpenSSL master](https://www.openssl.org/docs/manmaster)
+- [OpenSSL 1.1.1](https://www.openssl.org/docs/man1.1.1)
+
+Wiki
+----
+
+There is a Wiki at [wiki.openssl.org][] which is currently not very active.
+It contains a lot of useful information, not all of which is up to date.
+
+License
=======
-See the OpenSSL website www.openssl.org for details on how to obtain
-commercial technical support. Free community support is available through the
-openssl-users email list (see
-https://www.openssl.org/community/mailinglists.html for further details).
+OpenSSL is licensed under the Apache License 2.0, which means that
+you are free to get and use it for commercial and non-commercial
+purposes as long as you fulfill its conditions.
-If you have any problems with OpenSSL then please take the following steps
-first:
+See the [LICENSE](LICENSE) file for more details.
- - Download the latest version from the repository
- to see if the problem has already been addressed
- - Configure with no-asm
- - Remove compiler optimization flags
+Support
+=======
-If you wish to report a bug then please include the following information
-and create an issue on GitHub:
+There are various ways to get in touch. The correct channel depends on
+your requirement. see the [SUPPORT](SUPPORT.md) file for more details.
- - OpenSSL version: output of 'openssl version -a'
- - Configuration data: output of 'perl configdata.pm --dump'
- - OS Name, Version, Hardware platform
- - Compiler Details (name, version)
- - Application Details (name, version)
- - Problem Description (steps that will reproduce the problem, if known)
- - Stack Traceback (if the application dumps core)
+Contributing
+============
-Just because something doesn't work the way you expect does not mean it
-is necessarily a bug in OpenSSL. Use the openssl-users email list for this type
-of query.
+If you are interested and willing to contribute to the OpenSSL project,
+please take a look at the [CONTRIBUTING](CONTRIBUTING.md) file.
-How to contribute to OpenSSL
-============================
+Since 2016, development takes place in public on the GitHub open source
+platform. The OpenSSL Project Pages at [openssl.github.io][] are a
+valuable source of information if you want to get familiar with our
+development process on GitHub.
- See [CONTRIBUTING](CONTRIBUTING.md)
- Legalities
- ==========
+Legalities
+==========
- A number of nations restrict the use or export of cryptography. If you
- are potentially subject to such restrictions you should seek competent
- professional legal advice before attempting to develop or distribute
- cryptographic code.
+A number of nations restrict the use or export of cryptography. If you are
+potentially subject to such restrictions you should seek legal advice before
+attempting to develop or distribute cryptographic code.
Copyright
=========
-Copyright (c) 1998-2018 The OpenSSL Project
+Copyright (c) 1998-2020 The OpenSSL Project
Copyright (c) 1995-1998 Eric A. Young, Tim J. Hudson
All rights reserved.
+
+
+<!-- Links -->
+
+[www.openssl.org]:
+ https://www.openssl.org
+ "OpenSSL Homepage"
+
+[git.openssl.org]:
+ https://git.openssl.org
+ "OpenSSL Git Repository"
+
+[git.openssl.org]:
+ https://git.openssl.org
+ "OpenSSL Git Repository"
+
+[github.com/openssl/openssl]:
+ https://github.com/openssl/openssl
+ "OpenSSL GitHub Mirror"
+
+[openssl.github.io]:
+ https://mspncp.github.io
+ "OpenSSL Project Pages"
+
+[wiki.openssl.org]:
+ https://wiki.openssl.org
+ "OpenSSL Wiki"
+
+
+[RFC 8446]:
+ https://tools.ietf.org/html/rfc8446
+
+
+<!-- Logos and Badges -->
+<!--
+ Note: The security token for the appveyor badge (the random number in
+ the URL below) was obtained for the mspncp/openssl project.
+ It needs to be replaced by the correct token by some core member
+ (@levitte, @mattcaswell?). It can be obtained for project members at
+ https://ci.appveyor.com/project/openssl/openssl/settings/badges.
+-->
+
+[openssl logo]:
+ doc/images/openssl.svg
+ "OpenSSL Logo"
+
+[travis badge]:
+ https://travis-ci.org/openssl/openssl.svg?branch=master
+ "Travis Build Status"
+
+[travis jobs]:
+ https://travis-ci.org/openssl/openssl
+ "Travis Jobs"
+
+[appveyor badge]:
+ https://ci.appveyor.com/api/projects/status/ikn2l4u1xsume63u/branch/master?svg=true
+ "AppVeyor Build Status"
+
+[appveyor jobs]:
+ https://ci.appveyor.com/project/openssl/openssl/branch/master
+ "AppVeyor Jobs"
projects / oweals / openssl.git / commitdiff