mirror of https://github.com/openssl/openssl
doc: introduce some minimalistic markdown without essential changes
The goal is to transform the standard documents README, INSTALL, SUPPORT, CONTRIBUTING, ... from a pure text format into markdown format, but in such a way that the documentation remains nicely formatted an easy readable when viewed with an normal text editor. To achieve this goal, we use a special form of 'minimalistic' markdown which interferes as little as possible with the reading flow. * avoid [ATX headings][] and use [setext headings][] instead (works for `<h1>` and `<h2>` headings only). * avoid [inline links][] and use [reference links][] instead. * avoid [fenced code blocks][], use [indented-code-blocks][] instead. The transformation will take place in several steps. This commit introduces mostly changes the formatting and does not chang the content significantly. [ATX headings]: https://github.github.com/gfm/#atx-headings [setext headings]: https://github.github.com/gfm/#setext-headings [inline links]: https://github.github.com/gfm/#inline-link [reference links]: https://github.github.com/gfm/#reference-link [fenced code blocks]: https://github.github.com/gfm/#fenced-code-blocks [indented code blocks]: https://github.github.com/gfm/#indented-code-blocks Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org> (Merged from https://github.com/openssl/openssl/pull/10545)
This commit is contained in:
parent
2e07506a12
commit
5f8e6c50bd
|
@ -1,2 +1,8 @@
|
||||||
Please https://www.openssl.org/community/thanks.html for the current
|
Acknowlegements
|
||||||
acknowledgements.
|
===============
|
||||||
|
|
||||||
|
Please see our [Thanks!][] page for the current acknowledgements.
|
||||||
|
|
||||||
|
|
||||||
|
[Thanks!]: https://www.openssl.org/community/thanks.html
|
||||||
|
|
||||||
|
|
79
AUTHORS.md
79
AUTHORS.md
|
@ -1,35 +1,46 @@
|
||||||
# This is the list of OpenSSL authors for copyright purposes.
|
Authors
|
||||||
#
|
=======
|
||||||
# This does not necessarily list everyone who has contributed code, since in
|
|
||||||
# some cases, their employer may be the copyright holder. To see the full list
|
|
||||||
# of contributors, see the revision history in source control.
|
|
||||||
OpenSSL Software Services, Inc.
|
|
||||||
OpenSSL Software Foundation, Inc.
|
|
||||||
|
|
||||||
# Individuals
|
This is the list of OpenSSL authors for copyright purposes.
|
||||||
Andy Polyakov
|
It does not necessarily list everyone who has contributed code,
|
||||||
Ben Laurie
|
since in some cases, their employer may be the copyright holder.
|
||||||
Ben Kaduk
|
To see the full list of contributors, see the revision history in
|
||||||
Bernd Edlinger
|
source control.
|
||||||
Bodo Möller
|
|
||||||
David Benjamin
|
|
||||||
Emilia Käsper
|
Groups
|
||||||
Eric Young
|
------
|
||||||
Geoff Thorpe
|
|
||||||
Holger Reif
|
* OpenSSL Software Services, Inc.
|
||||||
Kurt Roeckx
|
* OpenSSL Software Foundation, Inc.
|
||||||
Lutz Jänicke
|
|
||||||
Mark J. Cox
|
|
||||||
Matt Caswell
|
Individuals
|
||||||
Matthias St. Pierre
|
-----------
|
||||||
Nils Larsch
|
|
||||||
Paul Dale
|
* Andy Polyakov
|
||||||
Paul C. Sutton
|
* Ben Laurie
|
||||||
Ralf S. Engelschall
|
* Ben Kaduk
|
||||||
Rich Salz
|
* Bernd Edlinger
|
||||||
Richard Levitte
|
* Bodo Möller
|
||||||
Stephen Henson
|
* David Benjamin
|
||||||
Steve Marquess
|
* Emilia Käsper
|
||||||
Tim Hudson
|
* Eric Young
|
||||||
Ulf Möller
|
* Geoff Thorpe
|
||||||
Viktor Dukhovni
|
* Holger Reif
|
||||||
|
* Kurt Roeckx
|
||||||
|
* Lutz Jänicke
|
||||||
|
* Mark J. Cox
|
||||||
|
* Matt Caswell
|
||||||
|
* Matthias St. Pierre
|
||||||
|
* Nils Larsch
|
||||||
|
* Paul Dale
|
||||||
|
* Paul C. Sutton
|
||||||
|
* Ralf S. Engelschall
|
||||||
|
* Rich Salz
|
||||||
|
* Richard Levitte
|
||||||
|
* Stephen Henson
|
||||||
|
* Steve Marquess
|
||||||
|
* Tim Hudson
|
||||||
|
* Ulf Möller
|
||||||
|
* Viktor Dukhovni
|
||||||
|
|
29289
CHANGES.md
29289
CHANGES.md
File diff suppressed because it is too large
Load Diff
|
@ -1,10 +1,14 @@
|
||||||
HOW TO CONTRIBUTE TO OpenSSL
|
HOW TO CONTRIBUTE TO OpenSSL
|
||||||
----------------------------
|
============================
|
||||||
|
|
||||||
(Please visit https://www.openssl.org/community/getting-started.html for
|
Please visit our [Getting Started][gs] page for other ideas about how to contribute.
|
||||||
other ideas about how to contribute.)
|
|
||||||
|
|
||||||
Development is done on GitHub, https://github.com/openssl/openssl.
|
[gs]: https://www.openssl.org/community/getting-started.html
|
||||||
|
|
||||||
|
|
||||||
|
Development is done on GitHub in the [openssl/openssl][gh] repository.
|
||||||
|
|
||||||
|
[gh]: https://github.com/openssl/openssl
|
||||||
|
|
||||||
To request new features or report bugs, please open an issue on GitHub
|
To request new features or report bugs, please open an issue on GitHub
|
||||||
|
|
||||||
|
@ -16,54 +20,57 @@ the same thing or there may be reasons why that feature isn't implemented.
|
||||||
To make it easier to review and accept your pull request, please follow these
|
To make it easier to review and accept your pull request, please follow these
|
||||||
guidelines:
|
guidelines:
|
||||||
|
|
||||||
1. Anything other than a trivial contribution requires a Contributor
|
1. Anything other than a trivial contribution requires a [Contributor
|
||||||
License Agreement (CLA), giving us permission to use your code. See
|
License Agreement][CLA] (CLA), giving us permission to use your code.
|
||||||
https://www.openssl.org/policies/cla.html for details. If your
|
If your contribution is too small to require a CLA (e.g. fixing a spelling
|
||||||
contribution is too small to require a CLA (e.g. fixing a spelling
|
mistake), place the text "`CLA: trivial`" on a line by itself separated by
|
||||||
mistake), place the text "CLA: trivial" on a line by itself separated by
|
|
||||||
an empty line from the rest of the commit message. It is not sufficient to
|
an empty line from the rest of the commit message. It is not sufficient to
|
||||||
only place the text in the GitHub pull request description.
|
only place the text in the GitHub pull request description.
|
||||||
|
|
||||||
To amend a missing "CLA: trivial" line after submission, do the following:
|
[CLA]: https://www.openssl.org/policies/cla.html
|
||||||
|
|
||||||
|
To amend a missing "`CLA: trivial`" line after submission, do the following:
|
||||||
|
```
|
||||||
git commit --amend
|
git commit --amend
|
||||||
[add the line, save and quit the editor]
|
[add the line, save and quit the editor]
|
||||||
git push -f
|
git push -f
|
||||||
|
```
|
||||||
2. All source files should start with the following text (with
|
2. All source files should start with the following text (with
|
||||||
appropriate comment characters at the start of each line and the
|
appropriate comment characters at the start of each line and the
|
||||||
year(s) updated):
|
year(s) updated):
|
||||||
|
```
|
||||||
Copyright 20xx-20yy The OpenSSL Project Authors. All Rights Reserved.
|
Copyright 20xx-20yy The OpenSSL Project Authors. All Rights Reserved.
|
||||||
|
|
||||||
Licensed under the Apache License 2.0 (the "License"). You may not use
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
||||||
this file except in compliance with the License. You can obtain a copy
|
this file except in compliance with the License. You can obtain a copy
|
||||||
in the file LICENSE in the source distribution or at
|
in the file LICENSE in the source distribution or at
|
||||||
https://www.openssl.org/source/license.html
|
https://www.openssl.org/source/license.html
|
||||||
|
```
|
||||||
|
|
||||||
3. Patches should be as current as possible; expect to have to rebase
|
3. Patches should be as current as possible; expect to have to rebase
|
||||||
often. We do not accept merge commits, you will have to remove them
|
often. We do not accept merge commits, you will have to remove them
|
||||||
(usually by rebasing) before it will be acceptable.
|
(usually by rebasing) before it will be acceptable.
|
||||||
|
|
||||||
4. Patches should follow our coding style (see
|
4. Patches should follow our [coding style][] and compile without warnings.
|
||||||
https://www.openssl.org/policies/codingstyle.html) and compile
|
Where gcc or clang is available you should use the
|
||||||
without warnings. Where gcc or clang is available you should use the
|
|
||||||
--strict-warnings Configure option. OpenSSL compiles on many varied
|
--strict-warnings Configure option. OpenSSL compiles on many varied
|
||||||
platforms: try to ensure you only use portable features. Clean builds
|
platforms: try to ensure you only use portable features. Clean builds
|
||||||
via Travis and AppVeyor are required, and they are started automatically
|
via Travis and AppVeyor are required, and they are started automatically
|
||||||
whenever a PR is created or updated.
|
whenever a PR is created or updated.
|
||||||
|
|
||||||
5. When at all possible, patches should include tests. These can
|
[coding style]: https://www.openssl.org/policies/codingstyle.html
|
||||||
|
|
||||||
|
5. When at all possible, patches should include tests. These can
|
||||||
either be added to an existing test, or completely new. Please see
|
either be added to an existing test, or completely new. Please see
|
||||||
test/README for information on the test framework.
|
test/README for information on the test framework.
|
||||||
|
|
||||||
6. New features or changed functionality must include
|
6. New features or changed functionality must include
|
||||||
documentation. Please look at the "pod" files in doc/man[1357] for
|
documentation. Please look at the "pod" files in doc/man[1357] for
|
||||||
examples of our style. Run "make doc-nits" to make sure that your
|
examples of our style. Run "make doc-nits" to make sure that your
|
||||||
documentation changes are clean.
|
documentation changes are clean.
|
||||||
|
|
||||||
7. For user visible changes (API changes, behaviour changes, ...),
|
7. For user visible changes (API changes, behaviour changes, ...),
|
||||||
consider adding a note in CHANGES. This could be a summarising
|
consider adding a note in [CHANGES](CHANGES). This could be a summarising
|
||||||
description of the change, and could explain the grander details.
|
description of the change, and could explain the grander details.
|
||||||
Have a look through existing entries for inspiration.
|
Have a look through existing entries for inspiration.
|
||||||
Please note that this is NOT simply a copy of git-log one-liners.
|
Please note that this is NOT simply a copy of git-log one-liners.
|
||||||
|
@ -72,8 +79,8 @@ guidelines:
|
||||||
with a specific release without having to sift through the higher
|
with a specific release without having to sift through the higher
|
||||||
noise ratio in git-log.
|
noise ratio in git-log.
|
||||||
|
|
||||||
8. For larger or more important user visible changes, as well as
|
8. For larger or more important user visible changes, as well as
|
||||||
security fixes, please add a line in NEWS. On exception, it might be
|
security fixes, please add a line in [NEWS](NEWS). On exception, it might be
|
||||||
worth adding a multi-line entry (such as the entry that announces all
|
worth adding a multi-line entry (such as the entry that announces all
|
||||||
the types that became opaque with OpenSSL 1.1.0).
|
the types that became opaque with OpenSSL 1.1.0).
|
||||||
This file helps users get a very quick summary of what comes with a
|
This file helps users get a very quick summary of what comes with a
|
||||||
|
|
8
FAQ.md
8
FAQ.md
|
@ -1,2 +1,6 @@
|
||||||
The FAQ is now maintained on the web:
|
Frequently Asked Questions (FAQ)
|
||||||
https://www.openssl.org/docs/faq.html
|
================================
|
||||||
|
|
||||||
|
The [Frequently Asked Questions][FAQ] are now maintained on the OpenSSL homepage.
|
||||||
|
|
||||||
|
[FAQ]: https://www.openssl.org/docs/faq.html
|
||||||
|
|
125
README.md
125
README.md
|
@ -1,36 +1,31 @@
|
||||||
|
Description
|
||||||
|
===========
|
||||||
|
|
||||||
Copyright (c) 1998-2018 The OpenSSL Project
|
The OpenSSL Project is a collaborative effort to develop a robust,
|
||||||
Copyright (c) 1995-1998 Eric A. Young, Tim J. Hudson
|
commercial-grade, fully featured, and Open Source toolkit implementing the
|
||||||
All rights reserved.
|
Transport Layer Security (TLS) protocols (including SSLv3) as well as a
|
||||||
|
full-strength general purpose cryptographic library.
|
||||||
|
|
||||||
DESCRIPTION
|
OpenSSL is descended from the SSLeay library developed by Eric A. Young
|
||||||
-----------
|
and Tim J. Hudson.
|
||||||
|
|
||||||
The OpenSSL Project is a collaborative effort to develop a robust,
|
The OpenSSL toolkit is licensed under the Apache License 2.0, which means
|
||||||
commercial-grade, fully featured, and Open Source toolkit implementing the
|
that you are free to get and use it for commercial and non-commercial
|
||||||
Transport Layer Security (TLS) protocols (including SSLv3) as well as a
|
purposes as long as you fulfill its conditions.
|
||||||
full-strength general purpose cryptographic library.
|
|
||||||
|
|
||||||
OpenSSL is descended from the SSLeay library developed by Eric A. Young
|
Overview
|
||||||
and Tim J. Hudson.
|
========
|
||||||
|
|
||||||
The OpenSSL toolkit is licensed under the Apache License 2.0, which means
|
The OpenSSL toolkit includes:
|
||||||
that you are free to get and use it for commercial and non-commercial
|
|
||||||
purposes as long as you fulfill its conditions.
|
|
||||||
|
|
||||||
OVERVIEW
|
* **libssl**
|
||||||
--------
|
|
||||||
|
|
||||||
The OpenSSL toolkit includes:
|
|
||||||
|
|
||||||
libssl (with platform specific naming):
|
|
||||||
Provides the client and server-side implementations for SSLv3 and TLS.
|
Provides the client and server-side implementations for SSLv3 and TLS.
|
||||||
|
|
||||||
libcrypto (with platform specific naming):
|
* **libcrypto:**
|
||||||
Provides general cryptographic and X.509 support needed by SSL/TLS but
|
Provides general cryptographic and X.509 support needed by SSL/TLS but
|
||||||
not logically part of it.
|
not logically part of it.
|
||||||
|
|
||||||
openssl:
|
* **openssl:**
|
||||||
A command line tool that can be used for:
|
A command line tool that can be used for:
|
||||||
Creation of key parameters
|
Creation of key parameters
|
||||||
Creation of X.509 certificates, CSRs and CRLs
|
Creation of X.509 certificates, CSRs and CRLs
|
||||||
|
@ -40,53 +35,71 @@
|
||||||
Handling of S/MIME signed or encrypted mail
|
Handling of S/MIME signed or encrypted mail
|
||||||
And more...
|
And more...
|
||||||
|
|
||||||
INSTALLATION
|
Installation
|
||||||
------------
|
============
|
||||||
|
|
||||||
See the appropriate file:
|
See the appropriate file:
|
||||||
INSTALL Linux, Unix, Windows, OpenVMS, ...
|
|
||||||
NOTES.* INSTALL addendums for different platforms
|
|
||||||
|
|
||||||
SUPPORT
|
* [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)
|
||||||
|
|
||||||
See the OpenSSL website www.openssl.org for details on how to obtain
|
Support
|
||||||
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).
|
|
||||||
|
|
||||||
If you have any problems with OpenSSL then please take the following steps
|
See the OpenSSL website www.openssl.org for details on how to obtain
|
||||||
first:
|
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).
|
||||||
|
|
||||||
- Download the latest version from the repository
|
If you have any problems with OpenSSL then please take the following steps
|
||||||
to see if the problem has already been addressed
|
first:
|
||||||
- Configure with no-asm
|
|
||||||
- Remove compiler optimization flags
|
|
||||||
|
|
||||||
If you wish to report a bug then please include the following information
|
- Download the latest version from the repository
|
||||||
and create an issue on GitHub:
|
to see if the problem has already been addressed
|
||||||
|
- Configure with no-asm
|
||||||
|
- Remove compiler optimization flags
|
||||||
|
|
||||||
- OpenSSL version: output of 'openssl version -a'
|
If you wish to report a bug then please include the following information
|
||||||
- Configuration data: output of 'perl configdata.pm --dump'
|
and create an issue on GitHub:
|
||||||
- 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)
|
|
||||||
|
|
||||||
Just because something doesn't work the way you expect does not mean it
|
- OpenSSL version: output of 'openssl version -a'
|
||||||
is necessarily a bug in OpenSSL. Use the openssl-users email list for this type
|
- Configuration data: output of 'perl configdata.pm --dump'
|
||||||
of query.
|
- 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)
|
||||||
|
|
||||||
HOW TO CONTRIBUTE TO OpenSSL
|
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.
|
||||||
|
|
||||||
See CONTRIBUTING
|
How to contribute to OpenSSL
|
||||||
|
============================
|
||||||
|
|
||||||
LEGALITIES
|
See [CONTRIBUTING](CONTRIBUTING.md)
|
||||||
----------
|
|
||||||
|
Legalities
|
||||||
|
==========
|
||||||
|
|
||||||
A number of nations restrict the use or export of cryptography. If you
|
A number of nations restrict the use or export of cryptography. If you
|
||||||
are potentially subject to such restrictions you should seek competent
|
are potentially subject to such restrictions you should seek competent
|
||||||
professional legal advice before attempting to develop or distribute
|
professional legal advice before attempting to develop or distribute
|
||||||
cryptographic code.
|
cryptographic code.
|
||||||
|
|
||||||
|
|
||||||
|
Copyright
|
||||||
|
=========
|
||||||
|
|
||||||
|
Copyright (c) 1998-2018 The OpenSSL Project
|
||||||
|
|
||||||
|
Copyright (c) 1995-1998 Eric A. Young, Tim J. Hudson
|
||||||
|
|
||||||
|
All rights reserved.
|
||||||
|
|
Loading…
Reference in New Issue