~ubuntu-branches/ubuntu/trusty/gnutls26/trusty-security

« back to all changes in this revision

Viewing changes to doc/gnutls.info-1

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Metzler
  • Date: 2010-04-22 19:29:52 UTC
  • mto: (12.4.3 experimental) (1.5.1)
  • mto: This revision was merged to the branch mainline in revision 26.
  • Revision ID: james.westby@ubuntu.com-20100422192952-gbj6cvaan8e4ejck
Tags: upstream-2.9.10
ImportĀ upstreamĀ versionĀ 2.9.10

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
This is gnutls.info, produced by makeinfo version 4.13 from gnutls.texi.
2
2
 
3
 
This manual is last updated 9 November 2009 for version 2.9.9 of GNU
4
 
TLS.
 
3
This manual is last updated 15 March 2010 for version 2.9.10 of GNU TLS.
5
4
 
6
 
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free
7
 
Software Foundation, Inc.
 
5
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
 
6
2010 Free Software Foundation, Inc.
8
7
 
9
8
     Permission is granted to copy, distribute and/or modify this
10
9
     document under the terms of the GNU Free Documentation License,
34
33
GNU TLS
35
34
*******
36
35
 
37
 
This manual is last updated 9 November 2009 for version 2.9.9 of GNU
38
 
TLS.
 
36
This manual is last updated 15 March 2010 for version 2.9.10 of GNU TLS.
39
37
 
40
 
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free
41
 
Software Foundation, Inc.
 
38
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
 
39
2010 Free Software Foundation, Inc.
42
40
 
43
41
     Permission is granted to copy, distribute and/or modify this
44
42
     document under the terms of the GNU Free Documentation License,
163
161
 
164
162
`http://www.gnutls.org/download.html'
165
163
 
166
 
The latest version is stored in a file, e.g., `gnutls-2.9.9.tar.gz'
167
 
where the `2.9.9' value is the highest version number in the directory.
 
164
The latest version is stored in a file, e.g., `gnutls-2.9.10.tar.gz'
 
165
where the `2.9.10' value is the highest version number in the directory.
168
166
 
169
167
GnuTLS uses a Linux-like development cycle: even minor version numbers
170
168
indicate a stable release and a odd minor version number indicates a
1701
1699
gnutls_certificate_verify_peers2:: is equivalent to the previous one,
1702
1700
and will verify the peer's certificate in a TLS session.
1703
1701
 
1704
 
`CERT_INVALID:'
 
1702
`GNUTLS_CERT_INVALID:'
1705
1703
     The certificate is not signed by one of the known authorities, or
1706
1704
     the signature is invalid.
1707
1705
 
1708
 
`CERT_REVOKED:'
 
1706
`GNUTLS_CERT_REVOKED:'
1709
1707
     The certificate has been revoked by its CA.
1710
1708
 
1711
 
`CERT_SIGNER_NOT_FOUND:'
 
1709
`GNUTLS_CERT_SIGNER_NOT_FOUND:'
1712
1710
     The certificate's issuer is not known. This is the case when the
1713
1711
     issuer is not in the trusted certificates list.
1714
1712
 
2230
2228
external package `pkg-config' that knows the path to the include file
2231
2229
and other configuration options.  The options that need to be added to
2232
2230
the compiler invocation at compile time are output by the `--cflags'
2233
 
option to `pkg-config libgnutls'.  The following example shows how it
2234
 
can be used at the command line:
2235
 
 
2236
 
     gcc -c foo.c `pkg-config libgnutls --cflags`
2237
 
 
2238
 
Adding the output of `pkg-config libgnutls --cflags' to the compilers
 
2231
option to `pkg-config gnutls'.  The following example shows how it can
 
2232
be used at the command line:
 
2233
 
 
2234
     gcc -c foo.c `pkg-config gnutls --cflags`
 
2235
 
 
2236
Adding the output of `pkg-config gnutls --cflags' to the compilers
2239
2237
command line will ensure that the compiler can find the
2240
2238
`gnutls/gnutls.h' header file.
2241
2239
 
2243
2241
Again, the compiler has to find the library files.  For this to work,
2244
2242
the path to the library files has to be added to the library search
2245
2243
path (via the `-L' option).  For this, the option `--libs' to
2246
 
`pkg-config libgnutls' can be used.  For convenience, this option also
 
2244
`pkg-config gnutls' can be used.  For convenience, this option also
2247
2245
outputs all other options that are required to link the program with
2248
2246
the libarary (for instance, the `-ltasn1' option).  The example shows
2249
2247
how to link `foo.o' with the library to a program `foo'.
2250
2248
 
2251
 
     gcc -o foo foo.o `pkg-config libgnutls --libs`
 
2249
     gcc -o foo foo.o `pkg-config gnutls --libs`
2252
2250
 
2253
2251
Of course you can also combine both examples to a single command by
2254
2252
specifying both options to `pkg-config':
2255
2253
 
2256
 
     gcc -o foo foo.c `pkg-config libgnutls --cflags --libs`
 
2254
     gcc -o foo foo.c `pkg-config gnutls --cflags --libs`
2257
2255
 
2258
2256
 
2259
2257
File: gnutls.info,  Node: Multi-threaded applications,  Next: Client examples,  Prev: Preparation,  Up: How to use GnuTLS in applications
2767
2765
  if (status & GNUTLS_CERT_REVOKED)
2768
2766
    printf ("The certificate has been revoked.\n");
2769
2767
 
 
2768
  if (status & GNUTLS_CERT_EXPIRED)
 
2769
    printf ("The certificate has expired\n");
 
2770
 
 
2771
  if (status & GNUTLS_CERT_NOT_ACTIVATED)
 
2772
    printf ("The certificate is not yet activated\n");
2770
2773
 
2771
2774
  /* Up to here the process is the same for X.509 certificates and
2772
2775
   * OpenPGP keys. From now on X.509 certificates are assumed. This can
2797
2800
      return;
2798
2801
    }
2799
2802
 
2800
 
  /* Beware here we do not check for errors.
2801
 
   */
2802
 
  if (gnutls_x509_crt_get_expiration_time (cert) < time (0))
2803
 
    {
2804
 
      printf ("The certificate has expired\n");
2805
 
      return;
2806
 
    }
2807
 
 
2808
 
  if (gnutls_x509_crt_get_activation_time (cert) > time (0))
2809
 
    {
2810
 
      printf ("The certificate is not yet activated\n");
2811
 
      return;
2812
 
    }
2813
2803
 
2814
2804
  if (!gnutls_x509_crt_check_hostname (cert, hostname))
2815
2805
    {
2930
2920
{
2931
2921
  unsigned int output;
2932
2922
  int ret;
2933
 
  time_t now = time (0);
2934
2923
  size_t name_size;
2935
2924
  char name[64];
2936
2925
 
2966
2955
        fprintf (stderr, ": no issuer was found");
2967
2956
      if (output & GNUTLS_CERT_SIGNER_NOT_CA)
2968
2957
        fprintf (stderr, ": issuer is not a CA");
 
2958
      if (output & GNUTLS_CERT_NOT_ACTIVATED)
 
2959
        fprintf (stderr, ": not yet activated\n");
 
2960
      if (output & GNUTLS_CERT_EXPIRED)
 
2961
        fprintf (stderr, ": expired\n");
2969
2962
 
2970
2963
      fprintf (stderr, "\n");
2971
2964
    }
2972
2965
  else
2973
2966
    fprintf (stderr, "Trusted\n");
2974
2967
 
2975
 
 
2976
 
  /* Now check the expiration dates.
2977
 
   */
2978
 
  if (gnutls_x509_crt_get_activation_time (crt) > now)
2979
 
    fprintf (stderr, "Not yet activated\n");
2980
 
 
2981
 
  if (gnutls_x509_crt_get_expiration_time (crt) < now)
2982
 
    fprintf (stderr, "Expired\n");
2983
 
 
2984
2968
  /* Check if the certificate is revoked.
2985
2969
   */
2986
2970
  ret = gnutls_x509_crt_check_revocation (crt, crl_list, crl_list_size);
3001
2985
{
3002
2986
  unsigned int output;
3003
2987
  int ret;
3004
 
  time_t now = time (0);
3005
2988
  size_t name_size;
3006
2989
  char name[64];
3007
2990
 
3029
3012
 
3030
3013
      if (output & GNUTLS_CERT_SIGNER_NOT_CA)
3031
3014
        fprintf (stderr, ": Issuer is not a CA\n");
3032
 
      else
3033
 
        fprintf (stderr, "\n");
 
3015
      if (output & GNUTLS_CERT_NOT_ACTIVATED)
 
3016
        fprintf (stderr, ": Not yet activated\n");
 
3017
      if (output & GNUTLS_CERT_EXPIRED)
 
3018
        fprintf (stderr, ": Expired\n");
 
3019
      fprintf (stderr, "\n");
3034
3020
    }
3035
3021
  else
3036
3022
    fprintf (stderr, "Trusted\n");
3037
3023
 
3038
3024
 
3039
 
  /* Now check the expiration dates.
3040
 
   */
3041
 
  if (gnutls_x509_crt_get_activation_time (crt) > now)
3042
 
    fprintf (stderr, "Not yet activated\n");
3043
 
 
3044
 
  if (gnutls_x509_crt_get_expiration_time (crt) < now)
3045
 
    fprintf (stderr, "Expired\n");
3046
 
 
3047
3025
  /* Check if the certificate is revoked.
3048
3026
   */
3049
3027
  ret = gnutls_x509_crt_check_revocation (crt, crl_list, crl_list_size);
3717
3695
 
3718
3696
  if (last)
3719
3697
    printf ("- received %d bytes AVP: `%.*s'\n",
3720
 
            lastlen, (int) lastlen, last);
 
3698
            (int) lastlen, (int) lastlen, last);
3721
3699
  else
3722
3700
    printf ("- new application phase\n");
3723
3701
 
3726
3704
    return -1;
3727
3705
  *newlen = strlen (*new);
3728
3706
 
3729
 
  printf ("- sending %d bytes AVP: `%s'\n", *newlen, *new);
 
3707
  printf ("- sending %d bytes AVP: `%s'\n", (int) *newlen, *new);
3730
3708
 
3731
3709
  gnutls_ia_permute_inner_secret (session, 3, "foo");
3732
3710
 
5319
5297
print_x509_certificate_info (gnutls_session_t session)
5320
5298
{
5321
5299
  char serial[40];
5322
 
  char dn[128];
 
5300
  char dn[256];
5323
5301
  size_t size;
5324
5302
  unsigned int algo, bits;
5325
5303
  time_t expiration_time, activation_time;
5326
5304
  const gnutls_datum_t *cert_list;
5327
5305
  unsigned int cert_list_size = 0;
5328
5306
  gnutls_x509_crt_t cert;
 
5307
  gnutls_datum_t cinfo;
5329
5308
 
5330
5309
  /* This function only works for X.509 certificates.
5331
5310
   */
5338
5317
 
5339
5318
  if (cert_list_size > 0)
5340
5319
    {
 
5320
      int ret;
5341
5321
 
5342
5322
      /* we only print information about the first certificate.
5343
5323
       */
5347
5327
 
5348
5328
      printf ("Certificate info:\n");
5349
5329
 
 
5330
      /* This is the preferred way of printing short information about
 
5331
         a certificate. */
 
5332
 
 
5333
      ret = gnutls_x509_crt_print (cert, GNUTLS_CRT_PRINT_ONELINE, &cinfo);
 
5334
      if (ret == 0)
 
5335
        {
 
5336
          printf ("\t%s\n", cinfo.data);
 
5337
          gnutls_free (cinfo.data);
 
5338
        }
 
5339
 
 
5340
      /* If you want to extract fields manually for some other reason,
 
5341
         below are popular example calls. */
 
5342
 
5350
5343
      expiration_time = gnutls_x509_crt_get_expiration_time (cert);
5351
5344
      activation_time = gnutls_x509_crt_get_activation_time (cert);
5352
5345
 
5953
5946
     signing_key
5954
5947
 
5955
5948
     # Whether this certificate will be used to encrypt data (needed
5956
 
     # in TLS RSA ciphersuites). Note that it is prefered to use different
 
5949
     # in TLS RSA ciphersuites). Note that it is preferred to use different
5957
5950
     # keys for encryption and signing.
5958
5951
     #encryption_key
5959
5952
 
6757
6750
 
6758
6751
     FUNC: is the callback function
6759
6752
 
6760
 
     This function sets a callback to be called in order to retrieve
6761
 
     the certificate to be used in the handshake.  The callback's
6762
 
     function prototype is: int (*callback)(gnutls_session_t, const
6763
 
     gnutls_datum_t* req_ca_dn, int nreqs, const gnutls_pk_algorithm_t*
6764
 
     pk_algos, int pk_algos_length, gnutls_retr_st* st);
 
6753
     This function sets a callback to be called in order to retrieve the
 
6754
     certificate to be used in the handshake.
 
6755
 
 
6756
     The callback's function prototype is: int
 
6757
     (*callback)(gnutls_session_t, const gnutls_datum_t* req_ca_dn, int
 
6758
     nreqs, const gnutls_pk_algorithm_t* pk_algos, int pk_algos_length,
 
6759
     gnutls_retr_st* st);
6765
6760
 
6766
6761
     `req_ca_cert' is only used in X.509 certificates.  Contains a list
6767
6762
     with the CA names that the server considers trusted.  Normally we
6835
6830
     helper function is provided in order to free (deallocate) it.
6836
6831
 
6837
6832
     This function does not free any temporary parameters associated
6838
 
     with this structure (ie RSA and DH parameters are not freed by
6839
 
     this function).
 
6833
     with this structure (ie RSA and DH parameters are not freed by this
 
6834
     function).
6840
6835
 
6841
6836
gnutls_certificate_free_crls
6842
6837
----------------------------
6990
6985
 
6991
6986
     FUNC: is the callback function
6992
6987
 
6993
 
     This function sets a callback to be called in order to retrieve
6994
 
     the certificate to be used in the handshake.  The callback's
6995
 
     function prototype is: int (*callback)(gnutls_session_t,
6996
 
     gnutls_retr_st* st);
 
6988
     This function sets a callback to be called in order to retrieve the
 
6989
     certificate to be used in the handshake.
 
6990
 
 
6991
     The callback's function prototype is: int
 
6992
     (*callback)(gnutls_session_t, gnutls_retr_st* st);
6997
6993
 
6998
6994
     `st' should contain the certificates and private keys.
6999
6995
 
7063
7059
     certificates.  Flags must be OR of the
7064
7060
     `gnutls_certificate_verify_flags' enumerations.
7065
7061
 
 
7062
gnutls_certificate_set_verify_function
 
7063
--------------------------------------
 
7064
 
 
7065
 -- Function: void gnutls_certificate_set_verify_function
 
7066
          (gnutls_certificate_credentials_t CRED,
 
7067
          gnutls_certificate_verify_function * FUNC)
 
7068
     CRED: is a `gnutls_certificate_credentials_t' structure.
 
7069
 
 
7070
     FUNC: is the callback function
 
7071
 
 
7072
     This function sets a callback to be called when peer's certificate
 
7073
     has been received in order to verify it on receipt rather than
 
7074
     doing after the handshake is completed.
 
7075
 
 
7076
     The callback's function prototype is: int
 
7077
     (*callback)(gnutls_session_t);
 
7078
 
 
7079
     If the callback function is provided then gnutls will call it, in
 
7080
     the handshake, just after the certificate message has been
 
7081
     received.  To verify or obtain the certificate the
 
7082
     `gnutls_certificate_verify_peers2()',
 
7083
     `gnutls_certificate_type_get()', `gnutls_certificate_get_peers()'
 
7084
     functions can be used.
 
7085
 
 
7086
     The callback function should return 0 for the handshake to continue
 
7087
     or non-zero to terminate.
 
7088
 
 
7089
     *Since:* 2.10.0
 
7090
 
7066
7091
gnutls_certificate_set_verify_limits
7067
7092
------------------------------------
7068
7093
 
7165
7190
 
7166
7191
     This function sets a certificate/private key pair in the
7167
7192
     gnutls_certificate_credentials_t structure.  This function may be
7168
 
     called more than once (in case multiple keys/certificates exist
7169
 
     for the server).
 
7193
     called more than once (in case multiple keys/certificates exist for
 
7194
     the server).  For clients that wants to send more than its own end
 
7195
     entity certificate (e.g., also an intermediate CA cert) then put
 
7196
     the certificate chain in `certfile'.
7170
7197
 
7171
7198
     Currently only PKCS-1 encoded RSA and DSA private keys are
7172
7199
     accepted by this function.
7229
7256
 
7230
7257
     This function sets a certificate/private key pair in the
7231
7258
     gnutls_certificate_credentials_t structure.  This function may be
7232
 
     called more than once (in case multiple keys/certificates exist
7233
 
     for the server).
 
7259
     called more than once (in case multiple keys/certificates exist for
 
7260
     the server).  For clients that wants to send more than its own end
 
7261
     entity certificate (e.g., also an intermediate CA cert) then put
 
7262
     the certificate chain in `cert_list'.
7234
7263
 
7235
7264
     *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code.
7236
7265
 
7357
7386
     TYPE: is DER or PEM
7358
7387
 
7359
7388
     This function adds the trusted CAs in order to verify client or
7360
 
     server certificates. In case of a client this is not required to
7361
 
     be called if the certificates are not verified using
 
7389
     server certificates. In case of a client this is not required to be
 
7390
     called if the certificates are not verified using
7362
7391
     `gnutls_certificate_verify_peers2()'.  This function may be called
7363
7392
     multiple times.
7364
7393
 
7528
7557
     condition is not met.  If `NULL' is passed to this function no
7529
7558
     check is done and only the version string is returned.
7530
7559
 
 
7560
gnutls_cipher_decrypt
 
7561
---------------------
 
7562
 
 
7563
 -- Function: int gnutls_cipher_decrypt (gnutls_cipher_hd_t HANDLE,
 
7564
          void * CIPHERTEXT, size_t CIPHERTEXTLEN)
 
7565
     HANDLE: is a `gnutls_cipher_hd_t' structure.
 
7566
 
 
7567
     CIPHERTEXT: the data to encrypt
 
7568
 
 
7569
     CIPHERTEXTLEN: The length of data to encrypt
 
7570
 
 
7571
     This function will decrypt the given data using the algorithm
 
7572
     specified by the context.
 
7573
 
 
7574
     *Returns:* Zero or a negative value on error.
 
7575
 
 
7576
     *Since:* 2.10.0
 
7577
 
 
7578
gnutls_cipher_deinit
 
7579
--------------------
 
7580
 
 
7581
 -- Function: void gnutls_cipher_deinit (gnutls_cipher_hd_t HANDLE)
 
7582
     HANDLE: is a `gnutls_cipher_hd_t' structure.
 
7583
 
 
7584
     This function will deinitialize all resources occupied by the given
 
7585
     encryption context.
 
7586
 
 
7587
     *Since:* 2.10.0
 
7588
 
 
7589
gnutls_cipher_encrypt
 
7590
---------------------
 
7591
 
 
7592
 -- Function: int gnutls_cipher_encrypt (gnutls_cipher_hd_t HANDLE,
 
7593
          void * TEXT, size_t TEXTLEN)
 
7594
     HANDLE: is a `gnutls_cipher_hd_t' structure.
 
7595
 
 
7596
     TEXT: the data to encrypt
 
7597
 
 
7598
     TEXTLEN: The length of data to encrypt
 
7599
 
 
7600
     This function will encrypt the given data using the algorithm
 
7601
     specified by the context.
 
7602
 
 
7603
     *Returns:* Zero or a negative value on error.
 
7604
 
 
7605
     *Since:* 2.10.0
 
7606
 
 
7607
gnutls_cipher_get_block_size
 
7608
----------------------------
 
7609
 
 
7610
 -- Function: int gnutls_cipher_get_block_size
 
7611
          (gnutls_cipher_algorithm_t ALGORITHM)
 
7612
     ALGORITHM: is an encryption algorithm
 
7613
 
 
7614
     Get block size for encryption algorithm.
 
7615
 
 
7616
     *Returns:* block size for encryption algorithm.
 
7617
 
 
7618
     *Since:* 2.10.0
 
7619
 
7531
7620
gnutls_cipher_get_id
7532
7621
--------------------
7533
7622
 
7577
7666
     *Returns:* the currently used cipher, a `gnutls_cipher_algorithm_t'
7578
7667
     type.
7579
7668
 
 
7669
gnutls_cipher_init
 
7670
------------------
 
7671
 
 
7672
 -- Function: int gnutls_cipher_init (gnutls_cipher_hd_t * HANDLE,
 
7673
          gnutls_cipher_algorithm_t CIPHER, const gnutls_datum_t * KEY,
 
7674
          const gnutls_datum_t * IV)
 
7675
     HANDLE: is a `gnutls_cipher_hd_t' structure.
 
7676
 
 
7677
     CIPHER: the encryption algorithm to use
 
7678
 
 
7679
     KEY: The key to be used for encryption
 
7680
 
 
7681
     IV: The IV to use (if not applicable set NULL)
 
7682
 
 
7683
     This function will initialize an context that can be used for
 
7684
     encryption/decryption of data. This will effectively use the
 
7685
     current crypto backend in use by gnutls or the cryptographic
 
7686
     accelerator in use.
 
7687
 
 
7688
     *Returns:* Zero or a negative value on error.
 
7689
 
 
7690
     *Since:* 2.10.0
 
7691
 
7580
7692
gnutls_cipher_list
7581
7693
------------------
7582
7694
 
7632
7744
 -- Function: const char * gnutls_cipher_suite_info (size_t IDX, char *
7633
7745
          CS_ID, gnutls_kx_algorithm_t * KX, gnutls_cipher_algorithm_t
7634
7746
          * CIPHER, gnutls_mac_algorithm_t * MAC, gnutls_protocol_t *
7635
 
          VERSION)
 
7747
          MIN_VERSION)
7636
7748
     IDX: index of cipher suite to get information about, starts on 0.
7637
7749
 
7638
7750
     CS_ID: output buffer with room for 2 bytes, indicating cipher
7644
7756
 
7645
7757
     MAC: output variable indicating MAC algorithm, or `NULL'.
7646
7758
 
7647
 
     VERSION: output variable indicating TLS protocol version, or
7648
 
     `NULL'.
7649
 
 
7650
7759
     Get information about supported cipher suites.  Use the function
7651
7760
     iteratively to get information about all supported cipher suites.
7652
7761
     Call with idx=0 to get information about first cipher suite, then
7774
7883
------------------------------
7775
7884
 
7776
7885
 -- Function: int gnutls_crypto_bigint_register2 (int PRIORITY, int
7777
 
          VERSION, gnutls_crypto_bigint_st * S)
 
7886
          VERSION, const gnutls_crypto_bigint_st * S)
7778
7887
     PRIORITY: is the priority of the interface
7779
7888
 
7780
7889
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7803
7912
------------------------------
7804
7913
 
7805
7914
 -- Function: int gnutls_crypto_cipher_register2 (int PRIORITY, int
7806
 
          VERSION, gnutls_crypto_cipher_st * S)
 
7915
          VERSION, const gnutls_crypto_cipher_st * S)
7807
7916
     PRIORITY: is the priority of the cipher interface
7808
7917
 
7809
7918
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7829
7938
------------------------------
7830
7939
 
7831
7940
 -- Function: int gnutls_crypto_digest_register2 (int PRIORITY, int
7832
 
          VERSION, gnutls_crypto_digest_st * S)
 
7941
          VERSION, const gnutls_crypto_digest_st * S)
7833
7942
     PRIORITY: is the priority of the digest interface
7834
7943
 
7835
7944
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7855
7964
---------------------------
7856
7965
 
7857
7966
 -- Function: int gnutls_crypto_mac_register2 (int PRIORITY, int
7858
 
          VERSION, gnutls_crypto_mac_st * S)
 
7967
          VERSION, const gnutls_crypto_mac_st * S)
7859
7968
     PRIORITY: is the priority of the mac interface
7860
7969
 
7861
7970
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7870
7979
     This function should be called before `gnutls_global_init()'.
7871
7980
 
7872
7981
     For simplicity you can use the convenience
7873
 
     `gnutls_crypto_mac_register()' macro.
 
7982
     `gnutls_crypto_digest_register()' macro.
7874
7983
 
7875
7984
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
7876
7985
 
7880
7989
--------------------------
7881
7990
 
7882
7991
 -- Function: int gnutls_crypto_pk_register2 (int PRIORITY, int
7883
 
          VERSION, gnutls_crypto_pk_st * S)
 
7992
          VERSION, const gnutls_crypto_pk_st * S)
7884
7993
     PRIORITY: is the priority of the interface
7885
7994
 
7886
7995
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7909
8018
---------------------------
7910
8019
 
7911
8020
 -- Function: int gnutls_crypto_rnd_register2 (int PRIORITY, int
7912
 
          VERSION, gnutls_crypto_rnd_st * S)
 
8021
          VERSION, const gnutls_crypto_rnd_st * S)
7913
8022
     PRIORITY: is the priority of the generator
7914
8023
 
7915
8024
     VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7936
8045
 
7937
8046
 -- Function: int gnutls_crypto_single_cipher_register2
7938
8047
          (gnutls_cipher_algorithm_t ALGORITHM, int PRIORITY, int
7939
 
          VERSION, gnutls_crypto_single_cipher_st * S)
 
8048
          VERSION, const gnutls_crypto_cipher_st * S)
7940
8049
     ALGORITHM: is the gnutls algorithm identifier
7941
8050
 
7942
8051
     PRIORITY: is the priority of the algorithm
7965
8074
 
7966
8075
 -- Function: int gnutls_crypto_single_digest_register2
7967
8076
          (gnutls_digest_algorithm_t ALGORITHM, int PRIORITY, int
7968
 
          VERSION, gnutls_crypto_single_digest_st * S)
 
8077
          VERSION, const gnutls_crypto_digest_st * S)
7969
8078
     ALGORITHM: is the gnutls algorithm identifier
7970
8079
 
7971
8080
     PRIORITY: is the priority of the algorithm
7994
8103
 
7995
8104
 -- Function: int gnutls_crypto_single_mac_register2
7996
8105
          (gnutls_mac_algorithm_t ALGORITHM, int PRIORITY, int VERSION,
7997
 
          gnutls_crypto_single_mac_st * S)
 
8106
          const gnutls_crypto_mac_st * S)
7998
8107
     ALGORITHM: is the gnutls algorithm identifier
7999
8108
 
8000
8109
     PRIORITY: is the priority of the algorithm
8094
8203
     Sets the function that will be used to remove data from the
8095
8204
     resumed sessions database. This function must return 0 on success.
8096
8205
 
8097
 
     The first argument to `rem_func()' will be null unless
 
8206
     The first argument to `rem_func' will be null unless
8098
8207
     `gnutls_db_set_ptr()' has been called.
8099
8208
 
8100
8209
gnutls_db_set_retrieve_function
8114
8223
     The datum's data must be allocated using the function
8115
8224
     `gnutls_malloc()'.
8116
8225
 
8117
 
     The first argument to `retr_func()' will be null unless
 
8226
     The first argument to `retr_func' will be null unless
8118
8227
     `gnutls_db_set_ptr()' has been called.
8119
8228
 
8120
8229
gnutls_db_set_store_function
8714
8823
 
8715
8824
     *Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
8716
8825
 
 
8826
gnutls_hash_deinit
 
8827
------------------
 
8828
 
 
8829
 -- Function: void gnutls_hash_deinit (gnutls_hash_hd_t HANDLE, void *
 
8830
          DIGEST)
 
8831
     HANDLE: is a `gnutls_hash_hd_t' structure.
 
8832
 
 
8833
     DIGEST: is the output value of the hash
 
8834
 
 
8835
     This function will deinitialize all resources occupied by the
 
8836
     given hash context.
 
8837
 
 
8838
     *Since:* 2.10.0
 
8839
 
 
8840
gnutls_hash_fast
 
8841
----------------
 
8842
 
 
8843
 -- Function: int gnutls_hash_fast (gnutls_digest_algorithm_t
 
8844
          ALGORITHM, const void * TEXT, size_t TEXTLEN, void * DIGEST)
 
8845
     ALGORITHM: the hash algorithm to use
 
8846
 
 
8847
     TEXT: the data to hash
 
8848
 
 
8849
     TEXTLEN: The length of data to hash
 
8850
 
 
8851
     DIGEST: is the output value of the hash
 
8852
 
 
8853
     This convenience function will hash the given data and return
 
8854
     output on a single call.
 
8855
 
 
8856
     *Returns:* Zero or a negative value on error.
 
8857
 
 
8858
     *Since:* 2.10.0
 
8859
 
 
8860
gnutls_hash_get_len
 
8861
-------------------
 
8862
 
 
8863
 -- Function: int gnutls_hash_get_len (gnutls_digest_algorithm_t
 
8864
          ALGORITHM)
 
8865
     ALGORITHM: the hash algorithm to use
 
8866
 
 
8867
     This function will return the length of the output data of the
 
8868
     given hash algorithm.
 
8869
 
 
8870
     *Returns:* The length or zero on error.
 
8871
 
 
8872
     *Since:* 2.10.0
 
8873
 
 
8874
gnutls_hash_init
 
8875
----------------
 
8876
 
 
8877
 -- Function: int gnutls_hash_init (gnutls_hash_hd_t * DIG,
 
8878
          gnutls_digest_algorithm_t ALGORITHM)
 
8879
     DIG: is a `gnutls_hash_hd_t' structure.
 
8880
 
 
8881
     ALGORITHM: the hash algorithm to use
 
8882
 
 
8883
     This function will initialize an context that can be used to
 
8884
     produce a Message Digest of data.  This will effectively use the
 
8885
     current crypto backend in use by gnutls or the cryptographic
 
8886
     accelerator in use.
 
8887
 
 
8888
     *Returns:* Zero or a negative value on error.
 
8889
 
 
8890
     *Since:* 2.10.0
 
8891
 
 
8892
gnutls_hash_output
 
8893
------------------
 
8894
 
 
8895
 -- Function: void gnutls_hash_output (gnutls_hash_hd_t HANDLE, void *
 
8896
          DIGEST)
 
8897
     HANDLE: is a `gnutls_hash_hd_t' structure.
 
8898
 
 
8899
     DIGEST: is the output value of the hash
 
8900
 
 
8901
     This function will output the current hash value.
 
8902
 
 
8903
     *Since:* 2.10.0
 
8904
 
 
8905
gnutls_hash
 
8906
-----------
 
8907
 
 
8908
 -- Function: int gnutls_hash (gnutls_hash_hd_t HANDLE, const void *
 
8909
          TEXT, size_t TEXTLEN)
 
8910
     HANDLE: is a `gnutls_cipher_hd_t' structure.
 
8911
 
 
8912
     TEXT: the data to hash
 
8913
 
 
8914
     TEXTLEN: The length of data to hash
 
8915
 
 
8916
     This function will hash the given data using the algorithm
 
8917
     specified by the context.
 
8918
 
 
8919
     *Returns:* Zero or a negative value on error.
 
8920
 
 
8921
     *Since:* 2.10.0
 
8922
 
8717
8923
gnutls_hex2bin
8718
8924
--------------
8719
8925
 
8770
8976
     *Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
8771
8977
     not long enough, or 0 on success.
8772
8978
 
 
8979
gnutls_hmac_deinit
 
8980
------------------
 
8981
 
 
8982
 -- Function: void gnutls_hmac_deinit (gnutls_hmac_hd_t HANDLE, void *
 
8983
          DIGEST)
 
8984
     HANDLE: is a `gnutls_hmac_hd_t' structure.
 
8985
 
 
8986
     DIGEST: is the output value of the MAC
 
8987
 
 
8988
     This function will deinitialize all resources occupied by the
 
8989
     given hmac context.
 
8990
 
 
8991
     *Since:* 2.10.0
 
8992
 
 
8993
gnutls_hmac_fast
 
8994
----------------
 
8995
 
 
8996
 -- Function: int gnutls_hmac_fast (gnutls_mac_algorithm_t ALGORITHM,
 
8997
          const void * KEY, size_t KEYLEN, const void * TEXT, size_t
 
8998
          TEXTLEN, void * DIGEST)
 
8999
     ALGORITHM: the hash algorithm to use
 
9000
 
 
9001
     KEY: the key to use
 
9002
 
 
9003
     KEYLEN: The length of the key
 
9004
 
 
9005
     TEXT: the data to hash
 
9006
 
 
9007
     TEXTLEN: The length of data to hash
 
9008
 
 
9009
     DIGEST: is the output value of the hash
 
9010
 
 
9011
     This convenience function will hash the given data and return
 
9012
     output on a single call.
 
9013
 
 
9014
     *Returns:* Zero or a negative value on error.
 
9015
 
 
9016
     *Since:* 2.10.0
 
9017
 
 
9018
gnutls_hmac_get_len
 
9019
-------------------
 
9020
 
 
9021
 -- Function: int gnutls_hmac_get_len (gnutls_mac_algorithm_t ALGORITHM)
 
9022
     ALGORITHM: the hmac algorithm to use
 
9023
 
 
9024
     This function will return the length of the output data of the
 
9025
     given hmac algorithm.
 
9026
 
 
9027
     *Returns:* The length or zero on error.
 
9028
 
 
9029
     *Since:* 2.10.0
 
9030
 
 
9031
gnutls_hmac_init
 
9032
----------------
 
9033
 
 
9034
 -- Function: int gnutls_hmac_init (gnutls_hmac_hd_t * DIG,
 
9035
          gnutls_digest_algorithm_t ALGORITHM, const void * KEY, size_t
 
9036
          KEYLEN)
 
9037
     DIG: is a `gnutls_hmac_hd_t' structure.
 
9038
 
 
9039
     ALGORITHM: the HMAC algorithm to use
 
9040
 
 
9041
     KEY: The key to be used for encryption
 
9042
 
 
9043
     KEYLEN: The length of the key
 
9044
 
 
9045
     This function will initialize an context that can be used to
 
9046
     produce a Message Authentication Code (MAC) of data.  This will
 
9047
     effectively use the current crypto backend in use by gnutls or the
 
9048
     cryptographic accelerator in use.
 
9049
 
 
9050
     *Returns:* Zero or a negative value on error.
 
9051
 
 
9052
     *Since:* 2.10.0
 
9053
 
 
9054
gnutls_hmac_output
 
9055
------------------
 
9056
 
 
9057
 -- Function: void gnutls_hmac_output (gnutls_hmac_hd_t HANDLE, void *
 
9058
          DIGEST)
 
9059
     HANDLE: is a `gnutls_hmac_hd_t' structure.
 
9060
 
 
9061
     DIGEST: is the output value of the MAC
 
9062
 
 
9063
     This function will output the current MAC value.
 
9064
 
 
9065
     *Since:* 2.10.0
 
9066
 
 
9067
gnutls_hmac
 
9068
-----------
 
9069
 
 
9070
 -- Function: int gnutls_hmac (gnutls_hmac_hd_t HANDLE, const void *
 
9071
          TEXT, size_t TEXTLEN)
 
9072
     HANDLE: is a `gnutls_cipher_hd_t' structure.
 
9073
 
 
9074
     TEXT: the data to hash
 
9075
 
 
9076
     TEXTLEN: The length of data to hash
 
9077
 
 
9078
     This function will hash the given data using the algorithm
 
9079
     specified by the context.
 
9080
 
 
9081
     *Returns:* Zero or a negative value on error.
 
9082
 
 
9083
     *Since:* 2.10.0
 
9084
 
8773
9085
gnutls_init
8774
9086
-----------
8775
9087
 
9258
9570
     compression methods. This is to avoid using the
9259
9571
     gnutls_*`_priority()' functions.
9260
9572
 
9261
 
     The `priorities' option allows you to specify a semi-colon
9262
 
     separated list of the cipher priorities to enable.
 
9573
     The `priorities' option allows you to specify a colon separated
 
9574
     list of the cipher priorities to enable.
9263
9575
 
9264
9576
     Unless the first keyword is "NONE" the defaults (in preference
9265
9577
     order) are for TLS protocols TLS1.1, TLS1.0, SSL3.0; for
9266
9578
     compression NULL; for certificate types X.509, OpenPGP.
9267
9579
 
9268
9580
     For key exchange algorithms when in NORMAL or SECURE levels the
9269
 
     perfect forward secrecy algorithms take precendence of the other
 
9581
     perfect forward secrecy algorithms take precedence of the other
9270
9582
     protocols.  In all cases all the supported key exchange algorithms
9271
9583
     are enabled (except for the RSA-EXPORT which is only enabled in
9272
9584
     EXPORT level).
9308
9620
 
9309
9621
     "%COMPAT" will enable compatibility features for a server.
9310
9622
 
 
9623
     "%UNSAFE_RENEGOTIATION" will allow unsafe renegotiation (this is
 
9624
     now the default, but will change once more servers support the
 
9625
     safe renegotiation TLS fix).
 
9626
 
 
9627
     "%SAFE_RENEGOTIATION" will allow safe renegotiation only.
 
9628
 
 
9629
     "%INITIAL_SAFE_RENEGOTIATION" will force initial safe negotiation
 
9630
     even if renegotiation wasn't requested. Only valid for server side
 
9631
     and implies "%SAFE_RENEGOTIATION".
 
9632
 
 
9633
     "%DISABLE_SAFE_RENEGOTIATION" will disable safe renegotiation
 
9634
     completely. Do not use unless you know what you are doing. Testing
 
9635
     purposes only.
 
9636
 
9311
9637
     "%SSL3_RECORD_VERSION" will use SSL3.0 record version in client
9312
9638
     hello.
9313
9639
 
9560
9886
     This function sets the username and password, in a
9561
9887
     gnutls_psk_client_credentials_t structure.  Those will be used in
9562
9888
     PSK authentication.  `username' should be an ASCII string or UTF-8
9563
 
     strings prepared using the "SASLprep" profile of "stringprep".
9564
 
     The key can be either in raw byte format or in Hex format (without
9565
 
     the 0x prefix).
 
9889
     strings prepared using the "SASLprep" profile of "stringprep".  The
 
9890
     key can be either in raw byte format or in Hex format (without the
 
9891
     0x prefix).
9566
9892
 
9567
9893
     *Returns:* `GNUTLS_E_SUCCESS' on success, or an error code.
9568
9894
 
9690
10016
          SESSION)
9691
10017
     SESSION: is a `gnutls_session_t' structure.
9692
10018
 
9693
 
     Used to disabled padding in TLS 1.0 and above.  Normally you do
9694
 
     not need to use this function, but there are buggy clients that
 
10019
     Used to disabled padding in TLS 1.0 and above.  Normally you do not
 
10020
     need to use this function, but there are buggy clients that
9695
10021
     complain if a server pads the encrypted data.  This of course will
9696
10022
     disable protection against statistical attacks on the data.
9697
10023
 
9838
10164
     `gnutls_handshake()' function in order to negotiate the new
9839
10165
     parameters.
9840
10166
 
 
10167
     Since TLS is full duplex some application data might have been
 
10168
     sent during peer's processing of this message. In that case one
 
10169
     should call `gnutls_record_recv()' until GNUTLS_E_REHANDSHAKE is
 
10170
     returned to clear any pending data. Care must be taken if
 
10171
     rehandshake is mandatory to terminate if it does not start after
 
10172
     some threshold.
 
10173
 
9841
10174
     If the client does not wish to renegotiate parameters he will
9842
10175
     should with an alert message, thus the return code will be
9843
10176
     `GNUTLS_E_WARNING_ALERT_RECEIVED' and the alert will be
10041
10374
     *Returns:* `GNUTLS_E_SUCCESS' on success, or an negative error
10042
10375
     code.
10043
10376
 
 
10377
gnutls_safe_negotiation_set_initial
 
10378
-----------------------------------
 
10379
 
 
10380
 -- Function: void gnutls_safe_negotiation_set_initial
 
10381
          (gnutls_session_t SESSION, int VALUE)
 
10382
     SESSION: is a `gnutls_session_t' structure.
 
10383
 
 
10384
     VALUE: 0 to disable and 1 to enable
 
10385
 
 
10386
     Used to enable and disable initial safe renegotiation for the
 
10387
     current session. By default it is allowed for a client to not
 
10388
     advertise safe renegotiation capability but there might be cases
 
10389
     where signalling a client of its insecurity by rejecting session
 
10390
     might be beneficial.  This option has meaning only in server side.
 
10391
 
 
10392
     *Since:* 2.10.0
 
10393
 
 
10394
gnutls_safe_renegotiation_set
 
10395
-----------------------------
 
10396
 
 
10397
 -- Function: void gnutls_safe_renegotiation_set (gnutls_session_t
 
10398
          SESSION, int VALUE)
 
10399
     SESSION: is a `gnutls_session_t' structure.
 
10400
 
 
10401
     VALUE: 0 to disable and 1 to enable
 
10402
 
 
10403
     Used to enable and disable safe renegotiation for the current
 
10404
     session. Normally you shouldn't cope with this function since the
 
10405
     default (enable) is sufficient, but there might be servers that
 
10406
     cannot handle or correctly handle the extension.
 
10407
 
 
10408
     *Since:* 2.10.0
 
10409
 
 
10410
gnutls_safe_renegotiation_status
 
10411
--------------------------------
 
10412
 
 
10413
 -- Function: int gnutls_safe_renegotiation_status (gnutls_session_t
 
10414
          SESSION)
 
10415
     SESSION: is a `gnutls_session_t' structure.
 
10416
 
 
10417
     Can be used to check whether safe renegotiation is being used in
 
10418
     the current session.
 
10419
 
 
10420
     *Returns:* 0 when safe renegotiation is not used and non zero when
 
10421
     safe renegotiation is used.
 
10422
 
 
10423
     *Since:* 2.10.0
 
10424
 
10044
10425
gnutls_server_name_get
10045
10426
----------------------
10046
10427
 
10152
10533
     `gnutls_free()'.
10153
10534
 
10154
10535
     Resuming sessions is really useful and speedups connections after
10155
 
     a succesful one.
 
10536
     a successful one.
10156
10537
 
10157
10538
     *Returns:* On success, `GNUTLS_E_SUCCESS' (0) is returned,
10158
10539
     otherwise an error code is returned.
10176
10557
     successful handshake.
10177
10558
 
10178
10559
     Resuming sessions is really useful and speedups connections after
10179
 
     a succesful one.
 
10560
     a successful one.
10180
10561
 
10181
10562
     *Returns:* On success, `GNUTLS_E_SUCCESS' (0) is returned,
10182
10563
     otherwise an error code is returned.
10587
10968
     This function will decode the given encoded data, using the base64
10588
10969
     encoding found in libsrp.
10589
10970
 
10590
 
     Note that b64_data should be null terminated.
 
10971
     Note that `b64_data' should be null terminated.
10591
10972
 
10592
10973
     Warning!  This base64 encoding is not the "standard" encoding, so
10593
10974
     do not use it for non-SRP purposes.
10682
11063
     FUNC: is the callback function
10683
11064
 
10684
11065
     This function can be used to set a callback to retrieve the
10685
 
     username and password for client SRP authentication.
10686
 
 
10687
 
     The callback's function form is:
 
11066
     username and password for client SRP authentication.  The
 
11067
     callback's function form is:
10688
11068
 
10689
11069
     int (*callback)(gnutls_session_t, char** username, char**password);
10690
11070
 
10775
11155
     FUNC: is the callback function
10776
11156
 
10777
11157
     This function can be used to set a callback to retrieve the user's
10778
 
     SRP credentials.  The callback's function form is: int
10779
 
     (*callback)(gnutls_session_t, const char* username,
 
11158
     SRP credentials.  The callback's function form is:
 
11159
 
 
11160
     int (*callback)(gnutls_session_t, const char* username,
10780
11161
     gnutls_datum_t* salt, gnutls_datum_t *verifier, gnutls_datum_t* g,
10781
11162
     gnutls_datum_t* n);
10782
11163
 
10857
11238
 
10858
11239
     *Returns:* A string explaining the GnuTLS error message.
10859
11240
 
 
11241
gnutls_supplemental_get_name
 
11242
----------------------------
 
11243
 
 
11244
 -- Function: const char * gnutls_supplemental_get_name
 
11245
          (gnutls_supplemental_data_format_type_t TYPE)
 
11246
     TYPE: is a supplemental data format type
 
11247
 
 
11248
     Convert a `gnutls_supplemental_data_format_type_t' value to a
 
11249
     string.
 
11250
 
 
11251
     *Returns:* a string that contains the name of the specified
 
11252
     supplemental data format type, or `NULL' for unknown types.
 
11253
 
10860
11254
gnutls_transport_get_ptr2
10861
11255
-------------------------
10862
11256
 
10960
11354
 
10961
11355
     SEND_PTR: is the value for the push function
10962
11356
 
10963
 
     Used to set the first argument of the transport function (like
10964
 
     PUSH and PULL). In berkeley style sockets this function will set
10965
 
     the connection handle.  With this function you can use two
10966
 
     different pointers for receiving and sending.
 
11357
     Used to set the first argument of the transport function (like PUSH
 
11358
     and PULL). In berkeley style sockets this function will set the
 
11359
     connection handle.  With this function you can use two different
 
11360
     pointers for receiving and sending.
10967
11361
 
10968
11362
gnutls_transport_set_ptr
10969
11363
------------------------
10974
11368
 
10975
11369
     PTR: is the value.
10976
11370
 
10977
 
     Used to set the first argument of the transport function (like
10978
 
     PUSH and PULL).  In berkeley style sockets this function will set
10979
 
     the connection handle.
 
11371
     Used to set the first argument of the transport function (like PUSH
 
11372
     and PULL).  In berkeley style sockets this function will set the
 
11373
     connection handle.
10980
11374
 
10981
11375
gnutls_transport_set_pull_function
10982
11376
----------------------------------