Synapse: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		Synapse provides an easy to use serial port and synchronous TCP/IP library.
2	2
3	3		## Overview
4	4
5	5		Synapse offers [[Hardware Access\|serial]] port and TCP/IP connectivity. It differs from other libraries that you only require to add some Synapse Pascal source code files to your code; no need for installing packages etc. The only exception is that you will need an external crypto library if you want to use encryption such as SSL/TLS/SSH.
6	6
7	7		See the documentation on the official site (link below) for more details.
8	8
9	9		## Installation
10	10
11	11		Installation can be as simple as simply copying over all files to your application directory and adding the relevant Synapse units to your uses clause.
12	12
13	13		A more elegant and recommended way is compiling the laz_synapse.lpk package so you can use the same units in all your projects.
14	14
15	15		Synapse download / Wiki info page: [Download and Wiki](https://github.com/geby/synapse)
16	16
17	17		## Support and bug reporting
18	18
19	19		The Synapse project has a mailing list where support is given and patches can be submitted.
20	20
21	21		Bug reports can also be mailed to the mailing list.
22	22
23	23		See the [Synapse support page](http://www.ararat.cz/synapse/doku.php/support) and some well presented [on line help](http://synapse.ararat.cz/doc/help/)
24	24
25	25		## SSL/TLS support
26	26
27	27		You can use OpenSSL, CryptLib, StreamSecII or OpenStreamSecII SSL support with Synapse. By default, no SSL support is used.
28	28
29	29		The support is activated by putting the chosen unit name in the uses section in your project. You also have to put the binary library file in your project path (Windows), or install it into your library search path (Linux, macOS, FreeBSD).
30	30
31	31		Synapse loads SSL library files in runtime as dynamic libraries.
32	32
33	33		- For detailed information refer to [SSL/TLS Plugin Architecture](http://www.ararat.cz/synapse/doku.php/public:howto:sslplugin)
34	34		- Some crypt libraries can be obtained from: <http://synapse.ararat.cz/files/crypt/>
35	35
36	36		### Missing library
37	37
38	38		On Linux you need to make sure the required dynamic library is present/installed on your system. In case of cryptlib if the library is not present on the system, an error message appears during linking:
39	39
40		-	~~`/usr/bin/ld: cannot find -lcl`~~
	40	+	```text
	41	+	/usr/bin/ld: cannot find -lcl
	42	+	```
41	43
42	44		A similar message will be displayed when using other dynamic libraries.
43	45
44	46		## Web server example
45	47
46	48		See the [[Networking\|Webserver example]].
47	49
48	50		## QOTD server query example
49	51
50	52		See the [[QOTD\|Quote of the Day server query example]].
51	53
52	54		## Sending email
53	55
54	56		Refer to the [[Synapse - Email Examples]] article.
55	57
56	58		## Downloading files
57	59
58	60		### From an FTP server
59	61
60	62		Given an URL and a (path and) file name, this will download it from an FTP server. It's mostly a wrapper around the Synapse code meant to make downloading easier when handling arbitrary files. If you know exactly what you're going to download where, just a call to Synapse:
61	63
62	64		``` pascal
63	65		FtpGetFile
64	66		```
65	67
66	68		will get you very far.
67	69
68	70		``` pascal
69	71		function DownloadFTP(URL, TargetFile: string): boolean;
70	72		const
71	73		FTPPort=21;
72	74		FTPScheme='ftp://'; //URI scheme name for FTP URLs
73	75		var
74	76		Host: string;
75	77		Port: integer;
76	78		Source: string;
77	79		FoundPos: integer;
78	80		begin
79	81		// Strip out scheme info:
80	82		if LeftStr(URL, length(FTPScheme))=FTPScheme then URL:=Copy(URL, length(FTPScheme)+1, length(URL));
81	83
82	84		// Crude parsing; could have used URI parsing code in FPC packages...
83	85		FoundPos:=pos('/', URL);
84	86		Host:=LeftStr(URL, FoundPos-1);
85	87		Source:=Copy(URL, FoundPos+1, Length(URL));
86	88
87	89		//Check for port numbers:
88	90		FoundPos:=pos(':', Host);
89	91		Port:=FTPPort;
90	92		if FoundPos>0 then
91	93		begin
92	94		Host:=LeftStr(Host, FoundPos-1);
93	95		Port:=StrToIntDef(Copy(Host, FoundPos+1, Length(Host)),21);
94	96		end;
95	97		Result:=FtpGetFile(Host, IntToStr(Port), Source, TargetFile, 'anonymous', 'fpc@example.com');
96	98		if result=false then writeln('DownloadFTP: error downloading '+URL+'. Details: host: '+Host+'; port: '+Inttostr(Port)+'; remote path: '+Source+' to '+TargetFile);
97	99		end;
98	100		```
99	101
100	102		Example to get list of files in given path
101	103
102	104		``` pascal
103	105		//Use ftpsend unit
104	106
105	107		function FtpGetDir(const IP, Port, Path, User, Pass: string; DirList: TStringList): Boolean;
106	108		var
107	109		i: Integer;
108	110		s: string;
109	111		begin
110	112		Result := False;
111	113		with TFTPSend.Create do
112	114		try
113	115		Username := User;
114	116		Password := Pass;
115	117		TargetHost := IP;
116	118		TargetPort := Port;
117	119		if not Login then
118	120		Exit;
119	121		Result := List(Path, False);
120	122		for i := 0 to FtpList.Count -1 do
121	123		begin
122	124		s := FTPList[i].FileName;
123	125		DirList.Add(s);
124	126		end;
125	127		Logout;
126	128		finally
127	129		Free;
128	130		end;
129	131		end;
130	132		```
131	133
132	134		### From an HTTP server
133	135
134	136		Given an URL and a (path and) file name, this will download it from an HTTP server. Note that this code checks the HTTP status code (like 200, 404) to see if the document we got back from the server is the desired file or an error page.
135	137
136	138		#### Simple version
137	139
138	140		``` pascal
139	141		...
140	142		uses httpsend,
141	143		...
142	144		function DownloadHTTP(URL, TargetFile: string): Boolean;
143	145		var
144	146		HTTPGetResult: Boolean;
145	147		HTTPSender: THTTPSend;
146	148		begin
147	149		Result := False;
148	150		HTTPSender := THTTPSend.Create;
149	151		try
150	152		HTTPGetResult := HTTPSender.HTTPMethod('GET', URL);
151	153		if (HTTPSender.ResultCode >= 100) and (HTTPSender.ResultCode<=299) then begin
152	154		HTTPSender.Document.SaveToFile(TargetFile);
153	155		Result := True;
154	156		end;
155	157		finally
156	158		HTTPSender.Free;
157	159		end;
158	160		end;
159	161		```
160	162
161	163		#### Advanced version
162	164
163	165		``` pascal
164	166		...
165	167		uses httpsend
166	168		...
167	169		function DownloadHTTP(URL, TargetFile: string): Boolean;
168	170		// Download file; retry if necessary.
169	171		// Could use Synapse HttpGetBinary, but that doesn't deal
170	172		// with result codes (i.e. it happily downloads a 404 error document)
171	173		const
172	174		MaxRetries = 3;
173	175		var
174	176		HTTPGetResult: Boolean;
175	177		HTTPSender: THTTPSend;
176	178		RetryAttempt: Integer;
177	179		begin
178	180		Result := False;
179	181		RetryAttempt := 1;
180	182		HTTPSender := THTTPSend.Create;
181	183		try
182	184		try
183	185		// Try to get the file
184	186		HTTPGetResult := HTTPSender.HTTPMethod('GET', URL);
185	187		while (HTTPGetResult = False) and (RetryAttempt < MaxRetries) do
186	188		begin
187	189		Sleep(500 * RetryAttempt);
188	190		HTTPSender.Clear;
189	191		HTTPGetResult := HTTPSender.HTTPMethod('GET', URL);
190	192		RetryAttempt := RetryAttempt + 1;
191	193		end;
192	194		// If we have an answer from the server, check if the file
193	195		// was sent to us.
194	196		case HTTPSender.Resultcode of
195	197		100..299:
196	198		begin
197	199		HTTPSender.Document.SaveToFile(TargetFile);
198	200		Result := True;
199	201		end; //informational, success
200	202		300..399: Result := False; // redirection. Not implemented, but could be.
201	203		400..499: Result := False; // client error; 404 not found etc
202	204		500..599: Result := False; // internal server error
203	205		else Result := False; // unknown code
204	206		end;
205	207		except
206	208		// We don't care for the reason for this error; the download failed.
207	209		Result := False;
208	210		end;
209	211		finally
210	212		HTTPSender.Free;
211	213		end;
212	214		end;
213	215		```
214	216
215	217		#### Simple version with progress
216	218
217	219		The following example shows how to get progress information from the HTTP download, as well as the file size. The file size is retrieved from the header information.
218	220
219	221		``` pascal
220	222		unit uhttpdownloader;
221	223
222	224		// Essential to change this. The default is {$mode objfpc}{$H+} and does not work.
223	225		{$mode Delphi}
224	226
225	227		interface
226	228
227	229		uses
228	230		Classes, SysUtils, httpsend, blcksock, typinfo;
229	231
230	232		type
231	233		IProgress = interface
232	234		procedure ProgressNotification(Text: String; CurrentProgress : integer; MaxProgress : integer);
233	235		end;
234	236
235	237		type
236	238		{ THttpDownloader }
237	239
238	240		THttpDownloader = class
239	241		public
240	242		function DownloadHTTP(URL, TargetFile: string; ProgressMonitor : IProgress): Boolean;
241	243		private
242	244		Bytes : Integer;
243	245		MaxBytes : Integer;
244	246		HTTPSender: THTTPSend;
245	247		ProgressMonitor : IProgress;
246	248		procedure Status(Sender: TObject; Reason: THookSocketReason; const Value: String);
247	249		function GetSizeFromHeader(Header: String):integer;
248	250		end;
249	251
250	252		implementation
251	253
252	254		function THttpDownloader.DownloadHTTP(URL, TargetFile: string; ProgressMonitor : IProgress): Boolean;
253	255		var
254	256		HTTPGetResult: Boolean;
255	257		begin
256	258		Result := False;
257	259		Bytes:= 0;
258	260		MaxBytes:= -1;
259	261		Self.ProgressMonitor:= ProgressMonitor;
260	262
261	263		HTTPSender := THTTPSend.Create;
262	264		try
263	265		HTTPSender.Sock.OnStatus:= Status;
264	266		HTTPGetResult := HTTPSender.HTTPMethod('GET', URL);
265	267		if (HTTPSender.ResultCode >= 100) and (HTTPSender.ResultCode<=299) then begin
266	268		HTTPSender.Document.SaveToFile(TargetFile);
267	269		Result := True;
268	270		end;
269	271		finally
270	272		HTTPSender.Free;
271	273		end;
272	274		end;
273	275
274	276		procedure THttpDownloader.Status(Sender: TObject; Reason: THookSocketReason; const Value: String);
275	277		var
276	278		V, currentHeader: String;
277	279		i: integer;
278	280		begin
279	281		//try to get filesize from headers
280	282		if (MaxBytes = -1) then
281	283		begin
282	284		for i:= 0 to HTTPSender.Headers.Count - 1 do
283	285		begin
284	286		currentHeader:= HTTPSender.Headers[i];
285	287		MaxBytes:= GetSizeFromHeader(currentHeader);
286	288		if MaxBytes <> -1 then break;
287	289		end;
288	290		end;
289	291
290	292		V := GetEnumName(TypeInfo(THookSocketReason), Integer(Reason)) + ' ' + Value;
291	293
292	294		if Reason = THookSocketReason.HR_ReadCount then
293	295		begin
294	296		Bytes:= Bytes + StrToInt(Value);
295	297		ProgressMonitor.ProgressNotification(V, Bytes, MaxBytes);
296	298		end;
297	299		end;
298	300
299	301		function THttpDownloader.GetSizeFromHeader(Header: String): integer;
300	302		var
301	303		item : TStringList;
302	304		begin
303	305		Result:= -1;
304	306
305	307		if Pos('Content-Length:', Header) <> 0 then
306	308		begin
307	309		item:= TStringList.Create();
308	310		item.Delimiter:= ':';
309	311		item.StrictDelimiter:=true;
310	312		item.DelimitedText:=Header;
311	313		if item.Count = 2 then
312	314		begin
313	315		Result:= StrToInt(Trim(item[1]));
314	316		end;
315	317		end;
316	318		end;
317	319
318	320		end.
319	321		```
320	322
321	323		What are we doing here?
322	324
323	325		First of all we look into the headers to get the file size. We have to wait and check if the header is there. The first events do not contain the Content-Length: information.
324	326
325	327		Once found, we extract that information. There are several events popping up here, which you can react to. But we only check for THookSocketReason.HR_ReadCount in that example.
326	328
327	329		"HR_ReadCount" provides us with the information how many bytes where read since the last event.
328	330
329	331		The progress is then reported to the UI:
330	332
331	333		``` pascal
332	334		procedure TMainForm.ProgressNotification(Text: String; CurrentProgress: integer; MaxProgress: integer);
333	335		begin
334	336		if (MaxProgress <> -1) then
335	337		begin
336	338		ProgressBar.Max:= MaxProgress;
337	339		end;
338	340
339	341		ProgressBar.Position:= CurrentProgress;
340	342		memoStatus.Lines.Add(Text);
341	343		Application.ProcessMessages;
342	344		end;
343	345		```
344	346
345	347		So, the final main unit will be:
346	348
347	349		``` pascal
348	350		unit uMain;
349	351
350	352		{$mode Delphi}
351	353
352	354		interface
353	355
354	356		uses
355	357		Classes, SysUtils, FileUtil, Forms, Controls, Graphics, Dialogs, StdCtrls, ComCtrls, httpsend, blcksock, typinfo,
356	358		uhttpdownloader;
357	359
358	360		type
359	361
360	362		{ TMainForm }
361	363
362	364		TMainForm = class(TForm, IProgress)
363	365		btnStartDownload: TButton;
364	366		edtUrl: TEdit;
365	367		labelUrl: TLabel;
366	368		memoStatus: TMemo;
367	369		ProgressBar: TProgressBar;
368	370		SaveDialog: TSaveDialog;
369	371		procedure btnStartDownloadClick(Sender: TObject);
370	372		private
371	373		{ private declarations }
372	374		function GetFileNameFromURL(url: String):string;
373	375		public
374	376		{ public declarations }
375	377		procedure ProgressNotification(Text: String; CurrentProgress : integer; MaxProgress : integer);
376	378		end;
377	379
378	380		var
379	381		MainForm: TMainForm;
380	382
381	383		implementation
382	384
383	385		{$R *.lfm}
384	386
385	387		{ TMainForm }
386	388
387	389		procedure TMainForm.btnStartDownloadClick(Sender: TObject);
388	390		var
389	391		fileName: String;
390	392		downloader: THttpDownloader;
391	393		success: boolean;
392	394		begin
393	395		fileName:= GetFileNameFromURL(edtUrl.Text);
394	396		SaveDialog.FileName:=fileName;
395	397		if (SaveDialog.Execute) then
396	398		begin
397	399		memoStatus.Lines.Clear;
398	400		ProgressBar.Position:=0;
399	401		downloader:= THttpDownloader.Create();
400	402		success:= downloader.DownloadHTTP(edtUrl.Text, SaveDialog.FileName, Self);
401	403
402	404		ProgressBar.Position:=0;
403	405		if Success then
404	406		memoStatus.Lines.Add('Download successful')
405	407		else
406	408		memoStatus.Lines.Add('Error during download');
407	409
408	410		end;
409	411		end;
410	412
411	413		function TMainForm.GetFileNameFromURL(url: String): string;
412	414		var i, l : integer;
413	415		fileName, current : String;
414	416		begin
415	417		fileName:= '';
416	418		l:= Length(url);
417	419		for i:= l downto 0 do begin
418	420		current:= url[i];
419	421		if current <> '/' then
420	422		begin
421	423		fileName:= current + fileName;
422	424		end else begin
423	425		Result:= fileName;
424	426		break;
425	427		end;
426	428		end;
427	429		end;
428	430
429	431		procedure TMainForm.ProgressNotification(Text: String; CurrentProgress: integer; MaxProgress: integer);
430	432		begin
431	433		if (MaxProgress <> -1) then ProgressBar.Max:= MaxProgress;
432	434		ProgressBar.Position:= CurrentProgress;
433	435		memoStatus.Lines.Add(Text);
434	436		Application.ProcessMessages;
435	437		end;
436	438
437	439		end.
438	440		```
439	441
440	442		Reference: <https://andydunkel.net/2015/09/09/lazarus_synapse_progress/>
441	443
442	444		#### From an HTTP server by parsing URLs: Sourceforge
443	445
444	446		Please see [[Download from SourceForge]] for an example of downloading from sourceforge.net.
445	447
446	448		### From an HTTPS server
447	449
448	450		This is similar to downloading from an HTTP server. In addition you need to [[Synapse\|activate SSL/TLS support]] and obtain the binary file(s) for the needed library. Then you can use the same DownloadHTTP function for downloading a file from a URL starting with <https://>.
449	451
450	452		## SSH/Telnet client sample program
451	453
452	454		Below you will find a unit that allows you to use telnet/SSH client functionality that uses the synapse tlntsend.pas unit. An example program shows how to use this. A different, simpler way is illustrated by Leonardo Ramé at [1](http://leonardorame.blogspot.com/2010/01/synapse-based-ssh-client.html). His example cannot use telnet and only sends one command, though.
453	455
454	456		### Requirements
455	457
456	458		Apart from the Synapse sources (of which you only need a couple), if you want to use SSH functionality, you will need an encryption library that Synapse uses. If you only use Telnet, you don't need this.
457	459
458	460		There are 2 choices:
459	461
460	462		- Cryptlib library. Advantage: stable. Apparently able to use private keys but these are in some format that is not widely supported.
461	463		- LibSSH2 library. Pascal bindings still in development, but you can use a file with your private key (in OpenSSH format) to authenticate.
462	464
463	465		#### Cryptlib
464	466
465	467		- On Windows, download a binary version of the cryptlib DLL (CL32.DLL) and put it in your source directory. If you compile to a different directory or distribute your program, you will need to distribute the DLL as well.
466	468		- On Linux and OSX, install cryptlib via your package manager/other means. When distributing your application, mark cryptlib as a requirement in your .deb/.rpm/whatever package.
467	469
468	470		You will also need the bindings (cryptlib.pas), present in the source distribution of cryptlib.
469	471
470	472		The versions of the cryptlib binary and the bindings must match.
471	473
472	474		> Note: It seems that cryptlib is not suitable to connect to linux machines, though AIX works. Use SSH2 instead.
473	475
474	476		#### LibSSH2
475	477
476	478		- On Windows, download a binary version of the libssh2 DLL (LIBSSH2.DLL) and put it in your source directory. If you compile to a different directory or distribute your program, you will need to distribute the DLL as well.
477	479		- On Linux and macOS, install libssh2 via your package manager/other means. When distributing your application:
478	480		- Linux: mark libssh2 as a requirement in your .deb/.rpm/whatever package.
479	481		- macOS: include libssh2 in your [[Application Bundle]]'s Resources directory.
480	482
481	483		You will also need ssl_libssh2.pas (see below) and the bindings: (libssh2.pas, see [this forum post](http://www.lazarus.freepascal.org/index.php/topic,15935.msg86465.html#msg86465)). The libssh2 binary and the bindings must match.
482	484
483	485		### Synapse libssh2 SSL plugin
484	486
485	487		> Note: plugin is not completed.
486	488
487	489		``` pascal
488	490		{
489	491		ssl_libssh2.pas version 0.2
490	492
491	493		SSH2 support (draft) plugin for Synapse Library (http://www.ararat.cz/synapse) by LibSSH2 (http://libssh2.org)
492	494		Requires: libssh2 pascal interface - http://www.lazarus.freepascal.org/index.php/topic,15935.msg86465.html#msg86465 and
493	495		libssh2.dll with OpenSSL.
494	496
495	497		(С) Alexey Suhinin http://x-alexey.narod.ru
496	498		}
497	499
498	500		{$IFDEF FPC}
499	501		{$MODE DELPHI}
500	502		{$ENDIF}
501	503		{$H+}
502	504
503	505		unit ssl_libssh2;
504	506
505	507		interface
506	508
507	509		uses
508	510		SysUtils,
509	511		blcksock, synsock,
510	512		libssh2;
511	513
512	514		type
513	515		{:@abstract(class implementing CryptLib SSL/SSH plugin.)
514	516		Instance of this class will be created for each @link(TTCPBlockSocket).
515	517		You not need to create instance of this class, all is done by Synapse itself!}
516	518		TSSLLibSSH2 = class(TCustomSSL)
517	519		protected
518	520		FSession: PLIBSSH2_SESSION;
519	521		FChannel: PLIBSSH2_CHANNEL;
520	522		function SSHCheck(Value: integer): Boolean;
521	523		function DeInit: Boolean;
522	524		public
523	525		{:See @inherited}
524	526		constructor Create(const Value: TTCPBlockSocket); override;
525	527		destructor Destroy; override;
526	528		function Connect: boolean; override;
527	529		function LibName: String; override;
528	530		function Shutdown: boolean; override;
529	531		{:See @inherited}
530	532		function BiShutdown: boolean; override;
531	533		{:See @inherited}
532	534		function SendBuffer(Buffer: TMemory; Len: Integer): Integer; override;
533	535		{:See @inherited}
534	536		function RecvBuffer(Buffer: TMemory; Len: Integer): Integer; override;
535	537		{:See @inherited}
536	538		function WaitingData: Integer; override;
537	539		{:See @inherited}
538	540		function GetSSLVersion: string; override;
539	541		published
540	542		end;
541	543
542	544		implementation
543	545
544	546		{==============================================================================}
545	547		function TSSLLibSSH2.SSHCheck(Value: integer): Boolean;
546	548		var
547	549		PLastError: PAnsiChar;
548	550		ErrMsgLen: Integer;
549	551		begin
550	552		Result := true;
551	553		FLastError := 0;
552	554		FLastErrorDesc := '';
553	555		if Value<0 then
554	556		begin
555	557		FLastError := libssh2_session_last_error(FSession, PLastError, ErrMsglen, 0);
556	558		FLastErrorDesc := PLastError;
557	559		Result := false;
558	560		end;
559	561		end;
560	562
561	563		function TSSLLibSSH2.DeInit: Boolean;
562	564		begin
563	565		if Assigned(FChannel) then
564	566		begin
565	567		libssh2_channel_free(FChannel);
566	568		FChannel := nil;
567	569		end;
568	570		if Assigned(FSession) then
569	571		begin
570	572		libssh2_session_disconnect(FSession,'Goodbye');
571	573		libssh2_session_free(FSession);
572	574		FSession := nil;
573	575		end;
574	576		FSSLEnabled := False;
575	577		Result := true;
576	578		end;
577	579
578	580		constructor TSSLLibSSH2.Create(const Value: TTCPBlockSocket);
579	581		begin
580	582		inherited Create(Value);
581	583		FSession := nil;
582	584		FChannel := nil;
583	585		end;
584	586
585	587		destructor TSSLLibSSH2.Destroy;
586	588		begin
587	589		DeInit;
588	590		inherited Destroy;
589	591		end;
590	592
591	593		function TSSLLibSSH2.Connect: boolean;
592	594		begin
593	595		Result := False;
594	596		if SSLEnabled then DeInit;
595	597		if (FSocket.Socket <> INVALID_SOCKET) and (FSocket.SSL.SSLType = LT_SSHv2) then
596	598		begin
597	599		FSession := libssh2_session_init();
598	600		if not Assigned(FSession) then
599	601		begin
600	602		FLastError := -999;
601	603		FLastErrorDesc := 'Cannot initialize SSH session';
602	604		exit;
603	605		end;
604	606		if not SSHCheck(libssh2_session_startup(FSession, FSocket.Socket)) then
605	607		exit;
606	608		if (FSocket.SSL.PrivateKeyFile<>'') then
607	609		begin
608	610		if (not SSHCheck(libssh2_userauth_publickey_fromfile(FSession, PChar(FSocket.SSL.Username), nil, PChar(FSocket.SSL.PrivateKeyFile), PChar(FSocket.SSL.KeyPassword)))) then
609	611		exit;
610	612		end
611	613		else
612	614		if (FSocket.SSL.Username<>'') and (FSocket.SSL.Password<>'') then
613	615		begin
614	616		if (not SSHCheck(libssh2_userauth_password(FSession, PChar(FSocket.SSL.Username), PChar(FSocket.SSL.Password)))) then
615	617		exit;
616	618		end;
617	619		FChannel := libssh2_channel_open_session(FSession);
618	620		if not assigned(FChannel) then
619	621		begin
620	622		SSHCheck(-1); // get error
621	623		if FLastError = 0 then
622	624		begin
623	625		FLastError := -999; // unknown error
624	626		FLastErrorDesc := 'Cannot open session';
625	627		end;
626	628		exit;
627	629		end;
628	630		if not SSHCheck(libssh2_channel_request_pty(FChannel, 'vanilla')) then
629	631		exit;
630	632		if not SSHCheck(libssh2_channel_shell(FChannel)) then
631	633		exit;
632	634		FSSLEnabled := True;
633	635		Result := True;
634	636		end;
635	637		end;
636	638
637	639		function TSSLLibSSH2.LibName: String;
638	640		begin
639	641		Result := 'ssl_libssh2';
640	642		end;
641	643
642	644		function TSSLLibSSH2.Shutdown: boolean;
643	645		begin
644	646		Result := DeInit;
645	647		end;
646	648
647	649		function TSSLLibSSH2.BiShutdown: boolean;
648	650		begin
649	651		Result := DeInit;
650	652		end;
651	653
652	654		function TSSLLibSSH2.SendBuffer(Buffer: TMemory; Len: Integer): Integer;
653	655		begin
654	656		Result:=libssh2_channel_write(FChannel, PChar(Buffer), Len);
655	657		SSHCheck(Result);
656	658		end;
657	659
658	660		function TSSLLibSSH2.RecvBuffer(Buffer: TMemory; Len: Integer): Integer;
659	661		begin
660	662		result:=libssh2_channel_read(FChannel, PChar(Buffer), Len);
661	663		SSHCheck(Result);
662	664		end;
663	665
664	666		function TSSLLibSSH2.WaitingData: Integer;
665	667		begin
666	668		if libssh2_poll_channel_read(FChannel, Result) <> 1 then Result := 0;
667	669		end;
668	670
669	671		function TSSLLibSSH2.GetSSLVersion: string;
670	672		begin
671	673		Result:=libssh2_version(0);
672	674		end;
673	675
674	676		initialization
675	677		if libssh2_init(0)=0 then
676	678		SSLImplementation := TSSLLibSSH2;
677	679
678	680		finalization
679	681		libssh2_exit;
680	682
681	683		end.
682	684		```
683	685
684	686		### Terminal client class
685	687
686	688		The telnetsshclient.pas unit below wraps around the Synapse tlntsend.pas unit and abstracts logging in, sending commands and receiving output and logging out.
687	689
688	690		If you only need a telnet client and can live without SSH support, comment out {\$DEFINE HAS_SSH_SUPPORT} below so you don't need to have the libssh2 dll.
689	691
690	692		This unit has been lightly tested on a Linux ssh/telnet server. Additional tests welcome.
691	693
692	694		``` pascal
693	695		unit telnetsshclient;
694	696
695	697		{ Wrapper around Synapse libraries and SSL library (libssh2+libssl
696	698		is used right now)
697	699		Download compiled Windows dll from e.g.
698	700		http://alxdm.dyndns-at-work.com:808/files/windll_libssh2.zip
699	701		Download FreePascal interface files:
700	702		http://www.lazarus.freepascal.org/index.php/topic,15935.msg86465.html#msg86465
701	703
702	704		This unit allows the user to send Telnet or SSH commands and get the output
703	705		Thanks to Leonardo Rame
704	706		http://leonardorame.blogspot.com/2010/01/synapse-based-ssh-client.html
705	707		and Ludo Brands.
706	708
707	709		Written by Reinier Olislagers 2011.
708	710		Modified for libssh2 by Alexey Suhinin 2012.
709	711
710	712		License of code:
711	713		* MIT
712	714		* LGPLv2 or later (with FreePascal static linking exception)
713	715		* GPLv2 or later
714	716		according to your choice.
715	717		Free use allowed but please don't sue or blame me.
716	718
717	719		Uses other libraries/components; different licenses may apply that also can influence the combined/compiled work.
718	720		}
719	721
720	722		{$mode objfpc}{$H+}
721	723		{$DEFINE HAS_SSH_SUPPORT} //comment out if only telnet support required
722	724		{$DEFINE LIBSSH2}
723	725
724	726		interface
725	727
726	728		uses
727	729		Classes, SysUtils,
728	730		tlntsend
729	731		{$IFDEF HAS_SSH_SUPPORT}
730	732		{ssl - or actually ssh - libs required by tlntsend}
731	733		{$IFDEF LIBSSH2}
732	734		ssl_libssh2
733	735		{$ELSE}
734	736		ssl_cryptlib
735	737		{$ENDIF}
736	738		{$ENDIF HAS_SSH_SUPPORT} ;
737	739
738	740		type
739	741		TProtocolType = (Telnet, SSH); //Different means of connecting
740	742		TServerType = (Unix, Windows); //line endings, mostly
741	743		{ TelnetSSHClient }
742	744
743	745		{ TTelnetSSHClient }
744	746
745	747		TTelnetSSHClient = class(TTelnetSend)
746	748		protected
747	749		FConnected: boolean;
748	750		FOutputPosition: integer; //Keeps track of position in output stream
749	751		FProtocolType: TProtocolType;
750	752		FServerLineEnding: string; //depends on FServerType
751	753		FServerType: TServerType;
752	754		FWelcomeMessage, FTelnetLoginPrompt, FTelnetPasswordPrompt: string;
753	755		procedure SetPrivateKeyFile(Value: string);
754	756		function GetPrivateKeyFile: string;
755	757		{ Based on protocol and servertype, set expected serverside line ending}
756	758		procedure DetermineLineEnding;
757	759		{ Sets port if no explicit port set. Uses protocol type: SSH or telnet}
758	760		procedure DeterminePort;
759	761		function GetSessionLog: string;
760	762		procedure ProtocolTypeChange(Value: TProtocolType);
761	763		function ReceiveData: string; //Can be used to get welcome message etc.
762	764		procedure SendData(Data: string);
763	765		procedure ServerTypeChange(Value: TServerType);
764	766		public
765	767		{All output generated during the entire session up to now}
766	768		property AllOutput: string read GetSessionLog;
767	769		{True if connected to server}
768	770		property Connected: boolean read FConnected;
769	771		{Name or IP address of host to connect to}
770	772		property HostName: string read FTargetHost write FTargetHost;
771	773		{Port on host used for connection. If left as 0, it will be determined by protocol type (22 for SSH, 23 for Telnet}
772	774		property Port: String read FTargetPort write FTargetPort;
773	775		{Location of private key file.}
774	776		property PrivateKeyFile: string read GetPrivateKeyFile write SetPrivateKeyFile;
775	777		{Telnet login prompt}
776	778		property TelnetLoginPrompt: string read FTelnetLoginPrompt write FTelnetLoginPrompt;
777	779		{Telnet password prompt}
778	780		property TelnetPasswordPrompt: string read FTelnetPasswordPrompt write FTelnetPasswordPrompt;
779	781		{Username used when connecting}
780	782		property UserName: string read FUserName write FUserName;
781	783		{Password used when connecting. Used as passphrase if PrivateKey is used}
782	784		property Password: string read FPassword write FPassword;
783	785		{Should we talk Telnet or SSH to the server? Defaults to SSH.}
784	786		property ProtocolType: TProtocolType read FProtocolType write ProtocolTypeChange;
785	787		{Windows or Unix/Linux server? Has effect on line endings. Defaults to Unix. NOTE: untested}
786	788		property Servertype: TServerType read FServerType write ServerTypeChange;
787	789		{Initial message displayed on logon}
788	790		property WelcomeMessage: string read FWelcomeMessage;
789	791		{Connect/logon to server. Requires that all authentication, protocol and hostname/port options are correct
790	792		Returns descriptive result. You can then use the Connected property.}
791	793		function Connect: string;
792	794		{If connected, logoff from server}
793	795		procedure Disconnect;
794	796		{Send command to server and receive result}
795	797		function CommandResult(Command: string): string; //Send command and get results
796	798		constructor Create;
797	799		destructor Destroy; override;
798	800		end;
799	801
800	802		implementation
801	803
802	804
803	805		{ TelnetSSHClient }
804	806		procedure TTelnetSSHClient.SetPrivateKeyFile(value: string);
805	807		begin
806	808		Sock.SSL.PrivateKeyFile := value;
807	809		end;
808	810
809	811		function TTelnetSSHClient.GetPrivateKeyFile: string;
810	812		begin
811	813		Result := Sock.SSL.PrivateKeyFile;
812	814		end;
813	815
814	816		procedure TTelnetSSHClient.DetermineLineEnding;
815	817		begin
816	818		case FProtocolType of
817	819		SSH:
818	820		begin
819	821		if FServerType = Unix then
820	822		FServerLineEnding := #10 //Unix
821	823		else
822	824		FServerLineEnding := #13 + #10; //windows
823	825		end;
824	826		Telnet:
825	827		begin
826	828		if FServerType = Unix then
827	829		FServerLineEnding := #10 //Unix
828	830		else
829	831		FServerLineEnding := #13 + #10; //windows
830	832		end;
831	833		else
832	834		raise Exception.Create('Unknown protocol type');
833	835		end;
834	836		end;
835	837
836	838		procedure Ttelnetsshclient.DeterminePort;
837	839		begin
838	840		if FTargetPort = '' then
839	841		//Set default port for protocol
840	842		begin
841	843		case FProtocolType of
842	844		Telnet: FTargetPort := '23';
843	845		SSH: FTargetPort := '22';
844	846		else
845	847		raise Exception.Create('Unknown protocol type.');
846	848		end;
847	849
848	850		end;
849	851		end;
850	852
851	853		procedure TTelnetSSHClient.ServerTypeChange(Value: Tservertype);
852	854		begin
853	855		FServerType := Value;
854	856		DetermineLineEnding;
855	857		end;
856	858
857	859		function TTelnetSSHClient.Connect: string;
858	860		var
859	861		Received: string;
860	862		begin
861	863		result:='Unknown error while connecting';
862	864		FOutputPosition := 1; //First character in output stream
863	865		FWelcomeMessage := '';
864	866		//Just to make sure:
865	867		DetermineLineEnding;
866	868		DeterminePort;
867	869		if FTargetPort='0' then
868	870		begin
869	871		result:='Port may not be 0.';
870	872		exit; //jump out of function
871	873		end;
872	874		case FProtocolType of
873	875		Telnet:
874	876		begin
875	877		try
876	878		if Login then
877	879		begin
878	880		FConnected := True;
879	881		result:='Connected to telnet server.';
880	882		end
881	883		else
882	884		if Sock.LastError<>0 then raise Exception.Create(Sock.LastErrorDesc);
883	885		except
884	886		on E: Exception do
885	887		begin
886	888		FConnected:=false;
887	889		result:='Error connecting to telnet server '+FTargetHost+':'+
888	890		FTargetPort+' as user ' + FUserName +
889	891		'. Technical details: '+E.Message;
890	892		end;
891	893		end;
892	894		end;
893	895		SSH:
894	896		begin
895	897		{$IFNDEF HAS_SSH_SUPPORT}
896	898		raise Exception.Create(
897	899		'SSH support has not been compiled into the telnetsshclient library.');
898	900		{$ENDIF HAS_SSH_SUPPORT}
899	901		try
900	902		if (PrivateKeyFile <> '') and (FPassword <> '') then
901	903		Sock.SSL.KeyPassword:=FPassword;
902	904		if SSHLogin then
903	905		begin
904	906		FConnected := True;
905	907		result:='Connected to SSH server.';
906	908		end
907	909		else
908	910		begin
909	911		if Sock.LastError<>0 then raise Exception.Create(Sock.LastErrorDesc);
910	912		if Sock.SSL.LastError<0 then raise Exception.Create(Sock.SSL.LastErrorDesc);
911	913		end;
912	914		except
913	915		on E: Exception do
914	916		begin
915	917		FConnected:=false;
916	918		result:='Error connecting to SSH server '+FTargetHost+':'+
917	919		FTargetPort+' as user ' + FUserName +
918	920		'. Technical details: '+E.Message;
919	921		end;
920	922		end;
921	923		end;
922	924		else
923	925		raise Exception.Create('Unknown protocol type');
924	926		end;
925	927		if FConnected = True then
926	928		begin
927	929		FWelcomeMessage := ReceiveData;
928	930		if FProtocolType=Telnet then
929	931		begin
930	932		//Unfortunately, we'll have to extract login ourselves
931	933		//Hope it applies to all server types.
932	934		if (AnsiPos(AnsiLowerCase(FTelnetLoginPrompt),AnsiLowerCase(FWelcomeMessage))>0) then
933	935		begin
934	936		SendData(UserName);
935	937		end;
936	938		Received:=ReceiveData;
937	939		if (AnsiPos(AnsiLowerCase(FTelnetPasswordPrompt),AnsiLowerCase(Received))>0) then
938	940		begin
939	941		SendData(Password);
940	942		end;
941	943		//Receive additional welcome message/message of the day
942	944		FWelcomeMessage:=FWelcomeMessage+LineEnding+ReceiveData;
943	945		end;
944	946		end;
945	947		end;
946	948
947	949		procedure TTelnetSSHClient.Disconnect;
948	950		begin
949	951		Logout;
950	952		FConnected := False;
951	953		end;
952	954
953	955		function TTelnetSSHClient.ReceiveData: string;
954	956		begin
955	957		Result := '';
956	958		while Sock.CanRead(1000) or (Sock.WaitingData > 0) do
957	959		begin
958	960		Sock.RecvPacket(1000);
959	961		Result := Result + Copy(SessionLog, FOutputPosition,
960	962		Length(SessionLog));
961	963		FOutputPosition := Length(SessionLog) + 1;
962	964		end;
963	965		end;
964	966
965	967		procedure Ttelnetsshclient.SendData(Data: String);
966	968		begin
967	969		Data := Data + FServerLineEnding; //Could be linux, could be Windows
968	970		Send(Data);
969	971		end;
970	972
971	973		function TTelnetSSHClient.GetSessionLog: string;
972	974		begin
973	975		// Gets complete output up to now
974	976		Result := SessionLog;
975	977		end;
976	978
977	979		procedure TTelnetSSHClient.ProtocolTypeChange(Value: Tprotocoltype);
978	980		begin
979	981		FProtocolType := Value;
980	982		//Auto-determine port and line ending, if necessary
981	983		DeterminePort;
982	984		DetermineLineEnding;
983	985		end;
984	986
985	987		function TTelnetSSHClient.CommandResult(Command: string): string;
986	988		begin
987	989		Result := '';
988	990		if FConnected then
989	991		begin
990	992		SendData(Command);
991	993		Result := ReceiveData; //gets too much
992	994		end
993	995		else
994	996		begin
995	997		//raise exception
996	998		Result := '';
997	999		raise Exception.Create('Can only run command when connected');
998	1000		end;
999	1001		end;
1000	1002
1001	1003		constructor TTelnetSSHClient.Create;
1002	1004		begin
1003	1005		inherited;
1004	1006		FConnected := False;
1005	1007		FProtocolType := SSH; //Could be telnet, too
1006	1008		FServerType := Unix; //Probably a safe default.
1007	1009		FTelnetLoginPrompt := 'login:';
1008	1010		FTelnetPasswordPrompt := 'password:';
1009	1011		DetermineLineEnding;
1010	1012		DeterminePort;
1011	1013		end;
1012	1014
1013	1015		destructor TTelnetSSHClient.Destroy;
1014	1016		begin
1015	1017		if FConnected then
1016	1018		Disconnect;
1017	1019		inherited Destroy;
1018	1020		end;
1019	1021
1020	1022		end.
1021	1023		```
1022	1024
1023	1025		### Example client code
1024	1026
1025	1027		To use the TTelnetSSHClient class we just made, you can use this example application, sshtest.lpr. Note that it needs to be compiled by Lazarus as it needs the LCL components to work with Synapse:
1026	1028
1027	1029		``` pascal
1028	1030		program sshtest;
1029	1031
1030	1032		{Test program for telnetsshclient
1031	1033
1032	1034		Written by Reinier Olislagers 2011.
1033	1035		Modified for libssh2 by Alexey Suhinin 2012.
1034	1036
1035	1037		License of code:
1036	1038		* MIT
1037	1039		* LGPLv2 or later (with FreePascal static linking exception)
1038	1040		* GPLv2 or later
1039	1041		according to your choice.
1040	1042		Free use allowed but please don't sue or blame me.
1041	1043
1042	1044		Uses other libraries/components; different licenses may apply that also can influence the combined/compiled work.
1043	1045
1044	1046		Run: sshtest <serverIPorhostname> [PrivateKeyFile]
1045	1047		}
1046	1048		{$mode objfpc}{$H+}
1047	1049		{$APPTYPE CONSOLE}
1048	1050
1049	1051		uses
1050	1052		telnetsshclient;
1051	1053		var
1052	1054		comm: TTelnetSSHClient;
1053	1055		Command: string;
1054	1056		begin
1055	1057		writeln('Starting.');
1056	1058		comm:=TTelnetSSHClient.Create;
1057	1059		comm.HostName:= ParamStr(1); //First argument on command line
1058	1060		if comm.HostName='' then
1059	1061		begin
1060	1062		writeln('Please specify hostname on command line.');
1061	1063		halt(1);
1062	1064		end;
1063	1065
1064	1066		comm.PrivateKeyFile := ParamStr(2);
1065	1067
1066	1068		comm.TargetPort:='0'; //auto determine based on protocoltype
1067	1069		comm.UserName:='root'; //change to your situation
1068	1070		comm.Password:='password'; //change to your situation
1069	1071		comm.ProtocolType:=SSH; //Telnet or SSH
1070	1072		writeln(comm.Connect); //Show result of connection
1071	1073		if comm.Connected then
1072	1074		begin
1073	1075		writeln('Server: ' + comm.HostName + ':'+comm.TargetPort+', user: '+comm.UserName);
1074	1076		writeln('Welcome message:');
1075	1077		writeln(comm.WelcomeMessage);
1076	1078		Command:='ls -al';
1077	1079		writeln('*** Sending ' + Command);
1078	1080		writeln('* Begin result**');
1079	1081		writeln(comm.CommandResult(Command));
1080	1082		writeln('* End result**');
1081	1083		writeln('');
1082	1084		writeln('');
1083	1085		Command:='df -h';
1084	1086		writeln('*** Sending ' + Command);
1085	1087		writeln('* Begin result**');
1086	1088		writeln(comm.CommandResult(Command));
1087	1089		writeln('* End result**');
1088	1090		writeln('');
1089	1091		writeln('');
1090	1092		writeln('All output:');
1091	1093		writeln('* Begin result**');
1092	1094		writeln(comm.AllOutput);
1093	1095		writeln('* End result**');
1094	1096		comm.Disconnect;
1095	1097		end
1096	1098		else
1097	1099		begin
1098	1100		writeln('Connection to ' +
1099	1101		comm.HostName + ':' +
1100	1102		comm.TargetPort + ' failed.');
1101	1103		end;
1102	1104		comm.Free;
1103	1105		end.
1104	1106		```
1105	1107
1106	1108		## OAuth v1/Twitter/Plurk integration
1107	1109
1108	1110		An OAuth v1 library written in FPC that uses Synapse (and is ready for other network libraries like lNet) is available in [[fpctwit]]. FPCtwit also contains FPC Twitter and Plurk example client programs and a Lazarus Twitter client.
1109	1111
1110	1112		## Other Web and Networking Articles
1111	1113
1112	1114		- [[Portal:Web Development\|Web Development Portal]]
1113	1115		- [[Networking]]
1114	1116		- [[Networking libraries]] - comparison of various networking libraries
1115	1117		- [[Brook Framework]] - The perfect Free Pascal framework for your web applications. It's pure Pascal. You don't need to leave your preferred programming language.
1116	1118		- [[Sockets]] - TCP/IP Sockets components
1117	1119		- [[fcl-net]] - Networking library supplied with FPC
1118	1120		- [[lNet]] - Lightweight Networking Components
1119	1121		- [[XML Tutorial]] - XML is often utilized on network communications
1120	1122		- [[FPC and Apache Modules]]
1121	1123		- [[fcl-web]] - Also known as fpWeb, this is a library to develop web applications which can be deployed as cgi, fastcgi or apache modules.
1122	1124		- [[Secure programming\|Secure Programming]]
1123	1125		- [[Internet Tools]] - A wrapper around Synapse/wininet/Android's http components simplifying https and redirections, and a XPath/XQuery/CSS Selector/JSONiq engine to process the downloaded pages
1124	1126
1125	1127		## See also
1126	1128
1127	1129		- [[Download from SourceForge]] Example that uses Synapse to download from an HTTP server that redirects.
1128	1130		- [Visual Synapse](https://sourceforge.net/projects/visualsynapse/) component wrappers for many parts of Synapse serial and networking library (TvsComPort, TvsWebClient, TvsSniffer, TvsHTTPServer, TvsFTPServer, TvsAuthentication, TvsVisualDNS, TvsVisualHTTP, TvsVisualDUP, TvsVisualTCP, TvsVisualICMP, TvsSocksProxyInfo, TvsIPHelper, TvsSendMail and TvsSynPing).
1129	1131		- [TCP/IP component based on Synapse + a small demo application](https://forum.lazarus.freepascal.org/index.php/topic,48677.0.html)
1130	1132
1131	1133		## External links
1132	1134
1133	1135		- [Official site](http://www.ararat.cz/synapse/)
1134	1136		- [Official documentation](http://synapse.ararat.cz/doc/help/)
1135	1137		- [Download and Wiki](https://github.com/geby/synapse/wiki)
1136	1138
1137	1139		---
1138	1140		From the Free Pascal wiki, page "Synapse", as it stood on 2024-02-20 after a change by Dbannon, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history