1
1
This is gnutls.info, produced by makeinfo version 4.13 from gnutls.texi.
3
This manual is last updated 9 November 2009 for version 2.9.9 of GNU
3
This manual is last updated 15 March 2010 for version 2.9.10 of GNU TLS.
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.
9
8
Permission is granted to copy, distribute and/or modify this
10
9
document under the terms of the GNU Free Documentation License,
37
This manual is last updated 9 November 2009 for version 2.9.9 of GNU
36
This manual is last updated 15 March 2010 for version 2.9.10 of GNU TLS.
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.
43
41
Permission is granted to copy, distribute and/or modify this
44
42
document under the terms of the GNU Free Documentation License,
164
162
`http://www.gnutls.org/download.html'
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.
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.
1702
`GNUTLS_CERT_INVALID:'
1705
1703
The certificate is not signed by one of the known authorities, or
1706
1704
the signature is invalid.
1706
`GNUTLS_CERT_REVOKED:'
1709
1707
The certificate has been revoked by its CA.
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.
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:
2236
gcc -c foo.c `pkg-config libgnutls --cflags`
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:
2234
gcc -c foo.c `pkg-config gnutls --cflags`
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.
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'.
2251
gcc -o foo foo.o `pkg-config libgnutls --libs`
2249
gcc -o foo foo.o `pkg-config gnutls --libs`
2253
2251
Of course you can also combine both examples to a single command by
2254
2252
specifying both options to `pkg-config':
2256
gcc -o foo foo.c `pkg-config libgnutls --cflags --libs`
2254
gcc -o foo foo.c `pkg-config gnutls --cflags --libs`
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");
2768
if (status & GNUTLS_CERT_EXPIRED)
2769
printf ("The certificate has expired\n");
2771
if (status & GNUTLS_CERT_NOT_ACTIVATED)
2772
printf ("The certificate is not yet activated\n");
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
2800
/* Beware here we do not check for errors.
2802
if (gnutls_x509_crt_get_expiration_time (cert) < time (0))
2804
printf ("The certificate has expired\n");
2808
if (gnutls_x509_crt_get_activation_time (cert) > time (0))
2810
printf ("The certificate is not yet activated\n");
2814
2804
if (!gnutls_x509_crt_check_hostname (cert, hostname))
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");
2970
2963
fprintf (stderr, "\n");
2973
2966
fprintf (stderr, "Trusted\n");
2976
/* Now check the expiration dates.
2978
if (gnutls_x509_crt_get_activation_time (crt) > now)
2979
fprintf (stderr, "Not yet activated\n");
2981
if (gnutls_x509_crt_get_expiration_time (crt) < now)
2982
fprintf (stderr, "Expired\n");
2984
2968
/* Check if the certificate is revoked.
2986
2970
ret = gnutls_x509_crt_check_revocation (crt, crl_list, crl_list_size);
3030
3013
if (output & GNUTLS_CERT_SIGNER_NOT_CA)
3031
3014
fprintf (stderr, ": Issuer is not a CA\n");
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");
3036
3022
fprintf (stderr, "Trusted\n");
3039
/* Now check the expiration dates.
3041
if (gnutls_x509_crt_get_activation_time (crt) > now)
3042
fprintf (stderr, "Not yet activated\n");
3044
if (gnutls_x509_crt_get_expiration_time (crt) < now)
3045
fprintf (stderr, "Expired\n");
3047
3025
/* Check if the certificate is revoked.
3049
3027
ret = gnutls_x509_crt_check_revocation (crt, crl_list, crl_list_size);
3719
3697
printf ("- received %d bytes AVP: `%.*s'\n",
3720
lastlen, (int) lastlen, last);
3698
(int) lastlen, (int) lastlen, last);
3722
3700
printf ("- new application phase\n");
3727
3705
*newlen = strlen (*new);
3729
printf ("- sending %d bytes AVP: `%s'\n", *newlen, *new);
3707
printf ("- sending %d bytes AVP: `%s'\n", (int) *newlen, *new);
3731
3709
gnutls_ia_permute_inner_secret (session, 3, "foo");
5348
5328
printf ("Certificate info:\n");
5330
/* This is the preferred way of printing short information about
5333
ret = gnutls_x509_crt_print (cert, GNUTLS_CRT_PRINT_ONELINE, &cinfo);
5336
printf ("\t%s\n", cinfo.data);
5337
gnutls_free (cinfo.data);
5340
/* If you want to extract fields manually for some other reason,
5341
below are popular example calls. */
5350
5343
expiration_time = gnutls_x509_crt_get_expiration_time (cert);
5351
5344
activation_time = gnutls_x509_crt_get_activation_time (cert);
6758
6751
FUNC: is the callback function
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.
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);
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.
6837
6832
This function does not free any temporary parameters associated
6838
with this structure (ie RSA and DH parameters are not freed by
6833
with this structure (ie RSA and DH parameters are not freed by this
6841
6836
gnutls_certificate_free_crls
6842
6837
----------------------------
6991
6986
FUNC: is the callback function
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.
6991
The callback's function prototype is: int
6992
(*callback)(gnutls_session_t, gnutls_retr_st* st);
6998
6994
`st' should contain the certificates and private keys.
7063
7059
certificates. Flags must be OR of the
7064
7060
`gnutls_certificate_verify_flags' enumerations.
7062
gnutls_certificate_set_verify_function
7063
--------------------------------------
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.
7070
FUNC: is the callback function
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.
7076
The callback's function prototype is: int
7077
(*callback)(gnutls_session_t);
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.
7086
The callback function should return 0 for the handshake to continue
7087
or non-zero to terminate.
7066
7091
gnutls_certificate_set_verify_limits
7067
7092
------------------------------------
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
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'.
7171
7198
Currently only PKCS-1 encoded RSA and DSA private keys are
7172
7199
accepted by this function.
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
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'.
7235
7264
*Returns:* `GNUTLS_E_SUCCESS' on success, or an error code.
7357
7386
TYPE: is DER or PEM
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.
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.
7560
gnutls_cipher_decrypt
7561
---------------------
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.
7567
CIPHERTEXT: the data to encrypt
7569
CIPHERTEXTLEN: The length of data to encrypt
7571
This function will decrypt the given data using the algorithm
7572
specified by the context.
7574
*Returns:* Zero or a negative value on error.
7578
gnutls_cipher_deinit
7579
--------------------
7581
-- Function: void gnutls_cipher_deinit (gnutls_cipher_hd_t HANDLE)
7582
HANDLE: is a `gnutls_cipher_hd_t' structure.
7584
This function will deinitialize all resources occupied by the given
7589
gnutls_cipher_encrypt
7590
---------------------
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.
7596
TEXT: the data to encrypt
7598
TEXTLEN: The length of data to encrypt
7600
This function will encrypt the given data using the algorithm
7601
specified by the context.
7603
*Returns:* Zero or a negative value on error.
7607
gnutls_cipher_get_block_size
7608
----------------------------
7610
-- Function: int gnutls_cipher_get_block_size
7611
(gnutls_cipher_algorithm_t ALGORITHM)
7612
ALGORITHM: is an encryption algorithm
7614
Get block size for encryption algorithm.
7616
*Returns:* block size for encryption algorithm.
7531
7620
gnutls_cipher_get_id
7532
7621
--------------------
7577
7666
*Returns:* the currently used cipher, a `gnutls_cipher_algorithm_t'
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.
7677
CIPHER: the encryption algorithm to use
7679
KEY: The key to be used for encryption
7681
IV: The IV to use (if not applicable set NULL)
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
7688
*Returns:* Zero or a negative value on error.
7580
7692
gnutls_cipher_list
7581
7693
------------------
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 *
7636
7748
IDX: index of cipher suite to get information about, starts on 0.
7638
7750
CS_ID: output buffer with room for 2 bytes, indicating cipher
7645
7757
MAC: output variable indicating MAC algorithm, or `NULL'.
7647
VERSION: output variable indicating TLS protocol version, or
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
------------------------------
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
7780
7889
VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7803
7912
------------------------------
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
7809
7918
VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7829
7938
------------------------------
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
7835
7944
VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7855
7964
---------------------------
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
7861
7970
VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7880
7989
--------------------------
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
7886
7995
VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
7909
8018
---------------------------
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
7915
8024
VERSION: should be set to `GNUTLS_CRYPTO_API_VERSION'
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
7942
8051
PRIORITY: is the priority of the algorithm
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
7971
8080
PRIORITY: is the priority of the algorithm
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
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.
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.
8100
8209
gnutls_db_set_retrieve_function
8715
8824
*Returns:* `GNUTLS_E_SUCCESS' on success, otherwise an error.
8829
-- Function: void gnutls_hash_deinit (gnutls_hash_hd_t HANDLE, void *
8831
HANDLE: is a `gnutls_hash_hd_t' structure.
8833
DIGEST: is the output value of the hash
8835
This function will deinitialize all resources occupied by the
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
8847
TEXT: the data to hash
8849
TEXTLEN: The length of data to hash
8851
DIGEST: is the output value of the hash
8853
This convenience function will hash the given data and return
8854
output on a single call.
8856
*Returns:* Zero or a negative value on error.
8863
-- Function: int gnutls_hash_get_len (gnutls_digest_algorithm_t
8865
ALGORITHM: the hash algorithm to use
8867
This function will return the length of the output data of the
8868
given hash algorithm.
8870
*Returns:* The length or zero on error.
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.
8881
ALGORITHM: the hash algorithm to use
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
8888
*Returns:* Zero or a negative value on error.
8895
-- Function: void gnutls_hash_output (gnutls_hash_hd_t HANDLE, void *
8897
HANDLE: is a `gnutls_hash_hd_t' structure.
8899
DIGEST: is the output value of the hash
8901
This function will output the current hash value.
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.
8912
TEXT: the data to hash
8914
TEXTLEN: The length of data to hash
8916
This function will hash the given data using the algorithm
8917
specified by the context.
8919
*Returns:* Zero or a negative value on error.
8770
8976
*Returns:* `GNUTLS_E_SHORT_MEMORY_BUFFER' if the buffer given is
8771
8977
not long enough, or 0 on success.
8982
-- Function: void gnutls_hmac_deinit (gnutls_hmac_hd_t HANDLE, void *
8984
HANDLE: is a `gnutls_hmac_hd_t' structure.
8986
DIGEST: is the output value of the MAC
8988
This function will deinitialize all resources occupied by the
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
9003
KEYLEN: The length of the key
9005
TEXT: the data to hash
9007
TEXTLEN: The length of data to hash
9009
DIGEST: is the output value of the hash
9011
This convenience function will hash the given data and return
9012
output on a single call.
9014
*Returns:* Zero or a negative value on error.
9021
-- Function: int gnutls_hmac_get_len (gnutls_mac_algorithm_t ALGORITHM)
9022
ALGORITHM: the hmac algorithm to use
9024
This function will return the length of the output data of the
9025
given hmac algorithm.
9027
*Returns:* The length or zero on error.
9034
-- Function: int gnutls_hmac_init (gnutls_hmac_hd_t * DIG,
9035
gnutls_digest_algorithm_t ALGORITHM, const void * KEY, size_t
9037
DIG: is a `gnutls_hmac_hd_t' structure.
9039
ALGORITHM: the HMAC algorithm to use
9041
KEY: The key to be used for encryption
9043
KEYLEN: The length of the key
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.
9050
*Returns:* Zero or a negative value on error.
9057
-- Function: void gnutls_hmac_output (gnutls_hmac_hd_t HANDLE, void *
9059
HANDLE: is a `gnutls_hmac_hd_t' structure.
9061
DIGEST: is the output value of the MAC
9063
This function will output the current MAC value.
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.
9074
TEXT: the data to hash
9076
TEXTLEN: The length of data to hash
9078
This function will hash the given data using the algorithm
9079
specified by the context.
9081
*Returns:* Zero or a negative value on error.
9258
9570
compression methods. This is to avoid using the
9259
9571
gnutls_*`_priority()' functions.
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.
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.
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
9309
9621
"%COMPAT" will enable compatibility features for a server.
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).
9627
"%SAFE_RENEGOTIATION" will allow safe renegotiation only.
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".
9633
"%DISABLE_SAFE_RENEGOTIATION" will disable safe renegotiation
9634
completely. Do not use unless you know what you are doing. Testing
9311
9637
"%SSL3_RECORD_VERSION" will use SSL3.0 record version in client
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
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
9567
9893
*Returns:* `GNUTLS_E_SUCCESS' on success, or an error code.
9691
10017
SESSION: is a `gnutls_session_t' structure.
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.
9838
10164
`gnutls_handshake()' function in order to negotiate the new
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
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
10377
gnutls_safe_negotiation_set_initial
10378
-----------------------------------
10380
-- Function: void gnutls_safe_negotiation_set_initial
10381
(gnutls_session_t SESSION, int VALUE)
10382
SESSION: is a `gnutls_session_t' structure.
10384
VALUE: 0 to disable and 1 to enable
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.
10394
gnutls_safe_renegotiation_set
10395
-----------------------------
10397
-- Function: void gnutls_safe_renegotiation_set (gnutls_session_t
10398
SESSION, int VALUE)
10399
SESSION: is a `gnutls_session_t' structure.
10401
VALUE: 0 to disable and 1 to enable
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.
10410
gnutls_safe_renegotiation_status
10411
--------------------------------
10413
-- Function: int gnutls_safe_renegotiation_status (gnutls_session_t
10415
SESSION: is a `gnutls_session_t' structure.
10417
Can be used to check whether safe renegotiation is being used in
10418
the current session.
10420
*Returns:* 0 when safe renegotiation is not used and non zero when
10421
safe renegotiation is used.
10044
10425
gnutls_server_name_get
10045
10426
----------------------
10587
10968
This function will decode the given encoded data, using the base64
10588
10969
encoding found in libsrp.
10590
Note that b64_data should be null terminated.
10971
Note that `b64_data' should be null terminated.
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
10684
11065
This function can be used to set a callback to retrieve the
10685
username and password for client SRP authentication.
10687
The callback's function form is:
11066
username and password for client SRP authentication. The
11067
callback's function form is:
10689
11069
int (*callback)(gnutls_session_t, char** username, char**password);
10775
11155
FUNC: is the callback function
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:
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);
10858
11239
*Returns:* A string explaining the GnuTLS error message.
11241
gnutls_supplemental_get_name
11242
----------------------------
11244
-- Function: const char * gnutls_supplemental_get_name
11245
(gnutls_supplemental_data_format_type_t TYPE)
11246
TYPE: is a supplemental data format type
11248
Convert a `gnutls_supplemental_data_format_type_t' value to a
11251
*Returns:* a string that contains the name of the specified
11252
supplemental data format type, or `NULL' for unknown types.
10860
11254
gnutls_transport_get_ptr2
10861
11255
-------------------------
10961
11355
SEND_PTR: is the value for the push function
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.
10968
11362
gnutls_transport_set_ptr
10969
11363
------------------------
10975
11369
PTR: is the value.
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
10981
11375
gnutls_transport_set_pull_function
10982
11376
----------------------------------