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