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 - [OpenSSL 3.2](https://www.openssl.org/docs/man3.2)
 158
 159 Demos
 160 -----
 161
 162 The are numerous source code demos for using various OpenSSL capabilities in the
 163 [demos subfolder](./demos).
 164
 165 Wiki
 166 ----
 167
 168 There is a Wiki at [wiki.openssl.org] which is currently not very active.
 169 It contains a lot of useful information, not all of which is up-to-date.
 170
 171 License
 172 =======
 173
 174 OpenSSL is licensed under the Apache License 2.0, which means that
 175 you are free to get and use it for commercial and non-commercial
 176 purposes as long as you fulfill its conditions.
 177
 178 See the [LICENSE.txt](LICENSE.txt) file for more details.
 179
 180 Support
 181 =======
 182
 183 There are various ways to get in touch. The correct channel depends on
 184 your requirement. See the [SUPPORT](SUPPORT.md) file for more details.
 185
 186 Contributing
 187 ============
 188
 189 If you are interested and willing to contribute to the OpenSSL project,
 190 please take a look at the [CONTRIBUTING](CONTRIBUTING.md) file.
 191
 192 Legalities
 193 ==========
 194
 195 A number of nations restrict the use or export of cryptography. If you are
 196 potentially subject to such restrictions, you should seek legal advice before
 197 attempting to develop or distribute cryptographic code.
 198
 199 Copyright
 200 =========
 201
 202 Copyright (c) 1998-2024 The OpenSSL Project Authors
 203
 204 Copyright (c) 1995-1998 Eric A. Young, Tim J. Hudson
 205
 206 All rights reserved.
 207
 208 <!-- Links  -->
 209
 210 [www.openssl.org]:
 211     <https://www.openssl.org>
 212     "OpenSSL Homepage"
 213
 214 [git.openssl.org]:
 215     <https://git.openssl.org>
 216     "OpenSSL Git Repository"
 217
 218 [git.openssl.org]:
 219     <https://git.openssl.org>
 220     "OpenSSL Git Repository"
 221
 222 [github.com/openssl/openssl]:
 223     <https://github.com/openssl/openssl>
 224     "OpenSSL GitHub Mirror"
 225
 226 [wiki.openssl.org]:
 227     <https://wiki.openssl.org>
 228     "OpenSSL Wiki"
 229
 230 [ossl-guide-migration(7ossl)]:
 231     <https://www.openssl.org/docs/manmaster/man7/ossl-guide-migration.html>
 232     "OpenSSL Migration Guide"
 233
 234 [RFC 8446]:
 235      <https://tools.ietf.org/html/rfc8446>
 236
 237 [RFC 6347]:
 238      <https://tools.ietf.org/html/rfc6347>
 239
 240 [RFC 9000]:
 241      <https://tools.ietf.org/html/rfc9000>
 242
 243 [Binaries]:
 244     <https://wiki.openssl.org/index.php/Binaries>
 245     "List of third party OpenSSL binaries"
 246
 247 [OpenSSL Guide]:
 248     <https://www.openssl.org/docs/manmaster/man7/ossl-guide-introduction.html>
 249     "An introduction to OpenSSL"
 250
 251 <!-- Logos and Badges -->
 252
 253 [openssl logo]:
 254     doc/images/openssl.svg
 255     "OpenSSL Logo"
 256
 257 [github actions ci badge]:
 258     <https://github.com/openssl/openssl/workflows/GitHub%20CI/badge.svg>
 259     "GitHub Actions CI Status"
 260
 261 [github actions ci]:
 262     <https://github.com/openssl/openssl/actions?query=workflow%3A%22GitHub+CI%22>
 263     "GitHub Actions CI"
 264
 265 [appveyor badge]:
 266     <https://ci.appveyor.com/api/projects/status/8e10o7xfrg73v98f/branch/master?svg=true>
 267     "AppVeyor Build Status"
 268
 269 [appveyor jobs]:
 270     <https://ci.appveyor.com/project/openssl/openssl/branch/master>
 271     "AppVeyor Jobs"