1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
|
This may not be complete yet. Check at gnutls.h for current information.
All functions return >=0 if everything is ok, or a negative value in case
of a failure. Failure is not always fatal.
int gnutls_init(GNUTLS_STATE * state, ConnectionEnd con_end);
This function just initializes a gnutls state to null.
con_end can be either GNUTLS_CLIENT or GNUTLS_SERVER.
int gnutls_deinit(GNUTLS_STATE state);
This function clears all buffers associated with the state.
int gnutls_handshake(int cd, GNUTLS_STATE state);
This function does the handshake of the TLS/SSL protocol,
and initializes the TLS connection.
It accepts a TCP connection descriptor and a GNUTLS state.
This function will fail if any problem is encountered,
and the connection should be terminated.
int gnutls_handshake_begin(int cd, GNUTLS_STATE state);
This function does the handshake of the TLS/SSL protocol.
This function will fail if any problem is encountered.
However this failure will not be fatal. You may choose to
continue the handshake - eg. even if the certificate cannot
be verified- by calling gnutls_handshake_finish()
int gnutls_handshake_finish(int cd, GNUTLS_STATE state);
This function does the final stuff of the handshake protocol.
This function will fail if any problem is encountered.
int gnutls_close(int cd, GNUTLS_STATE state);
Terminates the current TLS/SSL connection. If it returns 0
you may continue using the TCP connection.
int gnutls_send_hello_request(int cd, GNUTLS_STATE state);
This function will renegotiate security parameters with the
client. This should only be called in case of a server.
If the client does not wish to renegotiate parameters he
will reply with an alert message, thus the return code will be
GNUTLS_E_WARNING_ALERT_RECEIVED and the alert will be
GNUTLS_NO_RENEGOTIATION.
AlertDescription gnutls_get_last_alert( GNUTLS_STATE state);
Returns the last alert number received. This function
should be called if GNUTLS_E_WARNING_ALERT_RECEIVED or
GNUTLS_E_FATAL_ALERT_RECEIVED has been returned by a gnutls
function.
The peer may send alerts if he thinks some things were not
right. Check gnutls.h for the available alert descriptions.
KXAlgorithm gnutls_get_current_kx( GNUTLS_STATE state);
Returns the key exchange algorithm used in the first key exchange.
(There is not key exchange in resumed sessions).
BulkCipherAlgorithm gnutls_get_current_cipher( GNUTLS_STATE state);
Returns the currently used cipher.
char *_gnutls_cipher_get_name(BulkCipherAlgorithm);
Returns a malloc'ed string with the name of the algorithm;
MACAlgorithm gnutls_get_current_mac_algorithm( GNUTLS_STATE state);
Returns the mac algorithm used.
char *_gnutls_mac_get_name(MACAlgorithm);
Returns a malloc'ed string with the name of the algorithm;
CompressionMethod gnutls_get_current_compression_method( GNUTLS_STATE state);
Returns the compression algorithm used.
char *_gnutls_compression_get_name(CompressionMethod);
Returns a malloc'ed string with the name of the algorithm;
int gnutls_is_fatal_error( int error);
If a function returns a negative value you may feed that value
to this function to see if it is fatal. Returns 1 for a fatal
error 0 otherwise. However you may want to check the
error code manual, since some non-fatal errors to the protocol
may be fatal for you (your program).
void gnutls_perror( int error);
char* gnutls_strerror( int error);
These funtions are like perror() and strerror().
gnutls_strerror() returns a malloc'ed value thus it must be
freed.
ssize_t gnutls_write(int cd, GNUTLS_STATE state, void* data, int sizeofdata);
This function has the same semantics as write() has. The only
difference is that is accepts a GNUTLS state.
ssize_t gnutls_read(int cd, GNUTLS_STATE state, void* data, int sizeofdata);
This function has the same semantics as read() has. The only
difference is that is accepts a GNUTLS state.
ssize_t gnutls_recv(int cd, GNUTLS_STATE state, void* data, int sizeofdata, int flags);
This function has the same semantics as recv() has. The only
difference is that is accepts a GNUTLS state. Flags are the flags
passed to recv() and should be used with care in gnutls.
The only acceptable flag is currently MSG_DONTWAIT. In that case,
if the socket is set to non blocking IO it will return GNUTLS_E_AGAIN,
if there are no data in the socket.
ssize_t gnutls_send(int cd, GNUTLS_STATE state, void* data, int sizeofdata, int flags);
This function has the same semantics as send() has. The only
difference is that is accepts a GNUTLS state. Currently flags cannot
be anything except 0.
int gnutls_check_pending( GNUTLS_STATE state);
This function checks if there are any data to receive
in the gnutls buffers. Returns the size of that data or 0.
Notice that you may also use select() to check for data in
the TCP connection, instead of this function.
(gnutls leaves some data in the tcp buffer in order for select
to work).
void gnutls_set_cipher_priority( GNUTLS_STATE state, ...);
Sets the priority on the ciphers supported by gnutls.
Priority is higher for ciphers specified before others.
After specifying the ciphers you want, you should add 0.
Note that the priority is set on the client. The server does
not use the algorithm's priority except for disabling
algorithms that were not specified.
int gnutls_set_kx_cred( GNUTLS_STATE state, int kx, void* cred);
Sets the needed credentials for the specified (in kx) authentication
algorithm. Eg username, password - or public and private keys etc.
The (void* cred) parameter is a structure that depends on the
specified kx algorithm and on the current state (client or server).
[ In order to minimize memory usage, and share credentials between
several threads gnutls keeps a pointer to cred, and not the whole cred
structure. Thus you will have to keep the structure allocated until
you call gnutls_deinit(). ]
* For GNUTLS_KX_DH_ANON cred should be NULL in case of a client.
In case of a server it should be DH_ANON_SERVER_CREDENTIALS.
* For GNUTLS_KX_SRP cred should be SRP_CLIENT_CREDENTIALS
in case of a client, and SRP_SERVER_CREDENTIALS, in case
of a server.
void* gnutls_get_auth_info( GNUTLS_STATE state);
Must be called after a complete gnutls_handshake().
Returns a pointer to authentication information.
* For GNUTLS_KX_ANON returns a pointer to DH_ANON_AUTH_INFO;
* For GNUTLS_KX_SRP returns a pointer to structure SRP_AUTH_INFO.
(you should not free that). Thus you can access the
username he used to connect.
void gnutls_set_kx_priority( GNUTLS_STATE state, ...);
like gnutls_set_cipher_priority, but for key exchange methods.
void gnutls_set_mac_priority( GNUTLS_STATE state, ...);
like gnutls_set_cipher_priority, but for mac algorithms.
void gnutls_set_compression_priority( GNUTLS_STATE state, ...);
like gnutls_set_cipher_priority, but for compression algorithms.
void gnutls_set_current_version(GNUTLS_STATE state, GNUTLS_Version version);
Sets the current SSL/TLS version. Accepted values are GNUTLS_SSL3
and GNUTLS_TLS1.
int gnutls_get_current_session_id( GNUTLS_STATE state, void* session, int *session_size);
Returns the session id. This can be used if you want to check if
the next session you tried to resume was actually resumed.
(resumed sessions have the same sessionID with the first session)
int gnutls_get_current_session( GNUTLS_STATE state, void* session, int *session_size);
Returns all session parameters - in order to support resuming.
The client should call this - and keep the returned session - if he wants to
resume that current version later by calling gnutls_set_current_session().
This function must be called after a successful handshake.
int gnutls_set_current_session( GNUTLS_STATE state, void* session, int session_size);
Sets all session parameters - in order to support resuming
session must be the one returned by get_current_session();
This function should be called before gnutls_handshake_begin.
Keep in mind that session resuming is advisory. The server may
choose not to resume the session, thus a full handshake will be
performed.
int gnutls_set_lowat( GNUTLS_STATE state, int num);
Used to set the lowat value in order for select to check
if there are pending data to socket buffer. Used only
if you have changed the default low water value (default is 1).
Normally you will not need that function.
int gnutls_set_cache_expiration( GNUTLS_STATE state, int seconds);
Sets the expiration time for resumed sessions.
int gnutls_set_db_name( GNUTLS_STATE state, char* filename);
Sets the name of the (gdbm) database to be used to keep
the sessions to be resumed.
int gnutls_clean_db( GNUTLS_STATE state);
Deletes all expired records in the db. This db may become huge
if this is not called.
|
