Clever Internet Suite - Using certificates

	Using certificates

SSL / TLS support | Using certificates | FTP + SSL | FTP + SSH

Using certificates in Client Components

All client components from the Clever Internet Suite fully support the SSL / TLS encryption: HTTPS, FTPS, SMTP, POP3, IMAP and NNTP.

The following method is called when the server presents its certificate to the client and the client can decide whether to continue with the connection process. This sample uses FTP Client, but it is also applied to any Client components mentioned above.

// [Delphi]
procedure TMainForm.clFTPVerifyServer(Sender: TObject; ACertificate: TclCertificate;
const AStatusText: String; AStatusCode: Integer; var AVerified: Boolean);
var
newInstance: TclCertificate;
begin
if not AVerified and (MessageDlg(AStatusText + #13#10' Do you wish to proceed ?',
mtWarning, [mbYes, mbNo], 0) = mrYes) then
begin
newInstance := clCertificateStore1.Items.AddFrom(ACertificate);
clCertificateStore1.StoreName := 'CA';
clCertificateStore1.Install(newInstance);
AVerified := True;
end;
end;

Using certificates in Server Components

The following Server components support SSL / TLS encryption and allow specifying a certificate and its private key used for secured communication: HTTPS, FTPS, SMTP, POP3, IMAP and NNTP.

The method below is called when the needs a certificate for establishing connection. You can create your own self-signed certificate, as well as load any other certificate from a certificate store.

// [Delphi]
procedure TMainForm.clFtpServer1GetCertificate(Sender: TObject;
var ACertificate: TclCertificate; AExtraCerts: TclCertificateList; var Handled: Boolean);
begin
if clCertificateStore1.Items.Count = 0 then
begin
clCertificateStore1.ValidFrom := Now();
clCertificateStore1.ValidTo := Now() + 365;
ACertificate := clCertificateStore1.CreateSelfSigned('CN=CleverTester,O=CleverComponents,E=CleverTester@company.mail', 123);
clCertificateStore1.Items.Add(ACertificate);
end;
ACertificate := clCertificateStore1.Items[0];
Handled := True;
end;

Using certificates in Downloader / Uploader components

To set up SSL connection you have to assign the URL component property with HTTPS protocol and the engine adjusts to use this encrypted kind of connection automatically. See Downloader, Uploader, Multi Downloader and Multi Uploader

In case of the connection requires a certificate to authenticate a connected user you can choose one of two possible methods:

Allow users to setup a certificate in interactive GUI mode.
Setup all the certificate settings programmically.

The first method is the simplest to coding and enabled by default. To activate this mechanism you just need set the UseInternetErrorDialog component property to TRUE. After that any of authentication problems will be shown in the standard Internet Explorer error dialog box. Within this dialog you can setup both certificate itself and many authentication problems, such as reaction on if certificate date is invalid, certificate common name is invalid and many others. You can learn more about setup of the Microsoft Internet Explorer authentication modes from the MSDN Library and Microsoft online-resource- MSDN.

The second method requires some programming.

Setup the UseInternetErrorDialog component property to FALSE to deactivate the interactive GUI authentication mode.

Use the CertificateFlags component property with any set of values cfIgnoreCommonNameInvalid, cfIgnoreDateInvalid, cfIgnoreUnknownAuthority to resolve problems with invalid certificate common name, expired certificate date and unknown authority respectively.

To select client certificate in any of components from Clever Internet Suite you may use the OnGetCertificate component event. The handler procedure for this event is defined as follows:

// [Delphi]
TclGetCertificateEvent = procedure (Sender: TObject; var ACertificate: TclCertificate; AExtraCerts: TclCertificateList; var Handled: Boolean) of object;

The ACertificate is a wrapper class for the digital certificate object.

You can obtain the certificate by using the Certificate Store component:

// [Delphi]

procedure TForm1.clDownloaderGetCertificate (Sender: TObject;
var ACertificate: TclCertificate;
AExtraCerts: TclCertificateList; var Handled: Boolean);
begin
ACertificate := clCertificateStore.CertificateByIssuedTo ('John Doe');
Handled := True;
end;

Note! The OnGetCertificate event is not supported in Internet Explorer versions earlier than 5.5. The result is unpredictable if the client has more than one client certificate on the computer. On Internet Explorer 5.01 and earlier, it is not possible to select a client certificate programmatically (without using the user interface). So if you have IE version earlier than 5.5 you should use the UseInternetErrorDialog option to authenticate in GUI mode.

Using certificates in the S/MIME component

When the S/MIME Message component is about to Encrypt, Sign, Decrypt or Verify the current mail message, it requires client certificates. Please use the OnGetSigningCertificate component event to select a sender public certificate when verifying the message and own certificate with private key when signing the message; the OnGetEncryptionCertificate event to select a sender public certificate when encrypting and own private certificate when decrypting the message.

The following code displays how to use these events:

// [Delphi]
procedure TForm1.clSMimeMessageGetSigningCertificate (Sender: TObject;
var ACertificate: TclCertificate;
AExtraCerts: TclCertificateList; var Handled: Boolean);
begin
ACertificate := CertificateStore.CertificateByEmail('clevertester@company.mail');
Handled := True;
end;

// [Delphi]
procedure TForm1.clSMimeMessageGetEncryptionCertificate (Sender: TObject;
var ACertificate: TclCertificate;
AExtraCerts: TclCertificateList; var Handled: Boolean);
begin
ACertificate := CertificateStore.CertificateByEmail('clevertester@company.mail');
Handled := True;
end;

Using certificates in the SOAP component

Use the same OnGetCertificate event when the SOAP Message component is about to Sign, Verify, Encrypt or Decrypt the current SOAP message. The component provides the following two events: OnGetSigningCertificate and OnGetEncryptionCertificate. See the description above ("Using certificates in S/MIME component") for more information about these events.

The code below demonstrates how to load a certificate from the PFX file:

// [Delphi]
procedure TForm1.clSoapMessage1GetSigningCertificate(Sender: TObject;
AKeyInfo: TclXmlKeyInfo; var ACertificate: TclCertificate;
AExtraCerts: TclCertificateList; var Handled: Boolean);
begin
clCertificateStore.ImportFromPFX(edtCertFile.Text, edtCertPassword.Text);
ACertificate := clCertificateStore[0];
Handled := True;
end;

For the OnGetEncryptionCertificate event you must supply both the store name and store location where the certificate is installed.

// [Delphi]
procedure TForm1.clSoapMessage1GetEncryptionCertificate(Sender: TObject;
AKeyInfo: TclXmlKeyInfo; var ACertificate: TclCertificate;
AExtraCerts: TclCertificateList; var AStoreName: String;
var AStoreLocation: TclCertificateStoreLocation; var Handled: Boolean);
begin
clCertificateStore1.StoreLocation := slCurrentUser;
clCertificateStore1.Open('MY');
ACertificate := clCertificateStore1.CertificateByEmail(dlg.edtEmail.Text);
AStoreName := 'MY';
AStoreLocation := slCurrentUser;
Handled := True;
end;

The AKeyInfo parameter provides an additional information about required certificate. You can use it for locating the required certificate within the certificate store.