ftp_client_transport.c
Go to the documentation of this file.
1 /**
2  * @file ftp_client_transport.c
3  * @brief Transport protocol abstraction layer
4  *
5  * @section License
6  *
7  * SPDX-License-Identifier: GPL-2.0-or-later
8  *
9  * Copyright (C) 2010-2024 Oryx Embedded SARL. All rights reserved.
10  *
11  * This file is part of CycloneTCP Open.
12  *
13  * This program is free software; you can redistribute it and/or
14  * modify it under the terms of the GNU General Public License
15  * as published by the Free Software Foundation; either version 2
16  * of the License, or (at your option) any later version.
17  *
18  * This program is distributed in the hope that it will be useful,
19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21  * GNU General Public License for more details.
22  *
23  * You should have received a copy of the GNU General Public License
24  * along with this program; if not, write to the Free Software Foundation,
25  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
26  *
27  * @author Oryx Embedded SARL (www.oryx-embedded.com)
28  * @version 2.4.0
29  **/
30 
31 //Switch to the appropriate trace level
32 #define TRACE_LEVEL FTP_TRACE_LEVEL
33 
34 //Dependencies
35 #include "core/net.h"
36 #include "ftp/ftp_client.h"
38 #include "debug.h"
39 
40 //Check TCP/IP stack configuration
41 #if (FTP_CLIENT_SUPPORT == ENABLED)
42 
43 
44 /**
45  * @brief Open network connection
46  * @param[in] context Pointer to the FTP client context
47  * @param[in] channel Control or data channel
48  * @param[in] txBufferSize TX buffer size
49  * @param[in] rxBufferSize RX buffer size
50  * @return Error code
51  **/
52 
54  FtpClientChannel *channel, size_t txBufferSize, size_t rxBufferSize)
55 {
56  error_t error;
57 
58  //Open a TCP socket
60  //Failed to open socket?
61  if(channel->socket == NULL)
62  return ERROR_OPEN_FAILED;
63 
64  //Associate the socket with the relevant interface
65  error = socketBindToInterface(channel->socket, context->interface);
66  //Any error to report?
67  if(error)
68  return error;
69 
70  //Set timeout
71  error = socketSetTimeout(channel->socket, context->timeout);
72  //Any error to report?
73  if(error)
74  return error;
75 
76  //Specify the size of the send buffer
77  error = socketSetTxBufferSize(channel->socket, txBufferSize);
78  //Any error to report?
79  if(error)
80  return error;
81 
82  //Specify the size of the receive buffer
83  error = socketSetRxBufferSize(channel->socket, rxBufferSize);
84  //Any error to report?
85  if(error)
86  return error;
87 
88  //Successful processing
89  return NO_ERROR;
90 }
91 
92 
93 /**
94  * @brief Open secure connection
95  * @param[in] context Pointer to the FTP client context
96  * @param[in] channel Control or data channel
97  * @param[in] txBufferSize TX buffer size
98  * @param[in] rxBufferSize RX buffer size
99  * @return Error code
100  **/
101 
103  FtpClientChannel *channel, size_t txBufferSize, size_t rxBufferSize)
104 {
105 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
106  error_t error;
107 
108  //Allocate TLS context
109  channel->tlsContext = tlsInit();
110  //Failed to allocate TLS context?
111  if(channel->tlsContext == NULL)
112  return ERROR_OPEN_FAILED;
113 
114  //Select client operation mode
116  //Any error to report?
117  if(error)
118  return error;
119 
120  //Bind TLS to the relevant socket
121  error = tlsSetSocket(channel->tlsContext, channel->socket);
122  //Any error to report?
123  if(error)
124  return error;
125 
126  //Set TX and RX buffer size
127  error = tlsSetBufferSize(channel->tlsContext, txBufferSize, rxBufferSize);
128  //Any error to report?
129  if(error)
130  return error;
131 
132  //Data channel?
133  if(channel == &context->dataChannel)
134  {
135  //Save TLS session from control connection
136  error = tlsSaveSessionState(context->controlChannel.tlsContext,
137  &context->tlsSession);
138  //Any error to report?
139  if(error)
140  return error;
141  }
142 
143  //Restore TLS session
144  error = tlsRestoreSessionState(channel->tlsContext, &context->tlsSession);
145  //Any error to report?
146  if(error)
147  return error;
148 
149  //Invoke user-defined callback, if any
150  if(context->tlsInitCallback != NULL)
151  {
152  //Perform TLS related initialization
153  error = context->tlsInitCallback(context, channel->tlsContext);
154  //Any error to report?
155  if(error)
156  return error;
157  }
158 
159  //Successful processing
160  return NO_ERROR;
161 #else
162  //Not implemented
163  return ERROR_NOT_IMPLEMENTED;
164 #endif
165 }
166 
167 
168 /**
169  * @brief Establish secure connection
170  * @param[in] channel Control or data channel
171  * @return Error code
172  **/
173 
175 {
176 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
177  //Establish TLS connection
178  return tlsConnect(channel->tlsContext);
179 #else
180  //Not implemented
181  return ERROR_NOT_IMPLEMENTED;
182 #endif
183 }
184 
185 
186 /**
187  * @brief Shutdown network connection
188  * @param[in] channel Control or data channel
189  * @return Error code
190  **/
191 
193 {
194  error_t error;
195 
196  //Initialize status code
197  error = NO_ERROR;
198 
199 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
200  //Valid TLS context?
201  if(channel->tlsContext != NULL)
202  {
203  //Shutdown TLS session
204  error = tlsShutdown(channel->tlsContext);
205  }
206 #endif
207 
208  //Check status code
209  if(!error)
210  {
211  //Valid TCP socket?
212  if(channel->socket != NULL)
213  {
214  //Shutdown TCP connection
215  error = socketShutdown(channel->socket, SOCKET_SD_BOTH);
216  }
217  }
218 
219  //Return status code
220  return error;
221 }
222 
223 
224 /**
225  * @brief Close network connection
226  * @param[in] channel Control or data channel
227  **/
228 
230 {
231 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
232  //Release TLS context
233  if(channel->tlsContext != NULL)
234  {
235  tlsFree(channel->tlsContext);
236  channel->tlsContext = NULL;
237  }
238 #endif
239 
240  //Close TCP connection
241  if(channel->socket != NULL)
242  {
243  socketClose(channel->socket);
244  channel->socket = NULL;
245  }
246 }
247 
248 
249 /**
250  * @brief Send data using the relevant transport protocol
251  * @param[in] channel Control or data channel
252  * @param[in] data Pointer to a buffer containing the data to be transmitted
253  * @param[in] length Number of bytes to be transmitted
254  * @param[out] written Actual number of bytes written (optional parameter)
255  * @param[in] flags Set of flags that influences the behavior of this function
256  * @return Error code
257  **/
258 
260  size_t length, size_t *written, uint_t flags)
261 {
262  error_t error;
263 
264 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
265  //TLS-secured connection?
266  if(channel->tlsContext != NULL)
267  {
268  //Send TLS-encrypted data
269  error = tlsWrite(channel->tlsContext, data, length, written, flags);
270  }
271  else
272 #endif
273  {
274  //Transmit data
275  error = socketSend(channel->socket, data, length, written, flags);
276  }
277 
278  //Return status code
279  return error;
280 }
281 
282 
283 /**
284  * @brief Receive data using the relevant transport protocol
285  * @param[in] channel Control or data channel
286  * @param[out] data Buffer into which received data will be placed
287  * @param[in] size Maximum number of bytes that can be received
288  * @param[out] received Number of bytes that have been received
289  * @param[in] flags Set of flags that influences the behavior of this function
290  * @return Error code
291  **/
292 
294  size_t size, size_t *received, uint_t flags)
295 {
296  error_t error;
297 
298 #if (FTP_CLIENT_TLS_SUPPORT == ENABLED)
299  //TLS-secured connection?
300  if(channel->tlsContext != NULL)
301  {
302  //Receive TLS-encrypted data
303  error = tlsRead(channel->tlsContext, data, size, received, flags);
304  }
305  else
306 #endif
307  {
308  //Receive data
309  error = socketReceive(channel->socket, data, size, received, flags);
310  }
311 
312  //Return status code
313  return error;
314 }
315 
316 #endif
unsigned int uint_t
Definition: compiler_port.h:50
Debugging facilities.
error_t
Error codes.
Definition: error.h:43
@ ERROR_NOT_IMPLEMENTED
Definition: error.h:66
@ ERROR_OPEN_FAILED
Definition: error.h:75
@ NO_ERROR
Success.
Definition: error.h:44
uint8_t data[]
Definition: ethernet.h:222
FTP client (File Transfer Protocol)
#define FtpClientContext
Definition: ftp_client.h:128
error_t ftpClientWriteChannel(FtpClientChannel *channel, const void *data, size_t length, size_t *written, uint_t flags)
Send data using the relevant transport protocol.
error_t ftpClientOpenSecureChannel(FtpClientContext *context, FtpClientChannel *channel, size_t txBufferSize, size_t rxBufferSize)
Open secure connection.
error_t ftpClientOpenChannel(FtpClientContext *context, FtpClientChannel *channel, size_t txBufferSize, size_t rxBufferSize)
Open network connection.
error_t ftpClientReadChannel(FtpClientChannel *channel, void *data, size_t size, size_t *received, uint_t flags)
Receive data using the relevant transport protocol.
error_t ftpClientEstablishSecureChannel(FtpClientChannel *channel)
Establish secure connection.
error_t ftpClientShutdownChannel(FtpClientChannel *channel)
Shutdown network connection.
void ftpClientCloseChannel(FtpClientChannel *channel)
Close network connection.
Transport protocol abstraction layer.
TCP/IP stack core.
#define socketBindToInterface
Definition: net_legacy.h:193
error_t socketReceive(Socket *socket, void *data, size_t size, size_t *received, uint_t flags)
Receive data from a connected socket.
Definition: socket.c:1152
Socket * socketOpen(uint_t type, uint_t protocol)
Create a socket (UDP or TCP)
Definition: socket.c:125
error_t socketSend(Socket *socket, const void *data, size_t length, size_t *written, uint_t flags)
Send data to a connected socket.
Definition: socket.c:946
error_t socketSetTimeout(Socket *socket, systime_t timeout)
Set timeout value for blocking operations.
Definition: socket.c:148
void socketClose(Socket *socket)
Close an existing socket.
Definition: socket.c:1517
error_t socketShutdown(Socket *socket, uint_t how)
Disable reception, transmission, or both.
Definition: socket.c:1480
error_t socketSetRxBufferSize(Socket *socket, size_t size)
Specify the size of the TCP receive buffer.
Definition: socket.c:699
error_t socketSetTxBufferSize(Socket *socket, size_t size)
Specify the size of the TCP send buffer.
Definition: socket.c:663
@ SOCKET_SD_BOTH
Definition: socket.h:151
@ SOCKET_IP_PROTO_TCP
Definition: socket.h:100
@ SOCKET_TYPE_STREAM
Definition: socket.h:85
Control or data channel.
Definition: ftp_client.h:234
TlsContext * tlsContext
TLS context.
Definition: ftp_client.h:237
Socket * socket
Underlying TCP socket.
Definition: ftp_client.h:235
uint8_t length
Definition: tcp.h:368
uint8_t flags
Definition: tcp.h:351
error_t tlsRestoreSessionState(TlsContext *context, const TlsSessionState *session)
Restore TLS session.
Definition: tls.c:2690
error_t tlsConnect(TlsContext *context)
Initiate the TLS handshake.
Definition: tls.c:1758
error_t tlsSaveSessionState(const TlsContext *context, TlsSessionState *session)
Save TLS session.
Definition: tls.c:2621
error_t tlsWrite(TlsContext *context, const void *data, size_t length, size_t *written, uint_t flags)
Send application data to the remote host using TLS.
Definition: tls.c:1849
TlsContext * tlsInit(void)
TLS context initialization.
Definition: tls.c:65
error_t tlsRead(TlsContext *context, void *data, size_t size, size_t *received, uint_t flags)
Receive application data from a the remote host using TLS.
Definition: tls.c:1984
error_t tlsSetConnectionEnd(TlsContext *context, TlsConnectionEnd entity)
Set operation mode (client or server)
Definition: tls.c:344
error_t tlsSetBufferSize(TlsContext *context, size_t txBufferSize, size_t rxBufferSize)
Set TLS buffer size.
Definition: tls.c:516
error_t tlsShutdown(TlsContext *context)
Gracefully close TLS session.
Definition: tls.c:2302
void tlsFree(TlsContext *context)
Release TLS context.
Definition: tls.c:2464
@ TLS_CONNECTION_END_CLIENT
Definition: tls.h:953
#define tlsSetSocket(context, socket)
Definition: tls.h:912