git.samba.org - gd/gnutls/blob - INSTALL.md

   1 GnuTLS README -- Important introductory notes
   2 =============================================
   3
   4 GnuTLS implements the TLS/SSL (Transport Layer Security aka Secure
   5 Sockets Layer) protocol.  GnuTLS is a GNU project.  Additional
   6 information can be found at <https://www.gnutls.org/>.
   7
   8
   9 README
  10 ======
  11
  12 This README is targeted for users of the library who build from
  13 sources but do not necessarily develop.  If you are interested
  14 in developing and contributing to the GnuTLS project, please
  15 see README-alpha and visit
  16 https://www.gnutls.org/manual/html_node/Contributing.html.
  17
  18
  19 COMPILATION
  20 ===========
  21
  22 A typical command sequence for building the library is shown below.
  23 A complete list of options available for configure can be found
  24 by running './configure --help'.
  25
  26 ```
  27     cd gnutls-<version>
  28     ./configure --prefix=/usr
  29     make
  30     make check
  31     sudo make install
  32 ```
  33
  34 The commands above build and install the static archive (libgnutls.a),
  35 the shared object (libgnutls.so), and additional binaries such as certtool
  36 and gnutls-cli.
  37
  38 The library depends on libnettle and gmplib.
  39 * gmplib: for big number arithmetic, https://gmplib.org/
  40 * nettle: for cryptographic algorithms, https://www.lysator.liu.se/~nisse/nettle/
  41
  42 Optionally it may use the following libraries:
  43 * libtasn1: For ASN.1 parsing (a copy is included, if not found), https://www.gnu.org/software/libtasn1/
  44 * p11-kit: for smart card support, https://p11-glue.github.io/p11-glue/p11-kit.html
  45 * libtspi: for Trusted Platform Module (TPM) support, https://trousers.sourceforge.net/
  46 * libunbound: For DNSSEC/DANE support, https://unbound.net/
  47 * libz: For compression support, https://www.zlib.net/
  48 * libidn: For supporting internationalized DNS names (IDNA 2003), https://www.gnu.org/software/libidn/
  49 * libidn2: For supporting internationalized DNS names (IDNA 2008), https://www.gnu.org/software/libidn/#libidn2
  50
  51 To configure libnettle for installation and use by GnuTLS, a typical
  52 command sequence would be:
  53
  54 ```
  55     cd nettle-<version>
  56     ./configure --prefix=/usr --disable-openssl --enable-shared
  57     make
  58     sudo make install
  59 ```
  60
  61 For the Nettle project, --enable-shared will instruct automake and
  62 friends to build and install both the static archive (libnettle.a)
  63 and the shared object (libnettle.so).
  64
  65 In case you are compiling for an embedded system, you can disable
  66 unneeded features of GnuTLS.  In general, it is usually best not to
  67 disable anything (for future mailing list questions and possible bugs).
  68
  69 Depending on your installation, additional libraries, such as libtasn1
  70 and zlib, may be required.
  71
  72
  73 DOCUMENTATION
  74 =============
  75
  76 See the documentation in doc/ and online at
  77 https://www.gnutls.org/manual.
  78
  79
  80 EXAMPLES
  81 ========
  82
  83 See the examples in doc/examples/ and online at 'How To Use GnuTLS in
  84 Applications' at https://www.gnutls.org/manual.
  85
  86
  87 SECURITY ADVISORIES
  88 ===================
  89
  90 The project collects and publishes information on past security
  91 incidents and vulnerabilities.  Open information exchange, including
  92 information which is [sometimes] suppressed in non-open or non-free
  93 projects, is one of the goals of the GnuTLS project.  Please visit
  94 https://www.gnutls.org/security.html.
  95
  96
  97 MAILING LISTS
  98 =============
  99
 100 The GnuTLS project maintains mailing lists for users, developers, and
 101 commits.  Please see https://www.gnutls.org/lists.html.
 102
 103
 104 LICENSING
 105 =========
 106
 107 See the [LICENSE](LICENSE) file.
 108
 109
 110 BUGS
 111 ====
 112
 113 Thorough testing is very important and expensive.  Often, the
 114 developers do not have access to a particular piece of hardware or
 115 configuration to reproduce a scenario.  Notifying the developers about a
 116 possible bug will greatly help the project.
 117
 118 If you believe you have found a bug, please report it to bugs@gnutls.org
 119 together with any applicable information.
 120
 121 Applicable information would include why the issue is a GnuTLS bug (if
 122 not readily apparent), output from 'uname -a', the version of the library or
 123 tool being used, a stack trace if available ('bt full' if under gdb or
 124 valgrind output), and perhaps a network trace.  Vague queries or piecemeal
 125 messages are difficult to act upon and don't help the development effort.
 126
 127 Additional information can be found at the project's manual.
 128
 129
 130 PATCHES
 131 =======
 132
 133 Patches are welcome and encouraged. Patches can be submitted through the
 134 bug tracking system or the mailing list.  When submitting patches, please
 135 be sure to use sources from the git repository, and preferably from the
 136 master branch.  To create a patch for the project from a local git repository,
 137 please use the following commands. 'gnutls' should be the local directory
 138 of a previous git clone.
 139
 140 ```
 141     cd gnutls
 142     git add the-file-you-modified.c another-file.c
 143     git commit the-file-you-modified.c another-file.c
 144     git format-patch
 145 ```
 146
 147 For more information on use of Git, visit https://git-scm.com/
 148
 149 ----------------------------------------------------------------------
 150 Copying and distribution of this file, with or without modification,
 151 are permitted in any medium without royalty provided the copyright
 152 notice and this notice are preserved.