xref: /freebsd/crypto/openssl/README.md (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
1*b077aed3SPierre ProncheryWelcome to the OpenSSL Project
2*b077aed3SPierre Pronchery==============================
3*b077aed3SPierre Pronchery
4*b077aed3SPierre Pronchery[![openssl logo]][www.openssl.org]
5*b077aed3SPierre Pronchery
6*b077aed3SPierre Pronchery[![github actions ci badge]][github actions ci]
7*b077aed3SPierre Pronchery[![appveyor badge]][appveyor jobs]
8*b077aed3SPierre Pronchery
9*b077aed3SPierre ProncheryOpenSSL is a robust, commercial-grade, full-featured Open Source Toolkit
10*b077aed3SPierre Proncheryfor the Transport Layer Security (TLS) protocol formerly known as the
11*b077aed3SPierre ProncherySecure Sockets Layer (SSL) protocol. The protocol implementation is based
12*b077aed3SPierre Proncheryon a full-strength general purpose cryptographic library, which can also
13*b077aed3SPierre Proncherybe used stand-alone.
14*b077aed3SPierre Pronchery
15*b077aed3SPierre ProncheryOpenSSL is descended from the SSLeay library developed by Eric A. Young
16*b077aed3SPierre Proncheryand Tim J. Hudson.
17*b077aed3SPierre Pronchery
18*b077aed3SPierre ProncheryThe official Home Page of the OpenSSL Project is [www.openssl.org].
19*b077aed3SPierre Pronchery
20*b077aed3SPierre ProncheryTable of Contents
21*b077aed3SPierre Pronchery=================
22*b077aed3SPierre Pronchery
23*b077aed3SPierre Pronchery - [Overview](#overview)
24*b077aed3SPierre Pronchery - [Download](#download)
25*b077aed3SPierre Pronchery - [Build and Install](#build-and-install)
26*b077aed3SPierre Pronchery - [Documentation](#documentation)
27*b077aed3SPierre Pronchery - [License](#license)
28*b077aed3SPierre Pronchery - [Support](#support)
29*b077aed3SPierre Pronchery - [Contributing](#contributing)
30*b077aed3SPierre Pronchery - [Legalities](#legalities)
31*b077aed3SPierre Pronchery
32*b077aed3SPierre ProncheryOverview
33*b077aed3SPierre Pronchery========
34*b077aed3SPierre Pronchery
35*b077aed3SPierre ProncheryThe OpenSSL toolkit includes:
36*b077aed3SPierre Pronchery
37*b077aed3SPierre Pronchery- **libssl**
38*b077aed3SPierre Pronchery  an implementation of all TLS protocol versions up to TLSv1.3 ([RFC 8446]).
39*b077aed3SPierre Pronchery
40*b077aed3SPierre Pronchery- **libcrypto**
41*b077aed3SPierre Pronchery  a full-strength general purpose cryptographic library. It constitutes the
42*b077aed3SPierre Pronchery  basis of the TLS implementation, but can also be used independently.
43*b077aed3SPierre Pronchery
44*b077aed3SPierre Pronchery- **openssl**
45*b077aed3SPierre Pronchery  the OpenSSL command line tool, a swiss army knife for cryptographic tasks,
46*b077aed3SPierre Pronchery  testing and analyzing. It can be used for
47*b077aed3SPierre Pronchery  - creation of key parameters
48*b077aed3SPierre Pronchery  - creation of X.509 certificates, CSRs and CRLs
49*b077aed3SPierre Pronchery  - calculation of message digests
50*b077aed3SPierre Pronchery  - encryption and decryption
51*b077aed3SPierre Pronchery  - SSL/TLS client and server tests
52*b077aed3SPierre Pronchery  - handling of S/MIME signed or encrypted mail
53*b077aed3SPierre Pronchery  - and more...
54*b077aed3SPierre Pronchery
55*b077aed3SPierre ProncheryDownload
56*b077aed3SPierre Pronchery========
57*b077aed3SPierre Pronchery
58*b077aed3SPierre ProncheryFor Production Use
59*b077aed3SPierre Pronchery------------------
60*b077aed3SPierre Pronchery
61*b077aed3SPierre ProncherySource code tarballs of the official releases can be downloaded from
62*b077aed3SPierre Pronchery[www.openssl.org/source](https://www.openssl.org/source).
63*b077aed3SPierre ProncheryThe OpenSSL project does not distribute the toolkit in binary form.
64*b077aed3SPierre Pronchery
65*b077aed3SPierre ProncheryHowever, for a large variety of operating systems precompiled versions
66*b077aed3SPierre Proncheryof the OpenSSL toolkit are available. In particular on Linux and other
67*b077aed3SPierre ProncheryUnix operating systems it is normally recommended to link against the
68*b077aed3SPierre Proncheryprecompiled shared libraries provided by the distributor or vendor.
69*b077aed3SPierre Pronchery
70*b077aed3SPierre ProncheryFor Testing and Development
71*b077aed3SPierre Pronchery---------------------------
72*b077aed3SPierre Pronchery
73*b077aed3SPierre ProncheryAlthough testing and development could in theory also be done using
74*b077aed3SPierre Proncherythe source tarballs, having a local copy of the git repository with
75*b077aed3SPierre Proncherythe entire project history gives you much more insight into the
76*b077aed3SPierre Proncherycode base.
77*b077aed3SPierre Pronchery
78*b077aed3SPierre ProncheryThe official OpenSSL Git Repository is located at [git.openssl.org].
79*b077aed3SPierre ProncheryThere is a GitHub mirror of the repository at [github.com/openssl/openssl],
80*b077aed3SPierre Proncherywhich is updated automatically from the former on every commit.
81*b077aed3SPierre Pronchery
82*b077aed3SPierre ProncheryA local copy of the Git Repository can be obtained by cloning it from
83*b077aed3SPierre Proncherythe original OpenSSL repository using
84*b077aed3SPierre Pronchery
85*b077aed3SPierre Pronchery    git clone git://git.openssl.org/openssl.git
86*b077aed3SPierre Pronchery
87*b077aed3SPierre Proncheryor from the GitHub mirror using
88*b077aed3SPierre Pronchery
89*b077aed3SPierre Pronchery    git clone https://github.com/openssl/openssl.git
90*b077aed3SPierre Pronchery
91*b077aed3SPierre ProncheryIf you intend to contribute to OpenSSL, either to fix bugs or contribute
92*b077aed3SPierre Proncherynew features, you need to fork the OpenSSL repository openssl/openssl on
93*b077aed3SPierre ProncheryGitHub and clone your public fork instead.
94*b077aed3SPierre Pronchery
95*b077aed3SPierre Pronchery    git clone https://github.com/yourname/openssl.git
96*b077aed3SPierre Pronchery
97*b077aed3SPierre ProncheryThis is necessary, because all development of OpenSSL nowadays is done via
98*b077aed3SPierre ProncheryGitHub pull requests. For more details, see [Contributing](#contributing).
99*b077aed3SPierre Pronchery
100*b077aed3SPierre ProncheryBuild and Install
101*b077aed3SPierre Pronchery=================
102*b077aed3SPierre Pronchery
103*b077aed3SPierre ProncheryAfter obtaining the Source, have a look at the [INSTALL](INSTALL.md) file for
104*b077aed3SPierre Proncherydetailed instructions about building and installing OpenSSL. For some
105*b077aed3SPierre Proncheryplatforms, the installation instructions are amended by a platform specific
106*b077aed3SPierre Proncherydocument.
107*b077aed3SPierre Pronchery
108*b077aed3SPierre Pronchery * [Notes for UNIX-like platforms](NOTES-UNIX.md)
109*b077aed3SPierre Pronchery * [Notes for Android platforms](NOTES-ANDROID.md)
110*b077aed3SPierre Pronchery * [Notes for Windows platforms](NOTES-WINDOWS.md)
111*b077aed3SPierre Pronchery * [Notes for the DOS platform with DJGPP](NOTES-DJGPP.md)
112*b077aed3SPierre Pronchery * [Notes for the OpenVMS platform](NOTES-VMS.md)
113*b077aed3SPierre Pronchery * [Notes on Perl](NOTES-PERL.md)
114*b077aed3SPierre Pronchery * [Notes on Valgrind](NOTES-VALGRIND.md)
115*b077aed3SPierre Pronchery
116*b077aed3SPierre ProncherySpecific notes on upgrading to OpenSSL 3.0 from previous versions can be found
117*b077aed3SPierre Proncheryin the [migration_guide(7ossl)] manual page.
118*b077aed3SPierre Pronchery
119*b077aed3SPierre ProncheryDocumentation
120*b077aed3SPierre Pronchery=============
121*b077aed3SPierre Pronchery
122*b077aed3SPierre ProncheryManual Pages
123*b077aed3SPierre Pronchery------------
124*b077aed3SPierre Pronchery
125*b077aed3SPierre ProncheryThe manual pages for the master branch and all current stable releases are
126*b077aed3SPierre Proncheryavailable online.
127*b077aed3SPierre Pronchery
128*b077aed3SPierre Pronchery- [OpenSSL master](https://www.openssl.org/docs/manmaster)
129*b077aed3SPierre Pronchery- [OpenSSL 3.0](https://www.openssl.org/docs/man3.0)
130*b077aed3SPierre Pronchery- [OpenSSL 1.1.1](https://www.openssl.org/docs/man1.1.1)
131*b077aed3SPierre Pronchery
132*b077aed3SPierre ProncheryWiki
133*b077aed3SPierre Pronchery----
134*b077aed3SPierre Pronchery
135*b077aed3SPierre ProncheryThere is a Wiki at [wiki.openssl.org] which is currently not very active.
136*b077aed3SPierre ProncheryIt contains a lot of useful information, not all of which is up to date.
137*b077aed3SPierre Pronchery
138*b077aed3SPierre ProncheryLicense
139*b077aed3SPierre Pronchery=======
140*b077aed3SPierre Pronchery
141*b077aed3SPierre ProncheryOpenSSL is licensed under the Apache License 2.0, which means that
142*b077aed3SPierre Proncheryyou are free to get and use it for commercial and non-commercial
143*b077aed3SPierre Proncherypurposes as long as you fulfill its conditions.
144*b077aed3SPierre Pronchery
145*b077aed3SPierre ProncherySee the [LICENSE.txt](LICENSE.txt) file for more details.
146*b077aed3SPierre Pronchery
147*b077aed3SPierre ProncherySupport
148*b077aed3SPierre Pronchery=======
149*b077aed3SPierre Pronchery
150*b077aed3SPierre ProncheryThere are various ways to get in touch. The correct channel depends on
151*b077aed3SPierre Proncheryyour requirement. see the [SUPPORT](SUPPORT.md) file for more details.
152*b077aed3SPierre Pronchery
153*b077aed3SPierre ProncheryContributing
154*b077aed3SPierre Pronchery============
155*b077aed3SPierre Pronchery
156*b077aed3SPierre ProncheryIf you are interested and willing to contribute to the OpenSSL project,
157*b077aed3SPierre Proncheryplease take a look at the [CONTRIBUTING](CONTRIBUTING.md) file.
158*b077aed3SPierre Pronchery
159*b077aed3SPierre ProncheryLegalities
160*b077aed3SPierre Pronchery==========
161*b077aed3SPierre Pronchery
162*b077aed3SPierre ProncheryA number of nations restrict the use or export of cryptography. If you are
163*b077aed3SPierre Proncherypotentially subject to such restrictions you should seek legal advice before
164*b077aed3SPierre Proncheryattempting to develop or distribute cryptographic code.
165*b077aed3SPierre Pronchery
166*b077aed3SPierre ProncheryCopyright
167*b077aed3SPierre Pronchery=========
168*b077aed3SPierre Pronchery
169*b077aed3SPierre ProncheryCopyright (c) 1998-2022 The OpenSSL Project
170*b077aed3SPierre Pronchery
171*b077aed3SPierre ProncheryCopyright (c) 1995-1998 Eric A. Young, Tim J. Hudson
172*b077aed3SPierre Pronchery
173*b077aed3SPierre ProncheryAll rights reserved.
174*b077aed3SPierre Pronchery
175*b077aed3SPierre Pronchery<!-- Links  -->
176*b077aed3SPierre Pronchery
177*b077aed3SPierre Pronchery[www.openssl.org]:
178*b077aed3SPierre Pronchery    <https://www.openssl.org>
179*b077aed3SPierre Pronchery    "OpenSSL Homepage"
180*b077aed3SPierre Pronchery
181*b077aed3SPierre Pronchery[git.openssl.org]:
182*b077aed3SPierre Pronchery    <https://git.openssl.org>
183*b077aed3SPierre Pronchery    "OpenSSL Git Repository"
184*b077aed3SPierre Pronchery
185*b077aed3SPierre Pronchery[git.openssl.org]:
186*b077aed3SPierre Pronchery    <https://git.openssl.org>
187*b077aed3SPierre Pronchery    "OpenSSL Git Repository"
188*b077aed3SPierre Pronchery
189*b077aed3SPierre Pronchery[github.com/openssl/openssl]:
190*b077aed3SPierre Pronchery    <https://github.com/openssl/openssl>
191*b077aed3SPierre Pronchery    "OpenSSL GitHub Mirror"
192*b077aed3SPierre Pronchery
193*b077aed3SPierre Pronchery[wiki.openssl.org]:
194*b077aed3SPierre Pronchery    <https://wiki.openssl.org>
195*b077aed3SPierre Pronchery    "OpenSSL Wiki"
196*b077aed3SPierre Pronchery
197*b077aed3SPierre Pronchery[migration_guide(7ossl)]:
198*b077aed3SPierre Pronchery    <https://www.openssl.org/docs/man3.0/man7/migration_guide.html>
199*b077aed3SPierre Pronchery    "OpenSSL Migration Guide"
200*b077aed3SPierre Pronchery
201*b077aed3SPierre Pronchery[RFC 8446]:
202*b077aed3SPierre Pronchery     <https://tools.ietf.org/html/rfc8446>
203*b077aed3SPierre Pronchery
204*b077aed3SPierre Pronchery<!-- Logos and Badges -->
205*b077aed3SPierre Pronchery
206*b077aed3SPierre Pronchery[openssl logo]:
207*b077aed3SPierre Pronchery    doc/images/openssl.svg
208*b077aed3SPierre Pronchery    "OpenSSL Logo"
209*b077aed3SPierre Pronchery
210*b077aed3SPierre Pronchery[github actions ci badge]:
211*b077aed3SPierre Pronchery    <https://github.com/openssl/openssl/workflows/GitHub%20CI/badge.svg>
212*b077aed3SPierre Pronchery    "GitHub Actions CI Status"
213*b077aed3SPierre Pronchery
214*b077aed3SPierre Pronchery[github actions ci]:
215*b077aed3SPierre Pronchery    <https://github.com/openssl/openssl/actions?query=workflow%3A%22GitHub+CI%22>
216*b077aed3SPierre Pronchery    "GitHub Actions CI"
217*b077aed3SPierre Pronchery
218*b077aed3SPierre Pronchery[appveyor badge]:
219*b077aed3SPierre Pronchery    <https://ci.appveyor.com/api/projects/status/8e10o7xfrg73v98f/branch/master?svg=true>
220*b077aed3SPierre Pronchery    "AppVeyor Build Status"
221*b077aed3SPierre Pronchery
222*b077aed3SPierre Pronchery[appveyor jobs]:
223*b077aed3SPierre Pronchery    <https://ci.appveyor.com/project/openssl/openssl/branch/master>
224*b077aed3SPierre Pronchery    "AppVeyor Jobs"
225