README.md

   1 Welcome to the OpenSSL Project
   2 ==============================
   3
   4 [![openssl logo]][www.openssl.org]
   5
   6 [![github actions ci badge]][github actions ci]
   7 [![appveyor badge]][appveyor jobs]
   8
   9 OpenSSL is a robust, commercial-grade, full-featured Open Source Toolkit
  10 for the TLS (formerly SSL), DTLS and QUIC (currently client side only)
  11 protocols.
  12
  13 The protocol implementations are based on a full-strength general purpose
  14 cryptographic library, which can also be used stand-alone. Also included is a
  15 cryptographic module validated to conform with FIPS standards.
  16
  17 OpenSSL is descended from the SSLeay library developed by Eric A. Young
  18 and Tim J. Hudson.
  19
  20 The official Home Page of the OpenSSL Project is [www.openssl.org].
  21
  22 Table of Contents
  23 =================
  24
  25  - [Overview](#overview)
  26  - [Download](#download)
  27  - [Build and Install](#build-and-install)
  28  - [Documentation](#documentation)
  29  - [License](#license)
  30  - [Support](#support)
  31  - [Contributing](#contributing)
  32  - [Legalities](#legalities)
  33
  34 Overview
  35 ========
  36
  37 The OpenSSL toolkit includes:
  38
  39 - **libssl**
  40   an implementation of all TLS protocol versions up to TLSv1.3 ([RFC 8446]),
  41   DTLS protocol versions up to DTLSv1.2 ([RFC 6347]) and
  42   the QUIC (currently client side only) version 1 protocol ([RFC 9000]).
  43
  44 - **libcrypto**
  45   a full-strength general purpose cryptographic library. It constitutes the
  46   basis of the TLS implementation, but can also be used independently.
  47
  48 - **openssl**
  49   the OpenSSL command line tool, a swiss army knife for cryptographic tasks,
  50   testing and analyzing. It can be used for
  51   - creation of key parameters
  52   - creation of X.509 certificates, CSRs and CRLs
  53   - calculation of message digests
  54   - encryption and decryption
  55   - SSL/TLS/DTLS and client and server tests
  56   - QUIC client tests
  57   - handling of S/MIME signed or encrypted mail
  58   - and more...
  59
  60 Download
  61 ========
  62
  63 For Production Use
  64 ------------------
  65
  66 Source code tarballs of the official releases can be downloaded from
  67 [www.openssl.org/source](https://www.openssl.org/source).
  68 The OpenSSL project does not distribute the toolkit in binary form.
  69
  70 However, for a large variety of operating systems precompiled versions
  71 of the OpenSSL toolkit are available. In particular, on Linux and other
  72 Unix operating systems, it is normally recommended to link against the
  73 precompiled shared libraries provided by the distributor or vendor.
  74
  75 We also maintain a list of third parties that produce OpenSSL binaries for
  76 various Operating Systems (including Windows) on the [Binaries] page on our
  77 wiki.
  78
  79 For Testing and Development
  80 ---------------------------
  81
  82 Although testing and development could in theory also be done using
  83 the source tarballs, having a local copy of the git repository with
  84 the entire project history gives you much more insight into the
  85 code base.
  86
  87 The official OpenSSL Git Repository is located at [git.openssl.org].
  88 There is a GitHub mirror of the repository at [github.com/openssl/openssl],
  89 which is updated automatically from the former on every commit.
  90
  91 A local copy of the Git Repository can be obtained by cloning it from
  92 the original OpenSSL repository using
  93
  94     git clone git://git.openssl.org/openssl.git
  95
  96 or from the GitHub mirror using
  97
  98     git clone https://github.com/openssl/openssl.git
  99
 100 If you intend to contribute to OpenSSL, either to fix bugs or contribute
 101 new features, you need to fork the OpenSSL repository openssl/openssl on
 102 GitHub and clone your public fork instead.
 103
 104     git clone https://github.com/yourname/openssl.git
 105
 106 This is necessary because all development of OpenSSL nowadays is done via
 107 GitHub pull requests. For more details, see [Contributing](#contributing).
 108
 109 Build and Install
 110 =================
 111
 112 After obtaining the Source, have a look at the [INSTALL](INSTALL.md) file for
 113 detailed instructions about building and installing OpenSSL. For some
 114 platforms, the installation instructions are amended by a platform specific
 115 document.
 116
 117  * [Notes for UNIX-like platforms](NOTES-UNIX.md)
 118  * [Notes for Android platforms](NOTES-ANDROID.md)
 119  * [Notes for Windows platforms](NOTES-WINDOWS.md)
 120  * [Notes for the DOS platform with DJGPP](NOTES-DJGPP.md)
 121  * [Notes for the OpenVMS platform](NOTES-VMS.md)
 122  * [Notes on Perl](NOTES-PERL.md)
 123  * [Notes on Valgrind](NOTES-VALGRIND.md)
 124
 125 Specific notes on upgrading to OpenSSL 3.x from previous versions can be found
 126 in the [ossl-guide-migration(7ossl)] manual page.
 127
 128 Documentation
 129 =============
 130
 131 README Files
 132 ------------
 133
 134 There are some README.md files in the top level of the source distribution
 135 containing additional information on specific topics.
 136
 137  * [Information about the OpenSSL QUIC protocol implementation](README-QUIC.md)
 138  * [Information about the OpenSSL Provider architecture](README-PROVIDERS.md)
 139  * [Information about using the OpenSSL FIPS validated module](README-FIPS.md)
 140  * [Information about the legacy OpenSSL Engine architecture](README-ENGINES.md)
 141
 142 The OpenSSL Guide
 143 -----------------
 144
 145 There are some tutorial and introductory pages on some important OpenSSL topics
 146 within the [OpenSSL Guide].
 147
 148 Manual Pages
 149 ------------
 150
 151 The manual pages for the master branch and all current stable releases are
 152 available online.
 153
 154 - [OpenSSL master](https://www.openssl.org/docs/manmaster)
 155 - [OpenSSL 3.0](https://www.openssl.org/docs/man3.0)
 156 - [OpenSSL 3.1](https://www.openssl.org/docs/man3.1)
 157
 158 Demos
 159 -----
 160
 161 The are numerous source code demos for using various OpenSSL capabilities in the
 162 [demos subfolder](./demos).
 163
 164 Wiki
 165 ----
 166
 167 There is a Wiki at [wiki.openssl.org] which is currently not very active.
 168 It contains a lot of useful information, not all of which is up-to-date.
 169
 170 License
 171 =======
 172
 173 OpenSSL is licensed under the Apache License 2.0, which means that
 174 you are free to get and use it for commercial and non-commercial
 175 purposes as long as you fulfill its conditions.
 176
 177 See the [LICENSE.txt](LICENSE.txt) file for more details.
 178
 179 Support
 180 =======
 181
 182 There are various ways to get in touch. The correct channel depends on
 183 your requirement. See the [SUPPORT](SUPPORT.md) file for more details.
 184
 185 Contributing
 186 ============
 187
 188 If you are interested and willing to contribute to the OpenSSL project,
 189 please take a look at the [CONTRIBUTING](CONTRIBUTING.md) file.
 190
 191 Legalities
 192 ==========
 193
 194 A number of nations restrict the use or export of cryptography. If you are
 195 potentially subject to such restrictions, you should seek legal advice before
 196 attempting to develop or distribute cryptographic code.
 197
 198 Copyright
 199 =========
 200
 201 Copyright (c) 1998-2023 The OpenSSL Project Authors
 202
 203 Copyright (c) 1995-1998 Eric A. Young, Tim J. Hudson
 204
 205 All rights reserved.
 206
 207 <!-- Links  -->
 208
 209 [www.openssl.org]:
 210     <https://www.openssl.org>
 211     "OpenSSL Homepage"
 212
 213 [git.openssl.org]:
 214     <https://git.openssl.org>
 215     "OpenSSL Git Repository"
 216
 217 [git.openssl.org]:
 218     <https://git.openssl.org>
 219     "OpenSSL Git Repository"
 220
 221 [github.com/openssl/openssl]:
 222     <https://github.com/openssl/openssl>
 223     "OpenSSL GitHub Mirror"
 224
 225 [wiki.openssl.org]:
 226     <https://wiki.openssl.org>
 227     "OpenSSL Wiki"
 228
 229 [ossl-guide-migration(7ossl)]:
 230     <https://www.openssl.org/docs/manmaster/man7/ossl-guide-migration.html>
 231     "OpenSSL Migration Guide"
 232
 233 [RFC 8446]:
 234      <https://tools.ietf.org/html/rfc8446>
 235
 236 [RFC 6347]:
 237      <https://tools.ietf.org/html/rfc6347>
 238
 239 [RFC 9000]:
 240      <https://tools.ietf.org/html/rfc9000>
 241
 242 [Binaries]:
 243     <https://wiki.openssl.org/index.php/Binaries>
 244     "List of third party OpenSSL binaries"
 245
 246 [OpenSSL Guide]:
 247     <https://www.openssl.org/docs/manmaster/man7/ossl-guide-introduction.html>
 248     "An introduction to OpenSSL"
 249
 250 <!-- Logos and Badges -->
 251
 252 [openssl logo]:
 253     doc/images/openssl.svg
 254     "OpenSSL Logo"
 255
 256 [github actions ci badge]:
 257     <https://github.com/openssl/openssl/workflows/GitHub%20CI/badge.svg>
 258     "GitHub Actions CI Status"
 259
 260 [github actions ci]:
 261     <https://github.com/openssl/openssl/actions?query=workflow%3A%22GitHub+CI%22>
 262     "GitHub Actions CI"
 263
 264 [appveyor badge]:
 265     <https://ci.appveyor.com/api/projects/status/8e10o7xfrg73v98f/branch/master?svg=true>
 266     "AppVeyor Build Status"
 267
 268 [appveyor jobs]:
 269     <https://ci.appveyor.com/project/openssl/openssl/branch/master>
 270     "AppVeyor Jobs"