|
Packit |
aea12f |
GnuTLS README -- Important introductory notes
|
|
Packit |
aea12f |
=============================================
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
GnuTLS implements the TLS/SSL (Transport Layer Security aka Secure
|
|
Packit |
aea12f |
Sockets Layer) protocol. GnuTLS is a GNU project. Additional
|
|
Packit |
aea12f |
information can be found at <https://www.gnutls.org/>.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
README
|
|
Packit |
aea12f |
======
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
This README is targeted for users of the library who build from
|
|
Packit |
aea12f |
sources but do not necessarily develop. If you are interested
|
|
Packit |
aea12f |
in developing and contributing to the GnuTLS project, please
|
|
Packit |
aea12f |
see README-alpha and visit
|
|
Packit |
aea12f |
https://www.gnutls.org/manual/html_node/Contributing.html.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
COMPILATION
|
|
Packit |
aea12f |
===========
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
A typical command sequence for building the library is shown below.
|
|
Packit |
aea12f |
A complete list of options available for configure can be found
|
|
Packit |
aea12f |
by running './configure --help'.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
```
|
|
Packit |
aea12f |
cd gnutls-<version>
|
|
Packit |
aea12f |
./configure --prefix=/usr
|
|
Packit |
aea12f |
make
|
|
Packit |
aea12f |
make check
|
|
Packit |
aea12f |
sudo make install
|
|
Packit |
aea12f |
```
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
The commands above build and install the static archive (libgnutls.a),
|
|
Packit |
aea12f |
the shared object (libgnutls.so), and additional binaries such as certtool
|
|
Packit |
aea12f |
and gnutls-cli.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
The library depends on libnettle and gmplib.
|
|
Packit |
aea12f |
* gmplib: for big number arithmetic, https://gmplib.org/
|
|
Packit |
aea12f |
* nettle: for cryptographic algorithms, https://www.lysator.liu.se/~nisse/nettle/
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
Optionally it may use the following libraries:
|
|
Packit |
aea12f |
* libtasn1: For ASN.1 parsing (a copy is included, if not found), https://www.gnu.org/software/libtasn1/
|
|
Packit |
aea12f |
* p11-kit: for smart card support, https://p11-glue.github.io/p11-glue/p11-kit.html
|
|
Packit |
aea12f |
* libtspi: for Trusted Platform Module (TPM) support, https://trousers.sourceforge.net/
|
|
Packit |
aea12f |
* libunbound: For DNSSEC/DANE support, https://unbound.net/
|
|
Packit |
aea12f |
* libz: For compression support, https://www.zlib.net/
|
|
Packit |
aea12f |
* libidn: For supporting internationalized DNS names (IDNA 2003), https://www.gnu.org/software/libidn/
|
|
Packit |
aea12f |
* libidn2: For supporting internationalized DNS names (IDNA 2008), https://www.gnu.org/software/libidn/#libidn2
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
To configure libnettle for installation and use by GnuTLS, a typical
|
|
Packit |
aea12f |
command sequence would be:
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
```
|
|
Packit |
aea12f |
cd nettle-<version>
|
|
Packit |
aea12f |
./configure --prefix=/usr --disable-openssl --enable-shared
|
|
Packit |
aea12f |
make
|
|
Packit |
aea12f |
sudo make install
|
|
Packit |
aea12f |
```
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
For the Nettle project, --enable-shared will instruct automake and
|
|
Packit |
aea12f |
friends to build and install both the static archive (libnettle.a)
|
|
Packit |
aea12f |
and the shared object (libnettle.so).
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
In case you are compiling for an embedded system, you can disable
|
|
Packit |
aea12f |
unneeded features of GnuTLS. In general, it is usually best not to
|
|
Packit |
aea12f |
disable anything (for future mailing list questions and possible bugs).
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
Depending on your installation, additional libraries, such as libtasn1
|
|
Packit |
aea12f |
and zlib, may be required.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
DOCUMENTATION
|
|
Packit |
aea12f |
=============
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
See the documentation in doc/ and online at
|
|
Packit |
aea12f |
https://www.gnutls.org/manual.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
EXAMPLES
|
|
Packit |
aea12f |
========
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
See the examples in doc/examples/ and online at 'How To Use GnuTLS in
|
|
Packit |
aea12f |
Applications' at https://www.gnutls.org/manual.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
SECURITY ADVISORIES
|
|
Packit |
aea12f |
===================
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
The project collects and publishes information on past security
|
|
Packit |
aea12f |
incidents and vulnerabilities. Open information exchange, including
|
|
Packit |
aea12f |
information which is [sometimes] suppressed in non-open or non-free
|
|
Packit |
aea12f |
projects, is one of the goals of the GnuTLS project. Please visit
|
|
Packit |
aea12f |
https://www.gnutls.org/security.html.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
MAILING LISTS
|
|
Packit |
aea12f |
=============
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
The GnuTLS project maintains mailing lists for users, developers, and
|
|
Packit |
aea12f |
commits. Please see https://www.gnutls.org/lists.html.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
LICENSING
|
|
Packit |
aea12f |
=========
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
See the [LICENSE](LICENSE) file.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
BUGS
|
|
Packit |
aea12f |
====
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
Thorough testing is very important and expensive. Often, the
|
|
Packit |
aea12f |
developers do not have access to a particular piece of hardware or
|
|
Packit |
aea12f |
configuration to reproduce a scenario. Notifying the developers about a
|
|
Packit |
aea12f |
possible bug will greatly help the project.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
If you believe you have found a bug, please report it to bugs@gnutls.org
|
|
Packit |
aea12f |
together with any applicable information.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
Applicable information would include why the issue is a GnuTLS bug (if
|
|
Packit |
aea12f |
not readily apparent), output from 'uname -a', the version of the library or
|
|
Packit |
aea12f |
tool being used, a stack trace if available ('bt full' if under gdb or
|
|
Packit |
aea12f |
valgrind output), and perhaps a network trace. Vague queries or piecemeal
|
|
Packit |
aea12f |
messages are difficult to act upon and don't help the development effort.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
Additional information can be found at the project's manual.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
PATCHES
|
|
Packit |
aea12f |
=======
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
Patches are welcome and encouraged. Patches can be submitted through the
|
|
Packit |
aea12f |
bug tracking system or the mailing list. When submitting patches, please
|
|
Packit |
aea12f |
be sure to use sources from the git repository, and preferably from the
|
|
Packit |
aea12f |
master branch. To create a patch for the project from a local git repository,
|
|
Packit |
aea12f |
please use the following commands. 'gnutls' should be the local directory
|
|
Packit |
aea12f |
of a previous git clone.
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
```
|
|
Packit |
aea12f |
cd gnutls
|
|
Packit |
aea12f |
git add the-file-you-modified.c another-file.c
|
|
Packit |
aea12f |
git commit the-file-you-modified.c another-file.c
|
|
Packit |
aea12f |
git format-patch
|
|
Packit |
aea12f |
```
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
For more information on use of Git, visit https://git-scm.com/
|
|
Packit |
aea12f |
|
|
Packit |
aea12f |
----------------------------------------------------------------------
|
|
Packit |
aea12f |
Copying and distribution of this file, with or without modification,
|
|
Packit |
aea12f |
are permitted in any medium without royalty provided the copyright
|
|
Packit |
aea12f |
notice and this notice are preserved.
|