← Back to branch summary

~ubuntu-branches/ubuntu/maverick/gnutls26/maverick-updates

« back to all changes in this revision

Viewing changes to doc/gnutls.info-1

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Metzler
  • Date: 2009-04-14 14:23:19 UTC
  • mfrom: (1.1.5 upstream)
  • Revision ID: james.westby@ubuntu.com-20090414142319-ok7xejzbqkofno1q
Tags: 2.6.5-1
* Sync sections in debian/control with override file. libgnutls26-dbg is
  section debug, guile-gnutls is section lisp.
* New upstream version. (Needed for Libtasn1-3 2.0)
* New patch 15_tasn1inpc.diff. Make sure libtasn1 is listed in Libs.private.
* Standards-Version: 3.8.1, no changes required.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/gnutls.info-1
1
 
This is gnutls.info, produced by makeinfo version 4.11 from gnutls.texi.
 
1
This is gnutls.info, produced by makeinfo version 4.13 from gnutls.texi.
2
2
 
3
 
This manual is last updated 15 September 2008 for version 2.4.2 of GNU
4
 
TLS.
 
3
This manual is last updated 11 April 2009 for version 2.6.5 of GNU TLS.
5
4
 
6
5
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free
7
6
Software Foundation, Inc.
35
34
GNU TLS
36
35
*******
37
36
 
38
 
This manual is last updated 15 September 2008 for version 2.4.2 of GNU
39
 
TLS.
 
37
This manual is last updated 11 April 2009 for version 2.6.5 of GNU TLS.
40
38
 
41
39
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free
42
40
Software Foundation, Inc.
144
142
 
145
143
If you are interested, please write to:
146
144
 
147
 
 
148
145
Simon Josefsson Datakonsult
149
146
Hagagatan 24
150
147
113 47 Stockholm
165
162
 
166
163
`http://www.gnutls.org/download.html'
167
164
 
168
 
The latest version is stored in a file, e.g., `gnutls-2.4.2.tar.gz'
169
 
where the `2.4.2' value is the highest version number in the directory.
 
165
The latest version is stored in a file, e.g., `gnutls-2.6.5.tar.gz'
 
166
where the `2.6.5' value is the highest version number in the directory.
170
167
 
171
168
GnuTLS uses a Linux-like development cycle: even minor version numbers
172
169
indicate a stable release and a odd minor version number indicates a
328
325
the TLS 1.1 and SSL 3.0 protocols (*Note Introduction to TLS::, for a
329
326
more detailed description of the protocols), accompanied with the
330
327
required framework for authentication and public key infrastructure.
331
 
The library is available under the GNU Lesser GPL license(1).
332
328
Important features of the GnuTLS library include:
333
329
 
334
330
   * Support for TLS 1.0, TLS 1.1, and SSL 3.0 protocols.
347
343
 
348
344
 
349
345
Additionally GnuTLS provides a limited emulation API for the widely
350
 
used OpenSSL(2) library, to ease integration with existing applications.
 
346
used OpenSSL(1) library, to ease integration with existing applications.
351
347
 
352
348
GnuTLS consists of three independent parts, namely the "TLS protocol
353
 
part", the "Certificate part", and the "Crypto backend" part.  The `TLS
354
 
protocol part' is the actual protocol implementation, and is entirely
355
 
implemented within the GnuTLS library.  The `Certificate part' consists
356
 
of the certificate parsing, and verification functions which is
357
 
partially implemented in the GnuTLS library.  The Libtasn1(3), a
 
349
part", the "Certificate part", and the "Cryptographic backend" part.
 
350
The `TLS protocol part' is the actual protocol implementation, and is
 
351
entirely implemented within the GnuTLS library.  The `Certificate part'
 
352
consists of the certificate parsing, and verification functions which
 
353
is partially implemented in the GnuTLS library.  The Libtasn1(2), a
358
354
library which offers ASN.1 parsing capabilities, is used for the X.509
359
 
certificate parsing functions.  A smaller version of OpenCDK(4) is used
360
 
for the OpenPGP key support in GnuTLS.  The "Crypto backend" is
361
 
provided by the Libgcrypt(5) library.
 
355
certificate parsing functions.  A smaller version of OpenCDK(3) is used
 
356
for the OpenPGP key support in GnuTLS.  The "Cryptographic backend" is
 
357
provided by the Libgcrypt(4) library(5).
362
358
 
363
359
In order to ease integration in embedded systems, parts of the GnuTLS
364
360
library can be disabled at compile time. That way a small library, with
373
369
 
374
370
---------- Footnotes ----------
375
371
 
376
 
(1) A copy of the license is included in the distribution
377
 
 
378
 
(2) `http://www.openssl.org/'
379
 
 
380
 
(3) `ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/'
381
 
 
382
 
(4) `ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/'
383
 
 
384
 
(5) `ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/'
 
372
(1) `http://www.openssl.org/'
 
373
 
 
374
(2) `ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/'
 
375
 
 
376
(3) `ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/'
 
377
 
 
378
(4) `ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/'
 
379
 
 
380
(5) On current versions of GnuTLS it is possible to override the
 
381
default crypto backend. Check *note Cryptographic Backend:: for details
385
382
 
386
383
 
387
384
File: gnutls.info,  Node: General Idea,  Next: Error handling,  Up: The Library
1017
1014
TLS are selected in a conservative way and such catastrophic
1018
1015
breakthroughs or failures are believed to be unlikely.
1019
1016
 
 
1017
NIST publication SP 800-57 [NISTSP80057] (*note Bibliography::)
 
1018
contains a similar table that extends beyond the key sizes given above.
 
1019
 
 
1020
Bits of     Symmetric key  RSA key size,  ECC key size
 
1021
security    algorithms     DSA, DH and    
 
1022
                           SRP prime size 
 
1023
80          2TDEA          1024           160-223
 
1024
112         3DES           2048           224-255
 
1025
128         AES-128        3072           256-383
 
1026
192         AES-192        7680           384-511
 
1027
256         AES-256        15360          512+
 
1028
 
 
1029
The recommendations are fairly consistent.
 
1030
 
1020
1031
 
1021
1032
File: gnutls.info,  Node: On SSL 2 and older protocols,  Next: On Record Padding,  Prev: Selecting cryptographic key sizes,  Up: Introduction to TLS
1022
1033
 
1864
1875
1.000.000 Euro  to Bad Inc.
1865
1876
 
1866
1877
For a hash algorithm to be called cryptographic the following three
1867
 
requirements must hold
1868
 
  1. Preimage resistance. That means the algorithm must be one way and
 
1878
requirements must hold:
 
1879
 
 
1880
  1. Preimage resistance.  That means the algorithm must be one way and
1869
1881
     given the output of the hash function H(x), it is impossible to
1870
1882
     calculate x.
1871
1883
 
1872
 
  2. 2nd preimage resistance. That means that given a pair x,y with
 
1884
  2. 2nd preimage resistance.  That means that given a pair x,y with
1873
1885
     y=H(x) it is impossible to calculate an x' such that y=H(x').
1874
1886
 
1875
 
  3. Collision resistance. That means that it is impossible to
 
1887
  3. Collision resistance.  That means that it is impossible to
1876
1888
     calculate random x and x' such H(x')=H(x).
1877
1889
 
1878
1890
The last two requirements in the list are the most important in digital
1896
1908
as well.  The collision attacks on SHA-1 may also get better, given the
1897
1909
new interest in tools for creating them.
1898
1910
 
1899
 
5.3.1 Supported Algorithms
1900
 
--------------------------
1901
 
 
1902
 
The available digital signature algorithms in GnuTLS are listed below:
1903
 
 
1904
 
`RSA'
1905
 
     RSA is public key cryptosystem designed by Ronald Rivest, Adi
1906
 
     Shamir and Leonard Adleman. It can be used with any hash functions.
1907
 
 
1908
 
`DSA'
1909
 
     DSA is the USA's Digital Signature Standard. It uses only the SHA-1
1910
 
     hash algorithm.
1911
 
 
1912
 
 
1913
 
The supported cryptographic hash algorithms are:
1914
 
 
1915
 
`MD2'
1916
 
     MD2 is a cryptographic hash algorithm designed by Ron Rivest. It is
1917
 
     optimized for 8-bit processors. Outputs 128 bits of data. There
1918
 
     are no known weaknesses of this algorithm but since this algorithm
1919
 
     is rarely used and not really studied it should not be used today.
1920
 
 
1921
 
`MD5'
1922
 
     MD5 is a cryptographic hash algorithm designed by Ron Rivest.
1923
 
     Outputs 128 bits of data. It is considered to be broken.
1924
 
 
1925
 
`SHA-1'
1926
 
     SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
1927
 
     bits of data. It is also considered to be broken, though no
1928
 
     practical attacks have been found.
1929
 
 
1930
 
`RMD160'
1931
 
     RIPEMD is a cryptographic hash algorithm developed in the
1932
 
     framework of the EU project RIPE. Outputs 160 bits of data.
1933
 
 
1934
 
 
1935
 
5.3.2 Trading Security for Interoperability
 
1911
5.3.1 Trading Security for Interoperability
1936
1912
-------------------------------------------
1937
1913
 
1938
1914
If you connect to a server and use GnuTLS' functions to verify the
2151
2127
* Menu:
2152
2128
 
2153
2129
* Headers::
 
2130
* Initialization::
2154
2131
* Version check::
2155
2132
* Debugging::
2156
2133
* Building the source::
2157
2134
 
2158
2135
 
2159
 
File: gnutls.info,  Node: Headers,  Next: Version check,  Up: Preparation
 
2136
File: gnutls.info,  Node: Headers,  Next: Initialization,  Up: Preparation
2160
2137
 
2161
2138
7.1.1 Headers
2162
2139
-------------
2169
2146
including the header file `gnutls/extra.h' in your programs.
2170
2147
 
2171
2148
 
2172
 
File: gnutls.info,  Node: Version check,  Next: Debugging,  Prev: Headers,  Up: Preparation
2173
 
 
2174
 
7.1.2 Version Check
 
2149
File: gnutls.info,  Node: Initialization,  Next: Version check,  Prev: Headers,  Up: Preparation
 
2150
 
 
2151
7.1.2 Initialization
 
2152
--------------------
 
2153
 
 
2154
GnuTLS must be initialized before it can be used.  The library is
 
2155
initialized by calling *note gnutls_global_init::.  The resources
 
2156
allocated by the initialization process can be released if the
 
2157
application no longer has a need to call GnuTLS functions, this is done
 
2158
by calling *note gnutls_global_deinit::.
 
2159
 
 
2160
The extra functionality of the GnuTLS-extra library is available after
 
2161
calling *note gnutls_global_init_extra::.
 
2162
 
 
2163
In order to take advantage of the internationalisation features in
 
2164
GnuTLS, such as translated error messages, the application must set the
 
2165
current locale using `setlocale' before initializing GnuTLS.
 
2166
 
 
2167
 
 
2168
File: gnutls.info,  Node: Version check,  Next: Debugging,  Prev: Initialization,  Up: Preparation
 
2169
 
 
2170
7.1.3 Version Check
2175
2171
-------------------
2176
2172
 
2177
2173
It is often desirable to check that the version of `gnutls' used is
2184
2180
 
2185
2181
File: gnutls.info,  Node: Debugging,  Next: Building the source,  Prev: Version check,  Up: Preparation
2186
2182
 
2187
 
7.1.3 Debugging
 
2183
7.1.4 Debugging
2188
2184
---------------
2189
2185
 
2190
2186
In many cases things may not go as expected and further information, to
2196
2192
 
2197
2193
File: gnutls.info,  Node: Building the source,  Prev: Debugging,  Up: Preparation
2198
2194
 
2199
 
7.1.4 Building the Source
 
2195
7.1.5 Building the Source
2200
2196
-------------------------
2201
2197
 
2202
2198
If you want to compile a source file including the `gnutls/gnutls.h'
2242
2238
7.2 Multi-Threaded Applications
2243
2239
===============================
2244
2240
 
2245
 
Although the GnuTLS library is thread safe by design, some parts of the
2246
 
crypto backend, such as the random generator, are not. Since _libgcrypt
2247
 
1.1.92_ there was an automatic detection of the thread library used by
2248
 
the application, so most applications wouldn't need to do any changes
2249
 
to ensure thread-safety. Due to the unportability of the automatic
2250
 
thread detection, this was removed from later releases of _libgcrypt_,
2251
 
so applications have now to register callback functions to ensure
2252
 
proper locking in sensitive parts of _libgcrypt_.
 
2241
Although the GnuTLS library is thread safe by design, some parts of
 
2242
Libgcrypt, such as the random generator, are not.  Applications have to
 
2243
register callback functions to ensure proper locking in the sensitive
 
2244
parts of _libgcrypt_.
2253
2245
 
2254
2246
There are helper macros to help you properly initialize the libraries.
2255
2247
Examples are shown below.
2335
2327
 * notice and this notice are preserved.
2336
2328
 */
2337
2329
 
2338
 
#if HAVE_CONFIG_H
 
2330
#ifdef HAVE_CONFIG_H
2339
2331
# include <config.h>
2340
2332
#endif
2341
2333
 
2376
2368
  gnutls_init (&session, GNUTLS_CLIENT);
2377
2369
 
2378
2370
  /* Use default priorities */
2379
 
  gnutls_priority_set_direct (session, "PERFORMANCE:+ANON-DH:!ARCFOUR-128", NULL);
 
2371
  gnutls_priority_set_direct (session, "PERFORMANCE:+ANON-DH:!ARCFOUR-128",
 
2372
                              NULL);
2380
2373
 
2381
2374
  /* put the anonymous credentials to the current session
2382
2375
   */
2459
2452
 * notice and this notice are preserved.
2460
2453
 */
2461
2454
 
2462
 
#if HAVE_CONFIG_H
 
2455
#ifdef HAVE_CONFIG_H
2463
2456
# include <config.h>
2464
2457
#endif
2465
2458
 
2506
2499
 
2507
2500
  /* Use default priorities */
2508
2501
  ret = gnutls_priority_set_direct (session, "PERFORMANCE", &err);
2509
 
  if (ret < 0) {
2510
 
    if (ret == GNUTLS_E_INVALID_REQUEST) {
2511
 
      fprintf(stderr, "Syntax error at: %s\n", err);
 
2502
  if (ret < 0)
 
2503
    {
 
2504
      if (ret == GNUTLS_E_INVALID_REQUEST)
 
2505
        {
 
2506
          fprintf (stderr, "Syntax error at: %s\n", err);
 
2507
        }
 
2508
      exit (1);
2512
2509
    }
2513
 
    exit(1);
2514
 
  }
2515
2510
 
2516
2511
  /* put the x509 credentials to the current session
2517
2512
   */
2593
2588
 * notice and this notice are preserved.
2594
2589
 */
2595
2590
 
2596
 
#if HAVE_CONFIG_H
 
2591
#ifdef HAVE_CONFIG_H
2597
2592
# include <config.h>
2598
2593
#endif
2599
2594
 
2727
2722
 * notice and this notice are preserved.
2728
2723
 */
2729
2724
 
2730
 
#if HAVE_CONFIG_H
 
2725
#ifdef HAVE_CONFIG_H
2731
2726
# include <config.h>
2732
2727
#endif
2733
2728
 
2833
2828
 * notice and this notice are preserved.
2834
2829
 */
2835
2830
 
2836
 
#if HAVE_CONFIG_H
 
2831
#ifdef HAVE_CONFIG_H
2837
2832
# include <config.h>
2838
2833
#endif
2839
2834
 
3075
3070
 * notice and this notice are preserved.
3076
3071
 */
3077
3072
 
3078
 
#if HAVE_CONFIG_H
 
3073
#ifdef HAVE_CONFIG_H
3079
3074
# include <config.h>
3080
3075
#endif
3081
3076
 
3124
3119
  long filelen;
3125
3120
  void *ptr;
3126
3121
 
3127
 
  if (!(f = fopen(file, "r"))
3128
 
      || fseek(f, 0, SEEK_END) != 0
3129
 
      || (filelen = ftell(f)) < 0
3130
 
      || fseek(f, 0, SEEK_SET) != 0
3131
 
      || !(ptr = malloc((size_t)filelen))
3132
 
      || fread(ptr, 1, (size_t)filelen, f) < (size_t)filelen)
 
3122
  if (!(f = fopen (file, "r"))
 
3123
      || fseek (f, 0, SEEK_END) != 0
 
3124
      || (filelen = ftell (f)) < 0
 
3125
      || fseek (f, 0, SEEK_SET) != 0
 
3126
      || !(ptr = malloc ((size_t) filelen))
 
3127
      || fread (ptr, 1, (size_t) filelen, f) < (size_t) filelen)
3133
3128
    {
3134
3129
      return loaded_file;
3135
3130
    }
3136
3131
 
3137
3132
  loaded_file.data = ptr;
3138
 
  loaded_file.size = (unsigned int)filelen;
 
3133
  loaded_file.size = (unsigned int) filelen;
3139
3134
  return loaded_file;
3140
3135
}
3141
3136
 
3142
 
static void unload_file(gnutls_datum_t data)
 
3137
static void
 
3138
unload_file (gnutls_datum_t data)
3143
3139
{
3144
 
  free(data.data);
 
3140
  free (data.data);
3145
3141
}
3146
3142
 
3147
3143
/* Load the certificate and the private key.
3210
3206
  gnutls_certificate_allocate_credentials (&xcred);
3211
3207
 
3212
3208
  /* priorities */
3213
 
  gnutls_priority_init( &priorities_cache, "NORMAL", NULL);
 
3209
  gnutls_priority_init (&priorities_cache, "NORMAL", NULL);
3214
3210
 
3215
3211
 
3216
3212
  /* sets the trusted cas file
3281
3277
  gnutls_deinit (session);
3282
3278
 
3283
3279
  gnutls_certificate_free_credentials (xcred);
3284
 
  gnutls_priority_deinit( priorities_cache);
 
3280
  gnutls_priority_deinit (priorities_cache);
3285
3281
 
3286
3282
  gnutls_global_deinit ();
3287
3283
 
3368
3364
 * notice and this notice are preserved.
3369
3365
 */
3370
3366
 
3371
 
#if HAVE_CONFIG_H
 
3367
#ifdef HAVE_CONFIG_H
3372
3368
# include <config.h>
3373
3369
#endif
3374
3370
 
3529
3525
 * notice and this notice are preserved.
3530
3526
 */
3531
3527
 
3532
 
#if HAVE_CONFIG_H
 
3528
#ifdef HAVE_CONFIG_H
3533
3529
# include <config.h>
3534
3530
#endif
3535
3531
 
3666
3662
The following client is a simple client which uses the TLS/IA extension
3667
3663
to authenticate with the server.
3668
3664
 
3669
 
/* Copyright 2007 Free Software Foundation
 
3665
/* Copyright 2007, 2008 Free Software Foundation
3670
3666
 *
3671
3667
 * Copying and distribution of this file, with or without modification,
3672
3668
 * are permitted in any medium without royalty provided the copyright
3673
3669
 * notice and this notice are preserved.
3674
3670
 */
3675
3671
 
3676
 
#if HAVE_CONFIG_H
 
3672
#ifdef HAVE_CONFIG_H
3677
3673
# include <config.h>
3678
3674
#endif
3679
3675
 
3697
3693
extern int tcp_connect (void);
3698
3694
extern void tcp_close (int sd);
3699
3695
 
3700
 
int
 
3696
static int
3701
3697
client_avp (gnutls_session_t session, void *ptr,
3702
 
           const char *last, size_t lastlen,
3703
 
           char **new, size_t *newlen)
 
3698
            const char *last, size_t lastlen, char **new, size_t * newlen)
3704
3699
{
3705
3700
 
3706
3701
  if (last)
3707
 
    printf ("- received %d bytes AVP: `%.*s'\n",
3708
 
            lastlen, lastlen, last);
 
3702
    printf ("- received %d bytes AVP: `%.*s'\n", lastlen, lastlen, last);
3709
3703
  else
3710
3704
    printf ("- new application phase\n");
3711
3705
 
3844
3838
The following client is a simple example of a client client utilizing
3845
3839
the GnuTLS C++ API.
3846
3840
 
3847
 
#if HAVE_CONFIG_H
 
3841
#ifdef HAVE_CONFIG_H
3848
3842
# include <config.h>
3849
3843
#else
3850
3844
#endif
3852
3846
#include <stdexcept>
3853
3847
#include <gnutls/gnutls.h>
3854
3848
#include <gnutls/gnutlsxx.h>
3855
 
 
3856
 
#include <string.h> /* for strlen */
 
3849
#include <cstring> /* for strlen */
3857
3850
 
3858
3851
/* A very basic TLS client, with anonymous authentication.
3859
3852
 * written by Eduardo Villanueva Che.
3963
3956
 * notice and this notice are preserved.
3964
3957
 */
3965
3958
 
3966
 
#if HAVE_CONFIG_H
 
3959
#ifdef HAVE_CONFIG_H
3967
3960
# include <config.h>
3968
3961
#endif
3969
3962
 
4042
4035
This example is a very simple echo server which supports X.509
4043
4036
authentication, using the RSA ciphersuites.
4044
4037
 
4045
 
/* Copyright 2007 Free Software Foundation
 
4038
/* Copyright 2007, 2008 Free Software Foundation
4046
4039
 *
4047
4040
 * Copying and distribution of this file, with or without modification,
4048
4041
 * are permitted in any medium without royalty provided the copyright
4049
4042
 * notice and this notice are preserved.
4050
4043
 */
4051
4044
 
4052
 
#if HAVE_CONFIG_H
 
4045
#ifdef HAVE_CONFIG_H
4053
4046
# include <config.h>
4054
4047
#endif
4055
4048
 
4063
4056
#include <string.h>
4064
4057
#include <unistd.h>
4065
4058
#include <gnutls/gnutls.h>
4066
 
#include <gcrypt.h> /* for gcry_control */
 
4059
#include <gcrypt.h>             /* for gcry_control */
4067
4060
 
4068
4061
#define KEYFILE "key.pem"
4069
4062
#define CERTFILE "cert.pem"
4084
4077
gnutls_certificate_credentials_t x509_cred;
4085
4078
gnutls_priority_t priority_cache;
4086
4079
 
4087
 
gnutls_session_t
 
4080
static gnutls_session_t
4088
4081
initialize_tls_session (void)
4089
4082
{
4090
4083
  gnutls_session_t session;
4102
4095
  /* Set maximum compatibility mode. This is only suggested on public webservers
4103
4096
   * that need to trade security for compatibility
4104
4097
   */
4105
 
  gnutls_session_enable_compatibility_mode( session);
 
4098
  gnutls_session_enable_compatibility_mode (session);
4106
4099
 
4107
4100
  return session;
4108
4101
}
4159
4152
 
4160
4153
  generate_dh_params ();
4161
4154
 
4162
 
  gnutls_priority_init( &priority_cache, "NORMAL", NULL);
 
4155
  gnutls_priority_init (&priority_cache, "NORMAL", NULL);
4163
4156
 
4164
4157
 
4165
4158
  gnutls_certificate_set_dh_params (x509_cred, dh_params);
4245
4238
  close (listen_sd);
4246
4239
 
4247
4240
  gnutls_certificate_free_credentials (x509_cred);
4248
 
  gnutls_priority_deinit(priority_cache);
 
4241
  gnutls_priority_deinit (priority_cache);
4249
4242
 
4250
4243
  gnutls_global_deinit ();
4251
4244
 
4270
4263
 * notice and this notice are preserved.
4271
4264
 */
4272
4265
 
4273
 
#if HAVE_CONFIG_H
 
4266
#ifdef HAVE_CONFIG_H
4274
4267
# include <config.h>
4275
4268
#endif
4276
4269
 
4284
4277
#include <string.h>
4285
4278
#include <unistd.h>
4286
4279
#include <gnutls/gnutls.h>
4287
 
#include <gcrypt.h> /* for gcry_control */
 
4280
#include <gcrypt.h>             /* for gcry_control */
4288
4281
 
4289
4282
#define KEYFILE "key.pem"
4290
4283
#define CERTFILE "cert.pem"
4312
4305
 
4313
4306
#define TLS_SESSION_CACHE 50
4314
4307
 
4315
 
gnutls_session_t
 
4308
static gnutls_session_t
4316
4309
initialize_tls_session (void)
4317
4310
{
4318
4311
  gnutls_session_t session;
4321
4314
 
4322
4315
  /* Use the default priorities, plus, export cipher suites.
4323
4316
   */
4324
 
  gnutls_priority_set_direct( session, "EXPORT", NULL);
 
4317
  gnutls_priority_set_direct (session, "EXPORT", NULL);
4325
4318
 
4326
4319
  gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, cert_cred);
4327
4320
 
4355
4348
  "KRipli8Lk7hV+XmT7Jde6qgNdArb9P90c1nQQdXDPqcdKB5EaxR3O8qXtDoj+4AW\n"
4356
4349
  "dr0gekNsZIHx0rkHhxdGGludMuaI+HdIVEUjtSSw1X1ep3onddLs+gMs+9v1L7N4\n"
4357
4350
  "YWAnkATleuavh05zA85TKZzMBBx7wwjYKlaY86jQw4JxrjX46dv7tpS1yAPYn3rk\n"
4358
 
  "Nd4jbVJfVHWbZeNy/NaO8g+nER+eSv9zAgEC\n"
4359
 
  "-----END DH PARAMETERS-----\n";
 
4351
  "Nd4jbVJfVHWbZeNy/NaO8g+nER+eSv9zAgEC\n" "-----END DH PARAMETERS-----\n";
4360
4352
 
4361
 
int
 
4353
static int
4362
4354
generate_dh_params (void)
4363
4355
{
4364
 
gnutls_datum_t dparams = { srp_dh_group2048, sizeof( srp_dh_group2048) };
 
4356
  gnutls_datum_t dparams = { srp_dh_group2048, sizeof (srp_dh_group2048) };
4365
4357
  /* Here instead of generating Diffie Hellman parameters (for use with DHE
4366
4358
   * kx algorithms) we import them.
4367
4359
   */
4654
4646
have a server that supports both X.509 and OpenPGP certificates-- but
4655
4647
we separated them to keep these examples as simple as possible.
4656
4648
 
4657
 
/* Copyright 2007 Free Software Foundation
 
4649
/* Copyright 2007, 2008 Free Software Foundation
4658
4650
 *
4659
4651
 * Copying and distribution of this file, with or without modification,
4660
4652
 * are permitted in any medium without royalty provided the copyright
4661
4653
 * notice and this notice are preserved.
4662
4654
 */
4663
4655
 
4664
 
#if HAVE_CONFIG_H
 
4656
#ifdef HAVE_CONFIG_H
4665
4657
# include <config.h>
4666
4658
#endif
4667
4659
 
4710
4702
  return 0;
4711
4703
}
4712
4704
 
4713
 
gnutls_session_t
 
4705
static gnutls_session_t
4714
4706
initialize_tls_session (void)
4715
4707
{
4716
4708
  gnutls_session_t session;
4717
4709
 
4718
4710
  gnutls_init (&session, GNUTLS_SERVER);
4719
4711
 
4720
 
  gnutls_priority_set_direct(session, "NORMAL", NULL);
 
4712
  gnutls_priority_set_direct (session, "NORMAL", NULL);
4721
4713
 
4722
4714
  /* request client certificate if any.
4723
4715
   */
4749
4741
  gnutls_global_init ();
4750
4742
 
4751
4743
  gnutls_certificate_allocate_credentials (&cred);
4752
 
  gnutls_certificate_set_openpgp_keyring_file (cred, RINGFILE, GNUTLS_OPENPGP_FMT_BASE64);
 
4744
  gnutls_certificate_set_openpgp_keyring_file (cred, RINGFILE,
 
4745
                                               GNUTLS_OPENPGP_FMT_BASE64);
4753
4746
 
4754
 
  gnutls_certificate_set_openpgp_key_file (cred, CERTFILE, KEYFILE, GNUTLS_OPENPGP_FMT_BASE64);
 
4747
  gnutls_certificate_set_openpgp_key_file (cred, CERTFILE, KEYFILE,
 
4748
                                           GNUTLS_OPENPGP_FMT_BASE64);
4755
4749
 
4756
4750
  generate_dh_params ();
4757
4751
 
4855
4849
to combine this functionality with a certificate server. Here it is
4856
4850
separate for simplicity.
4857
4851
 
4858
 
/* Copyright 2007 Free Software Foundation
 
4852
/* Copyright 2007, 2008 Free Software Foundation
4859
4853
 *
4860
4854
 * Copying and distribution of this file, with or without modification,
4861
4855
 * are permitted in any medium without royalty provided the copyright
4862
4856
 * notice and this notice are preserved.
4863
4857
 */
4864
4858
 
4865
 
#if HAVE_CONFIG_H
 
4859
#ifdef HAVE_CONFIG_H
4866
4860
# include <config.h>
4867
4861
#endif
4868
4862
 
4897
4891
gnutls_srp_server_credentials_t srp_cred;
4898
4892
gnutls_certificate_credentials_t cert_cred;
4899
4893
 
4900
 
gnutls_session_t
 
4894
static gnutls_session_t
4901
4895
initialize_tls_session (void)
4902
4896
{
4903
4897
  gnutls_session_t session;
5047
5041
This example server support anonymous authentication, and could be used
5048
5042
to serve the example client for anonymous authentication.
5049
5043
 
5050
 
/* Copyright 2007 Free Software Foundation
 
5044
/* Copyright 2007, 2008 Free Software Foundation
5051
5045
 *
5052
5046
 * Copying and distribution of this file, with or without modification,
5053
5047
 * are permitted in any medium without royalty provided the copyright
5054
5048
 * notice and this notice are preserved.
5055
5049
 */
5056
5050
 
5057
 
#if HAVE_CONFIG_H
 
5051
#ifdef HAVE_CONFIG_H
5058
5052
# include <config.h>
5059
5053
#endif
5060
5054
 
5082
5076
/* These are global */
5083
5077
gnutls_anon_server_credentials_t anoncred;
5084
5078
 
5085
 
gnutls_session_t
 
5079
static gnutls_session_t
5086
5080
initialize_tls_session (void)
5087
5081
{
5088
5082
  gnutls_session_t session;
5255
5249
 * notice and this notice are preserved.
5256
5250
 */
5257
5251
 
5258
 
#if HAVE_CONFIG_H
 
5252
#ifdef HAVE_CONFIG_H
5259
5253
# include <config.h>
5260
5254
#endif
5261
5255
 
5307
5301
 * notice and this notice are preserved.
5308
5302
 */
5309
5303
 
5310
 
#if HAVE_CONFIG_H
 
5304
#ifdef HAVE_CONFIG_H
5311
5305
# include <config.h>
5312
5306
#endif
5313
5307
 
5428
5422
 * notice and this notice are preserved.
5429
5423
 */
5430
5424
 
5431
 
#if HAVE_CONFIG_H
 
5425
#ifdef HAVE_CONFIG_H
5432
5426
# include <config.h>
5433
5427
#endif
5434
5428
 
5526
5520
 * notice and this notice are preserved.
5527
5521
 */
5528
5522
 
5529
 
#if HAVE_CONFIG_H
 
5523
#ifdef HAVE_CONFIG_H
5530
5524
# include <config.h>
5531
5525
#endif
5532
5526
 
5722
5716
This is a program to generate X.509 certificates, certificate requests,
5723
5717
CRLs and private keys.
5724
5718
 
5725
 
 
5726
5719
Certtool help
5727
5720
Usage: certtool [options]
5728
5721
     -s, --generate-self-signed
5783
5776
     -d, --debug LEVEL        specify the debug level. Default is 1.
5784
5777
     -h, --help               shows this help text
5785
5778
     -v, --version            shows the program's version
5786
 
     --copyright              shows the program's license
5787
5779
 
5788
5780
The program can be used interactively or non interactively by
5789
5781
specifying the `--template' command line option. See below for an
5924
5916
 
5925
5917
     # A dnsname in case of a WWW server.
5926
5918
     #dns_name = "www.none.org"
 
5919
     #dns_name = "www.morethanone.org"
5927
5920
 
5928
5921
     # An IP address in case of a server.
5929
5922
     #ip_address = "192.168.1.1"
5978
5971
computer.  It sets up a TLS connection and forwards data from the
5979
5972
standard input to the secured socket and vice versa.
5980
5973
 
5981
 
 
5982
5974
GNU TLS test client
5983
5975
Usage:  gnutls-cli [options] hostname
5984
5976
 
6024
6016
                              algorithms  and modes.
6025
6017
     -h, --help               prints this help
6026
6018
     -v, --version            prints the program's version number
6027
 
     --copyright              prints the program's license
6028
6019
 
6029
6020
To connect to a server using PSK authentication, you may use something
6030
6021
like:
6139
6130
 
6140
6131
Simple server program that listens to incoming TLS connections.
6141
6132
 
6142
 
 
6143
6133
GNU TLS test server
6144
6134
Usage: gnutls-serv [options]
6145
6135
 
6179
6169
                              algorithms  and modes.
6180
6170
     -h, --help               prints this help
6181
6171
     -v, --version            prints the program's version number
6182
 
     --copyright              prints the program's license
6183
6172
 
6184
6173
8.4.1 Setting Up a Test HTTPS Server
6185
6174
------------------------------------
6365
6354
 
6366
6355
This is a program to manage PSK username and keys.
6367
6356
 
6368
 
 
6369
6357
PSKtool help
6370
6358
Usage : psktool [options]
6371
6359
     -u, --username username
6894
6882
 
6895
6883
 -- Function: void gnutls_certificate_get_x509_cas
6896
6884
          (gnutls_certificate_credentials_t SC, gnutls_x509_crt_t **
6897
 
          X509_CA_LIST, unsigned int* NCAS)
 
6885
          X509_CA_LIST, unsigned int * NCAS)
6898
6886
     SC: is an `gnutls_certificate_credentials_t' structure.
6899
6887
 
6900
6888
     X509_CA_LIST: will point to the CA list. Should be treated as
6912
6900
 
6913
6901
 -- Function: void gnutls_certificate_get_x509_crls
6914
6902
          (gnutls_certificate_credentials_t SC, gnutls_x509_crl_t **
6915
 
          X509_CRL_LIST, unsigned int* NCRLS)
 
6903
          X509_CRL_LIST, unsigned int * NCRLS)
6916
6904
     SC: is an `gnutls_certificate_credentials_t' structure.
6917
6905
 
6918
6906
     X509_CRL_LIST: the exported CRL list. Should be treated as constant
7334
7322
------------------------------
7335
7323
 
7336
7324
 -- Function: gnutls_certificate_type_t gnutls_certificate_type_get_id
7337
 
          (const char* NAME)
 
7325
          (const char * NAME)
7338
7326
     NAME: is a certificate type name
7339
7327
 
7340
7328
     The names are compared in a case insensitive way.
7341
7329
 
7342
 
     *Returns:* an id of the specified in a string certificate type, or
7343
 
     `GNUTLS_CRT_UNKNOWN' on error.
 
7330
     *Returns:* an `gnutls_certificate_type_t' for the specified in a
 
7331
     string certificate type, or `GNUTLS_CRT_UNKNOWN' on error.
7344
7332
 
7345
7333
gnutls_certificate_type_get_name
7346
7334
--------------------------------
7470
7458
--------------------
7471
7459
 
7472
7460
 -- Function: gnutls_cipher_algorithm_t gnutls_cipher_get_id (const
7473
 
          char* NAME)
 
7461
          char * NAME)
 
7462
     NAME: is a MAC algorithm name
 
7463
 
7474
7464
     The names are compared in a case insensitive way.
7475
7465
 
7476
7466
     *Returns:* return a `gnutls_cipher_algorithm_t' value
7596
7586
-------------------------
7597
7587
 
7598
7588
 -- Function: gnutls_compression_method_t gnutls_compression_get_id
7599
 
          (const char* NAME)
 
7589
          (const char * NAME)
 
7590
     NAME: is a compression method name
 
7591
 
7600
7592
     The names are compared in a case insensitive way.
7601
7593
 
7602
7594
     *Returns:* an id of the specified in a string compression method,
7700
7692
     For GNUTLS_CRD_CERTIFICATE cred should be
7701
7693
     gnutls_certificate_credentials_t.
7702
7694
 
7703
 
gnutls_crypto_cipher_register
7704
 
-----------------------------
7705
 
 
7706
 
 -- Function: int gnutls_crypto_cipher_register
7707
 
          (gnutls_cipher_algorithm_t ALGORITHM, int PRIORITY,
7708
 
          gnutls_crypto_cipher_st* S)
 
7695
gnutls_crypto_bigint_register2
 
7696
------------------------------
 
7697
 
 
7698
 -- Function: int gnutls_crypto_bigint_register2 (int PRIORITY, int
 
7699
          VERSION, gnutls_crypto_bigint_st * S)
 
7700
     PRIORITY: is the priority of the interface
 
7701
 
 
7702
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
 
7703
 
 
7704
     S: is a structure holding new interface's data
 
7705
 
 
7706
     This function will register an interface for gnutls to operate on
 
7707
     big integers. Any interface registered will override the included
 
7708
     interface. The interface with the lowest priority will be used by
 
7709
     gnutls.
 
7710
 
 
7711
     Note that the bigint interface must interoperate with the public
 
7712
     key interface. Thus if this interface is updated the
 
7713
     `gnutls_crypto_pk_register()' should also be used.
 
7714
 
 
7715
     This function should be called before `gnutls_global_init()'.
 
7716
 
 
7717
     For simplicity you can use the convenience
 
7718
     `gnutls_crypto_bigint_register()' macro.
 
7719
 
 
7720
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
 
7721
 
 
7722
     *Since:* 2.6.0
 
7723
 
 
7724
gnutls_crypto_cipher_register2
 
7725
------------------------------
 
7726
 
 
7727
 -- Function: int gnutls_crypto_cipher_register2 (int PRIORITY, int
 
7728
          VERSION, gnutls_crypto_cipher_st * S)
 
7729
     PRIORITY: is the priority of the cipher interface
 
7730
 
 
7731
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
 
7732
 
 
7733
     S: is a structure holding new interface's data
 
7734
 
 
7735
     This function will register a cipher interface to be used by
 
7736
     gnutls. Any interface registered will override the included engine
 
7737
     and by convention kernel implemented interfaces should have
 
7738
     priority of 90. The interface with the lowest priority will be used
 
7739
     by gnutls.
 
7740
 
 
7741
     This function should be called before `gnutls_global_init()'.
 
7742
 
 
7743
     For simplicity you can use the convenience
 
7744
     `gnutls_crypto_cipher_register()' macro.
 
7745
 
 
7746
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
 
7747
 
 
7748
     *Since:* 2.6.0
 
7749
 
 
7750
gnutls_crypto_digest_register2
 
7751
------------------------------
 
7752
 
 
7753
 -- Function: int gnutls_crypto_digest_register2 (int PRIORITY, int
 
7754
          VERSION, gnutls_crypto_digest_st * S)
 
7755
     PRIORITY: is the priority of the digest interface
 
7756
 
 
7757
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
 
7758
 
 
7759
     S: is a structure holding new interface's data
 
7760
 
 
7761
     This function will register a digest interface to be used by
 
7762
     gnutls. Any interface registered will override the included engine
 
7763
     and by convention kernel implemented interfaces should have
 
7764
     priority of 90. The interface with the lowest priority will be used
 
7765
     by gnutls.
 
7766
 
 
7767
     This function should be called before `gnutls_global_init()'.
 
7768
 
 
7769
     For simplicity you can use the convenience
 
7770
     `gnutls_crypto_digest_register()' macro.
 
7771
 
 
7772
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
 
7773
 
 
7774
     *Since:* 2.6.0
 
7775
 
 
7776
gnutls_crypto_mac_register2
 
7777
---------------------------
 
7778
 
 
7779
 -- Function: int gnutls_crypto_mac_register2 (int PRIORITY, int
 
7780
          VERSION, gnutls_crypto_mac_st * S)
 
7781
     PRIORITY: is the priority of the mac interface
 
7782
 
 
7783
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
 
7784
 
 
7785
     S: is a structure holding new interface's data
 
7786
 
 
7787
     This function will register a mac interface to be used by gnutls.
 
7788
     Any interface registered will override the included engine and by
 
7789
     convention kernel implemented interfaces should have priority of
 
7790
     90. The interface with the lowest priority will be used by gnutls.
 
7791
 
 
7792
     This function should be called before `gnutls_global_init()'.
 
7793
 
 
7794
     For simplicity you can use the convenience
 
7795
     `gnutls_crypto_mac_register()' macro.
 
7796
 
 
7797
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
 
7798
 
 
7799
     *Since:* 2.6.0
 
7800
 
 
7801
gnutls_crypto_pk_register2
 
7802
--------------------------
 
7803
 
 
7804
 -- Function: int gnutls_crypto_pk_register2 (int PRIORITY, int
 
7805
          VERSION, gnutls_crypto_pk_st * S)
 
7806
     PRIORITY: is the priority of the interface
 
7807
 
 
7808
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
 
7809
 
 
7810
     S: is a structure holding new interface's data
 
7811
 
 
7812
     This function will register an interface for gnutls to operate on
 
7813
     public key operations. Any interface registered will override the
 
7814
     included interface. The interface with the lowest priority will be
 
7815
     used by gnutls.
 
7816
 
 
7817
     Note that the bigint interface must interoperate with the bigint
 
7818
     interface. Thus if this interface is updated the
 
7819
     `gnutls_crypto_bigint_register()' should also be used.
 
7820
 
 
7821
     This function should be called before `gnutls_global_init()'.
 
7822
 
 
7823
     For simplicity you can use the convenience
 
7824
     `gnutls_crypto_pk_register()' macro.
 
7825
 
 
7826
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
 
7827
 
 
7828
     *Since:* 2.6.0
 
7829
 
 
7830
gnutls_crypto_rnd_register2
 
7831
---------------------------
 
7832
 
 
7833
 -- Function: int gnutls_crypto_rnd_register2 (int PRIORITY, int
 
7834
          VERSION, gnutls_crypto_rnd_st * S)
 
7835
     PRIORITY: is the priority of the generator
 
7836
 
 
7837
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
 
7838
 
 
7839
     S: is a structure holding new generator's data
 
7840
 
 
7841
     This function will register a random generator to be used by
 
7842
     gnutls.  Any generator registered will override the included
 
7843
     generator and by convention kernel implemented generators have
 
7844
     priority of 90.  The generator with the lowest priority will be
 
7845
     used by gnutls.
 
7846
 
 
7847
     This function should be called before `gnutls_global_init()'.
 
7848
 
 
7849
     For simplicity you can use the convenience
 
7850
     `gnutls_crypto_rnd_register()' macro.
 
7851
 
 
7852
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
 
7853
 
 
7854
     *Since:* 2.6.0
 
7855
 
 
7856
gnutls_crypto_single_cipher_register2
 
7857
-------------------------------------
 
7858
 
 
7859
 -- Function: int gnutls_crypto_single_cipher_register2
 
7860
          (gnutls_cipher_algorithm_t ALGORITHM, int PRIORITY, int
 
7861
          VERSION, gnutls_crypto_single_cipher_st * S)
7709
7862
     ALGORITHM: is the gnutls algorithm identifier
7710
7863
 
7711
7864
     PRIORITY: is the priority of the algorithm
7712
7865
 
 
7866
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
 
7867
 
7713
7868
     S: is a structure holding new cipher's data
7714
7869
 
7715
7870
     This function will register a cipher algorithm to be used by
7716
 
     gnutls. Any algorithm registered will override the included
 
7871
     gnutls.  Any algorithm registered will override the included
7717
7872
     algorithms and by convention kernel implemented algorithms have
7718
 
     priority of 90. The algorithm with the lowest priority will be
 
7873
     priority of 90.  The algorithm with the lowest priority will be
7719
7874
     used by gnutls.
7720
7875
 
7721
7876
     This function should be called before `gnutls_global_init()'.
7722
7877
 
 
7878
     For simplicity you can use the convenience
 
7879
     `gnutls_crypto_single_cipher_register()' macro.
 
7880
 
7723
7881
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
7724
7882
 
7725
 
gnutls_crypto_digest_register
7726
 
-----------------------------
7727
 
 
7728
 
 -- Function: int gnutls_crypto_digest_register
7729
 
          (gnutls_digest_algorithm_t ALGORITHM, int PRIORITY,
7730
 
          gnutls_crypto_digest_st* S)
 
7883
     *Since:* 2.6.0
 
7884
 
 
7885
gnutls_crypto_single_digest_register2
 
7886
-------------------------------------
 
7887
 
 
7888
 -- Function: int gnutls_crypto_single_digest_register2
 
7889
          (gnutls_digest_algorithm_t ALGORITHM, int PRIORITY, int
 
7890
          VERSION, gnutls_crypto_single_digest_st * S)
7731
7891
     ALGORITHM: is the gnutls algorithm identifier
7732
7892
 
7733
7893
     PRIORITY: is the priority of the algorithm
7734
7894
 
 
7895
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
 
7896
 
7735
7897
     S: is a structure holding new algorithms's data
7736
7898
 
7737
 
     This function will register a digest (hash) algorithm to be used
7738
 
     by gnutls. Any algorithm registered will override the included
 
7899
     This function will register a digest (hash) algorithm to be used by
 
7900
     gnutls.  Any algorithm registered will override the included
7739
7901
     algorithms and by convention kernel implemented algorithms have
7740
 
     priority of 90. The algorithm with the lowest priority will be
 
7902
     priority of 90.  The algorithm with the lowest priority will be
7741
7903
     used by gnutls.
7742
7904
 
7743
7905
     This function should be called before `gnutls_global_init()'.
7744
7906
 
 
7907
     For simplicity you can use the convenience
 
7908
     `gnutls_crypto_single_digest_register()' macro.
 
7909
 
7745
7910
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
7746
7911
 
7747
 
gnutls_crypto_mac_register
7748
 
--------------------------
7749
 
 
7750
 
 -- Function: int gnutls_crypto_mac_register (gnutls_mac_algorithm_t
7751
 
          ALGORITHM, int PRIORITY, gnutls_crypto_mac_st* S)
 
7912
     *Since:* 2.6.0
 
7913
 
 
7914
gnutls_crypto_single_mac_register2
 
7915
----------------------------------
 
7916
 
 
7917
 -- Function: int gnutls_crypto_single_mac_register2
 
7918
          (gnutls_mac_algorithm_t ALGORITHM, int PRIORITY, int VERSION,
 
7919
          gnutls_crypto_single_mac_st * S)
7752
7920
     ALGORITHM: is the gnutls algorithm identifier
7753
7921
 
7754
7922
     PRIORITY: is the priority of the algorithm
 
7923
 
 
7924
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7755
7925
 
7756
7926
     S: is a structure holding new algorithms's data
7757
7927
 
7762
7932
 
7763
7933
     This function should be called before `gnutls_global_init()'.
7764
7934
 
7765
 
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
7766
 
 
7767
 
gnutls_crypto_rnd_register
7768
 
--------------------------
7769
 
 
7770
 
 -- Function: int gnutls_crypto_rnd_register (int PRIORITY,
7771
 
          gnutls_crypto_rnd_st* S)
7772
 
     PRIORITY: is the priority of the generator
7773
 
 
7774
 
     S: is a structure holding new generator's data
7775
 
 
7776
 
     This function will register a random generator to be used by
7777
 
     gnutls. Any generator registered will override the included
7778
 
     generator and by convention kernel implemented generators have
7779
 
     priority of 90. The generator with the lowest priority will be
7780
 
     used by gnutls.
7781
 
 
7782
 
     This function should be called before `gnutls_global_init()'.
7783
 
 
7784
 
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
 
7935
     For simplicity you can use the convenience
 
7936
     `gnutls_crypto_single_mac_register()' macro.
 
7937
 
 
7938
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
 
7939
 
 
7940
     *Since:* 2.6.0
7785
7941
 
7786
7942
gnutls_db_check_entry
7787
7943
---------------------
8138
8294
---------------------
8139
8295
 
8140
8296
 -- Function: int gnutls_error_is_fatal (int ERROR)
8141
 
     ERROR: is an error returned by a gnutls function. Error should be
8142
 
     a negative value.
8143
 
 
8144
 
     If a function returns a negative value you may feed that value to
8145
 
     this function to see if it is fatal. Returns 1 for a fatal error 0
8146
 
     otherwise. However you may want to check the error code manually,
8147
 
     since some non-fatal errors to the protocol may be fatal for you
8148
 
     (your program).
8149
 
 
8150
 
     This is only useful if you are dealing with errors from the record
8151
 
     layer or the handshake layer.
8152
 
 
8153
 
     For positive `error' values, 0 is returned.
 
8297
     ERROR: is a GnuTLS error code, a negative value
 
8298
 
 
8299
     If a GnuTLS function returns a negative value you may feed that
 
8300
     value to this function to see if the error condition is fatal.
 
8301
 
 
8302
     Note that you may want to check the error code manually, since some
 
8303
     non-fatal errors to the protocol may be fatal for you program.
 
8304
 
 
8305
     This function is only useful if you are dealing with errors from
 
8306
     the record layer or the handshake layer.
 
8307
 
 
8308
     *Returns:* 1 if the error code is fatal, for positive `error'
 
8309
     values, 0 is returned.  For unknown `error' values, -1 is returned.
8154
8310
 
8155
8311
gnutls_error_to_alert
8156
8312
---------------------
8171
8327
 
8172
8328
     *Returns:* the alert code to use for a particular error code.
8173
8329
 
 
8330
gnutls_ext_register
 
8331
-------------------
 
8332
 
 
8333
 -- Function: int gnutls_ext_register (int TYPE, const char * NAME,
 
8334
          gnutls_ext_parse_type_t PARSE_TYPE, gnutls_ext_recv_func
 
8335
          RECV_FUNC, gnutls_ext_send_func SEND_FUNC)
 
8336
     TYPE: the 16-bit integer referring to the extension type
 
8337
 
 
8338
     NAME: human printable name of the extension used for debugging
 
8339
 
 
8340
     PARSE_TYPE: either `GNUTLS_EXT_TLS' or `GNUTLS_EXT_APPLICATION'.
 
8341
 
 
8342
     RECV_FUNC: a function to receive extension data
 
8343
 
 
8344
     SEND_FUNC: a function to send extension data
 
8345
 
 
8346
     This function is used to register a new TLS extension handler.
 
8347
 
 
8348
     *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code.
 
8349
 
 
8350
     *Since:* 2.6.0
 
8351
 
8174
8352
gnutls_fingerprint
8175
8353
------------------
8176
8354
 
8512
8690
gnutls_kx_get_id
8513
8691
----------------
8514
8692
 
8515
 
 -- Function: gnutls_kx_algorithm_t gnutls_kx_get_id (const char* NAME)
 
8693
 -- Function: gnutls_kx_algorithm_t gnutls_kx_get_id (const char * NAME)
 
8694
     NAME: is a KX name
 
8695
 
8516
8696
     Convert a string to a `gnutls_kx_algorithm_t' value.  The names are
8517
8697
     compared in a case insensitive way.
8518
8698
 
8573
8753
gnutls_mac_get_id
8574
8754
-----------------
8575
8755
 
8576
 
 -- Function: gnutls_mac_algorithm_t gnutls_mac_get_id (const char*
 
8756
 -- Function: gnutls_mac_algorithm_t gnutls_mac_get_id (const char *
8577
8757
          NAME)
 
8758
     NAME: is a MAC algorithm name
 
8759
 
8578
8760
     Convert a string to a `gnutls_mac_algorithm_t' value.  The names
8579
8761
     are compared in a case insensitive way.
8580
8762
 
8810
8992
-------------
8811
8993
 
8812
8994
 -- Function: void gnutls_perror (int ERROR)
8813
 
     ERROR: is an error returned by a gnutls function. Error is always
8814
 
     a negative value.
 
8995
     ERROR: is a GnuTLS error code, a negative value
8815
8996
 
8816
8997
     This function is like `perror()'. The only difference is that it
8817
8998
     accepts an error number returned by a gnutls function.
8828
9009
     *Returns:* a string that contains the name of the specified public
8829
9010
     key algorithm, or `NULL'.
8830
9011
 
 
9012
gnutls_pk_get_id
 
9013
----------------
 
9014
 
 
9015
 -- Function: gnutls_pk_algorithm_t gnutls_pk_get_id (const char * NAME)
 
9016
     NAME: is a string containing a public key algorithm name.
 
9017
 
 
9018
     Convert a string to a `gnutls_pk_algorithm_t' value.  The names are
 
9019
     compared in a case insensitive way.  For example,
 
9020
     gnutls_pk_get_id("RSA") will return `GNUTLS_PK_RSA'.
 
9021
 
 
9022
     *Returns:* an `gnutls_pk_algorithm_tid' of the specified in a
 
9023
     string public key algorithm, or `GNUTLS_PK_UNKNOWN' on failures.
 
9024
 
 
9025
     *Since:* 2.6.0
 
9026
 
 
9027
gnutls_pk_get_name
 
9028
------------------
 
9029
 
 
9030
 -- Function: const char * gnutls_pk_get_name (gnutls_pk_algorithm_t
 
9031
          ALGORITHM)
 
9032
     ALGORITHM: is a public key algorithm
 
9033
 
 
9034
     Convert a `gnutls_pk_algorithm_t' value to a string.
 
9035
 
 
9036
     *Returns:* a pointer to a string that contains the name of the
 
9037
     specified public key algorithm, or `NULL'.
 
9038
 
 
9039
     *Since:* 2.6.0
 
9040
 
 
9041
gnutls_pk_list
 
9042
--------------
 
9043
 
 
9044
 -- Function: const gnutls_pk_algorithm_t * gnutls_pk_list ( VOID)
 
9045
     Get a list of supported public key algorithms.
 
9046
 
 
9047
     *Returns:* a zero-terminated list of `gnutls_pk_algorithm_t'
 
9048
     integers indicating the available ciphers.
 
9049
 
 
9050
     *Since:* 2.6.0
 
9051
 
8831
9052
gnutls_prf_raw
8832
9053
--------------
8833
9054
 
8966
9187
     "NONE" nothing is enabled. This disables even protocols and
8967
9188
     compression methods.
8968
9189
 
8969
 
     *Special keywords:* '!' or '-' appended with an algorithm will
8970
 
     remove this algorithm.  '+' appended with an algorithm will add
8971
 
     this algorithm.  '`COMPAT'' will enable compatibility features for
8972
 
     a server.
 
9190
     *Special keywords:* "!" or "-" appended with an algorithm will
 
9191
     remove this algorithm.  "+" appended with an algorithm will add
 
9192
     this algorithm.  "`COMPAT'" will enable compatibility features for
 
9193
     a server.  "`SSL3_RECORD_VERSION'" will use SSL3.0 record version
 
9194
     in client hello.
8973
9195
 
8974
9196
     To avoid collisions in order to specify a compression algorithm in
8975
9197
     this string you have to prefix it with "COMP-", protocol versions
9034
9256
gnutls_protocol_get_id
9035
9257
----------------------
9036
9258
 
9037
 
 -- Function: gnutls_protocol_t gnutls_protocol_get_id (const char*
 
9259
 -- Function: gnutls_protocol_t gnutls_protocol_get_id (const char *
9038
9260
          NAME)
 
9261
     NAME: is a protocol name
 
9262
 
9039
9263
     The names are compared in a case insensitive way.
9040
9264
 
9041
9265
     *Returns:* an id of the specified protocol, or
9917
10141
     *Returns:* On success, `GNUTLS_E_SUCCESS' (0) is returned,
9918
10142
     otherwise an error code is returned.
9919
10143
 
 
10144
gnutls_session_set_finished_function
 
10145
------------------------------------
 
10146
 
 
10147
 -- Function: void gnutls_session_set_finished_function
 
10148
          (gnutls_session_t SESSION, gnutls_finished_callback_func
 
10149
          FINISHED_FUNC)
 
10150
     SESSION: is a `gnutls_session_t' structure.
 
10151
 
 
10152
     FINISHED_FUNC: a `gnutls_finished_callback_func' callback.
 
10153
 
 
10154
     Register a callback function for the session that will be called
 
10155
     when a TLS Finished message has been generated.  The function is
 
10156
     typically used to copy away the TLS finished message for later use
 
10157
     as a channel binding or similar purpose.
 
10158
 
 
10159
     *The callback should follow this prototype:* void callback
 
10160
     (gnutls_session_t session, const void *finished, size_t len);
 
10161
 
 
10162
     The `finished' parameter will contain the binary TLS finished
 
10163
     message, and `len' will contains its length.  For SSLv3
 
10164
     connections, the `len' parameter will be 36 and for TLS
 
10165
     connections it will be 12.
 
10166
 
 
10167
     It is recommended that the function returns quickly in order to not
 
10168
     delay the handshake.  Use the function to store a copy of the TLS
 
10169
     finished message for later use.
 
10170
 
 
10171
     *Since:* 2.6.0
 
10172
 
9920
10173
gnutls_session_set_ptr
9921
10174
----------------------
9922
10175
 
10018
10271
     can be used to store application-specific data needed in the
10019
10272
     callback function.  See also `gnutls_sign_callback_get()'.
10020
10273
 
 
10274
gnutls_sign_get_id
 
10275
------------------
 
10276
 
 
10277
 -- Function: gnutls_sign_algorithm_t gnutls_sign_get_id (const char *
 
10278
          NAME)
 
10279
     NAME: is a MAC algorithm name
 
10280
 
 
10281
     The names are compared in a case insensitive way.
 
10282
 
 
10283
     *Returns:* return a `gnutls_sign_algorithm_t' value corresponding
 
10284
     to the specified cipher, or `GNUTLS_SIGN_UNKNOWN' on error.
 
10285
 
 
10286
gnutls_sign_get_name
 
10287
--------------------
 
10288
 
 
10289
 -- Function: const char * gnutls_sign_get_name
 
10290
          (gnutls_sign_algorithm_t ALGORITHM)
 
10291
     ALGORITHM: is a public key signature algorithm
 
10292
 
 
10293
     Convert a `gnutls_sign_algorithm_t' value to a string.
 
10294
 
 
10295
     *Returns:* a pointer to a string that contains the name of the
 
10296
     specified public key signature algorithm, or `NULL'.
 
10297
 
 
10298
     *Since:* 2.6.0
 
10299
 
 
10300
gnutls_sign_list
 
10301
----------------
 
10302
 
 
10303
 -- Function: const gnutls_sign_algorithm_t * gnutls_sign_list ( VOID)
 
10304
     Get a list of supported public key signature algorithms.
 
10305
 
 
10306
     *Returns:* a zero-terminated list of `gnutls_sign_algorithm_t'
 
10307
     integers indicating the available ciphers.
 
10308
 
10021
10309
gnutls_srp_allocate_client_credentials
10022
10310
--------------------------------------
10023
10311
 
10214
10502
     *Returns:* On success, `GNUTLS_E_SUCCESS' (0) is returned, or an
10215
10503
     error code.
10216
10504
 
 
10505
gnutls_srp_set_prime_bits
 
10506
-------------------------
 
10507
 
 
10508
 -- Function: void gnutls_srp_set_prime_bits (gnutls_session_t SESSION,
 
10509
          unsigned int BITS)
 
10510
     SESSION: is a `gnutls_session_t' structure.
 
10511
 
 
10512
     BITS: is the number of bits
 
10513
 
 
10514
     This function sets the minimum accepted number of bits, for use in
 
10515
     an SRP key exchange.  If zero, the default 2048 bits will be used.
 
10516
 
 
10517
     In the client side it sets the minimum accepted number of bits.  If
 
10518
     a server sends a prime with less bits than that
 
10519
     `GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER' will be returned by the
 
10520
     handshake.
 
10521
 
 
10522
     *Since:* 2.6.0
 
10523
 
10217
10524
gnutls_srp_set_server_credentials_file
10218
10525
--------------------------------------
10219
10526
 
10298
10605
     *Returns:* On success, `GNUTLS_E_SUCCESS' (0) is returned, or an
10299
10606
     error code.
10300
10607
 
 
10608
gnutls_strerror_name
 
10609
--------------------
 
10610
 
 
10611
 -- Function: const char * gnutls_strerror_name (int ERROR)
 
10612
     ERROR: is an error returned by a gnutls function.
 
10613
 
 
10614
     Return the GnuTLS error code define as a string.  For example,
 
10615
     gnutls_strerror_name (GNUTLS_E_DH_PRIME_UNACCEPTABLE) will return
 
10616
     the string "GNUTLS_E_DH_PRIME_UNACCEPTABLE".
 
10617
 
 
10618
     *Returns:* A string corresponding to the symbol name of the error
 
10619
     code.
 
10620
 
 
10621
     *Since:* 2.6.0
 
10622
 
10301
10623
gnutls_strerror
10302
10624
---------------
10303
10625
 
10304
10626
 -- Function: const char * gnutls_strerror (int ERROR)
10305
 
     ERROR: is an error returned by a gnutls function. Error is always
10306
 
     a negative value.
 
10627
     ERROR: is a GnuTLS error code, a negative value
10307
10628
 
10308
 
     This function is similar to `strerror()'. Differences: it accepts
 
10629
     This function is similar to `strerror()'.  Differences: it accepts
10309
10630
     an error number returned by a gnutls function; In case of an
10310
10631
     unknown error a descriptive string is sent instead of NULL.
10311
10632
 
 
10633
     Error codes are always a negative value.
 
10634
 
 
10635
     *Returns:* A string explaining the GnuTLS error message.
 
10636
 
10312
10637
gnutls_transport_get_ptr2
10313
10638
-------------------------
10314
10639