tSFTPClient

O SFTP, ou Secure File Transfer Protocol, é um protocolo seguro para

transferência de arquivos diversos, confidenciais ou não, entre
computadores, servidores e dispositivos de armazenamento em
nuvem, que faz uso do protocolo SSH (Secure Shell) para criptografar
todos os dados transferidos. Isso torna o SFTP uma opção muito mais
segura do que outros protocolos de transferência de arquivos como
FTP ou HTTP.
É possível utilizar a Classe tSFTPClient, disponível na linguagem TLPP,
para implementar funcionalidades equivalentes a Classe tFTPClient,
disponível na linguagem em ADVPL, de forma mais segura e eficiente.
Certificados de Login
Para gerar certificados de Login, é importante atentar-se a estes
procedimentos:
Geração de Certificados de Login para Classe tSFTPClient
Configuração
No arquivo de configurção INI do Application Server ([Link]),
segue um exemplo de como configurar algumas chaves utilizadas
especificamente pela Classe TSFTPClient:
[SFTP]
privatekey = D:\Keys\SFTPDEV_PREFERED\withpass\id_rsa
publickey = D:\Keys\SFTPDEV_PREFERED\withpass\id_rsa.pub
certpassword = m1nh4S3nH4fl3!SXHL3SSD
ShellExec =1
As descrições de cada chaves da sessão SFTP:
 PRIVATEKEY é utilizada para configurar o caminho do arquivo
referente a chave privada localizado no servidor.
 PUBLICKEY é utilizada para configurar o caminho do arquivo
referente a chave pública localizado no servidor.
 CERTPASSWORD é a senha da chave pública. Se não existir,
basta omiti-la.
 SHELLEXEC Permite habilitar o recurso de envio de comandos
diretamente para o prompt de comandos do servidor SFTP
remoto. Valores aceitos: 0-Inativo (Padrão) / 1-Ativo.
Autenticação
O SFTP suporta dois métodos de autenticação:
Autenticação via senha: A autenticação via senha é o método mais
comum de autenticação SFTP. Requer que o usuário forneça um nome
de usuário e uma senha para acessar o servidor SFTP.
Autenticação via chave pública: A autenticação via chave pública é
uma maneira mais segura de autenticar em um servidor SFTP que
requer a criação de uma chave pública e uma chave privada. A chave
pública é enviada ao servidor SFTP e a chave privada é mantida pelo
usuário.
A autenticação via chave pública é mais segura do que a
autenticação via senha pois não requer o envio de senha para o
servidor SFTP, tornando mais difícil para um invasor roubar a senha.
Vantagens do SFTP
Segurança: Usa criptografia para proteger todos os dados
transferidos.
Confiabilidade: Protocolo confiável que fornece transferências seguras
e consistentes de arquivos.
Flexibilidade: Pode ser usado para transferir arquivos entre diferentes
sistemas operacionais e dispositivos.
Desvantagens do SFTP
Velocidade: Pode ser um pouco mais lento do que outros protocolos
de transferência de arquivos como o FTP.
Complexidade: Pode ser um pouco mais complexo de configurar e
usar do que outros protocolos de transferência de arquivos. Requer o
uso do servidor OpenSSH para prover o acesso SFTP através da
camada SSH.
Métodos da Classe SFTP
 Geração de Certificados de Login para Classe
tSFTPClient
 tSFTPClient:Connect
 tSFTPClient:ConnectPubKey
 tSFTPClient:ConnectPubKeyEx
 tSFTPClient:Directory
 tSFTPClient:Disconnect
 tSFTPClient:GetLastResponse
 tSFTPClient:GetMLCount
 tSFTPClient:GetMLLine
  tSFTPClient:MakeDir
 tSFTPClient:MakeFile
 tSFTPClient:Move
 tSFTPClient:New
 tSFTPClient:NoOp
 tSFTPClient:ReceiveFile
 tSFTPClient:RemoveDirectory
 tSFTPClient:RemoveFile
 tSFTPClient:SendFile
 tSFTPClient:ShellExec

Geração de Certificados de Login para Classe tSFTPClient

Pré-Requisitos: Putty, OpenSSH, OpenSSL e Windows Subsystem for

Linux (WSL)
Observação Importante: Não se deve utilizar a ferramenta
PUTTYGEN para geração dos certificados de LOGIN.
Recomenda-se utilizar apenas a ferramenta ssh-keygen apenas para este
processo de geração e a openssl para eventual conversão de formatos de
chaves, caso for necessário.
Atualmente, existem vários tipos de certificados de Login que podem ser
utilizados no SFTP. São elas:
 RSA Key (Padrão)
 DSA Key, ECDSA Key (Elliptic Curve)
 Ed25519 Key (EdDSA Curve).
Na plataforma, recomenda-se utilizar o padrão RSA Key.
Para gerarmos um par de chaves publica e privada compatível com o
subsistema de SFTP do Protheus, devemos realizar os seguintes
procedimentos:
ssh-keygen -t rsa -m PEM -f id_rsa
Este comando, gerará um par de certificados público e privado
normalmente chamada de (id_rsa.pub e id_rsa) respectivamente. Em
ambiente Linux/WSL, favor verificar se os formatos de chaves, com o auxílio
do comando file id_rsa*, estão conforme a tabela abaixo:
 Arquivo Tipo da chave
Gerado

id_rsa PEM RSA private key

id_rsa.pub OpenSSH RSA public

key

Feito este procedimento, todo o conteúdo do arquivo id_rsa.pub deverá ser

acrescentado dentro do arquivo ~/.ssh/authorized_keys no usuário do
servidor SFTP em que terá acesso.
No arquivo [Link], devemos configurar, conforme o exemplo
abaixo, a seção SFTP para que as funções de download e upload funcionem
corretamente:
[SFTP]
privatekey = D:/Keys/id_rsa
publickey = D:/Keys/id_rsa.pub
certpassword = teste12345
Note que o certificado, neste exemplo, foi gerado com uma senha
"teste12345". Caso o certificado tenha sido gerado sem nenhuma senha,
devemos omitir a chave certpassword nesta seção SFTP.
Observações importantes
Nota: A ferramenta ssh-keygen suporta os seguintes modos de
geração do certificados:
 "RFC4716" (RFC 4716/SSH2 pública ou chave privada)
 "PKCS8" (PKCS8 pública ou chave privada)
 "PEM" (PEM chave pública)
IMPORTANTE: Caso for observado que o certificado de login gerado
não esteja no formato PEM, é necessário converter o certificado (no
arquivo id_rsa) Os formatos: "RFC4716" (RFC 4716/SSH2 pública ou
chave privada) e "PKCS8" (PKCS8 pública ou chave privada)
suportados pela a ferramenta ssh-keygen, não estao homologados
com subsistema de SFTP do Application Server podendo ocorrer
erros ao realizar o Login caso forem utilizados.
Para converter, para o formato compatível, é necessário realizar o seguinte
procedimento na linha de comando (Requer OpenSSL):
openssl rsa -in id_rsa -outform pem > id_rsa.pem
Caso necessitar gerar um certificado no formato Putty, para algum outro fim
sem ser para uso no Protheus, é possível converter o certificado para o
formato PPK utilizando o seguinte comando:
puttygen id_rsa -o [Link] -O private
Lembrando novamente que este certificado no formato Putty (PPK) não é
suportado pelo o Protheus não devendo ser utilizado.
Feito estes procedimentos, é interessante conferir novamente se o formato
dos certificados estão de acordo com o reportado ao executar o comando no
WSL ou Linux (considerando que os arquivos de certificados estão na
mesma pasta):
file *
Ao executar o comando o resultado deverá ser:

Arquivo Tipo da chave

Gerado

id_rsa PEM RSA private key

id_rsa.pem PEM RSA private key

id_rsa.pub OpenSSH RSA public key

minhachave.p PuTTY Private Key File, version 3,

pk algorithm ssh-rsa

Nota: O formato da chave privada (id_rsa) nunca deverá ser

OpenSSH RSA private key uma vez que este não é suportado.
IMPORTANTE: Nunca se deve utilizar certificados no formato PUTTY
(PPK) para a plataforma Protheus pois não são compatíveis.

tSFTPClient:ConnectPubKey
Estabelece uma conexão com um servidor de SFTP ( SSH File Transfer
Protocol ) utilizado o modo de autenticação por usuário com a chave publica
e senha da chave publica.
Pré-requisito
Para que a conexão com o servidor SFTP seja bem sucedida, é preciso
configurar as chaves pública e privada e a respectiva senha da chave
pública na seção [SFTP] do arquivo de configuração do AppServer. Exemplo
de como configurar:
[SFTP]
privatekey = D:\Keys\SFTPDEV_PREFERED\withpass\id_rsa
publickey = D:\Keys\SFTPDEV_PREFERED\withpass\id_rsa.pub
certpassword = m1nh4S3nH4fl3!SXHL3SSD
ShellExec =1
Sintaxe
TSFTPClient():ConnectPubKey( < cServer >, < cPort >, < cUser > )
Parâmetros
Os parâmetros que esta função recebe são descritos abaixo:

Nome Tipo Descrição Obrigató Referên

rio cia

cServer caracte Endereço do X

re servidor SFTP a ser
conectado

cPort caracte Número da porta do X

re servidor

cUser caracte Login do usuário X

re

cUserPasswo caracte Senha do usuário X

rd re

Retorno
Conforme a Tabela abaixo esta função retonará o valor numérico. Além
disso, o [Link] conterão informações importantes adicionais caso for
detectados erros.

Retor Tipo Descrição

no

nRet numéric Status de conexão ao servidor

o SFTP

Exemplo
user Function sftp_open_close_connection_ex2()

local nRet1, nRet2

local oSftp1 := tSFTPClient():new()

nRet1 :=
oSftp1:ConnectPubKey("[Link]","2222","josevitor")
 if (nRet1 <> 0)
conOut("Falha em conectar ao servidor SFTP")
return .F.
endif

nRet2 := oSftp1:Disconnect()
if (nRet2 <> 0)
conOut("Falha em desconectar ao servidor SFTP")
return .F.
endif

Return .T.
Observações
Note que neste método de conexão, temos dois tipos de senhas que são a
do usuário e a da chave pública.
Segue a lista de códigos de status de retorno indicando sucesso ou falha de
conexão:

Códig Símbolo Descrição

o

0 SFTP_OK Sucesso de conexão ao

servidor SFTP

-1 SFTP_HOST_NOT_FOUND Servidor remoto não

encontrado

-2 SFTP_SOCKET_FAIL Falha no socket da

conexão

-3 SFTP_CONNECTION_FAIL Falha ao conectar no

servidor remoto

-4 SFTP_SESSION_INIT_FAIL Falha ao inicializar o

socket

-5 SFTP_HANDSHAKE_FAIL Falha no HandShake da

camada SSH
 Códig Símbolo Descrição
o

-6 SFTP_SFTP_INIT_FAIL Falha ao inicializar o

subsistema de SFTP

-28 SFTP_KNOWNHOSTS_READ_FAIL Falha ao realizar leitura

do host

-30 SFTP_KNOWNHOSTS_FINGERPRINT_ Falha ao realizar leitura

FAIL da assinatura

-31 SFTP_KNOWNHOSTS_MISMATCH Assinatura não-conforme

no arquivo de
KNOWNHOSTS

-32 SFTP_KNOWNHOSTS_NOTFOUND Assinatura não-

encontrada no arquivo de
KNOWNHOSTS

-33 SFTP_KNOWNHOSTS_CHECK_FAILU Falha ao verificar o

RE arquivo de
KNOWNHOSTS

tSFTPClient:ConnectPubKeyEx

Estabelece uma conexão com um servidor de SFTP ( SSH File Transfer

Protocol ) utilizando o modo de autenticação por login e senha de
usuário e ainda com um chave pública e senha desta chave
registradas no INI do Application Server.
Este método se difere do ConnectPubKey pois realiza a autenticação
em duas etapas (Usuário + Senha) e (Chaves Pública e Privada +
Senha da Chave). É um caso especial onde o servidor SFTP encontra-
se configurado para realizar autenticação múltipla por mais de um
fator de autenticação.
Pré-requisito
Para que a conexão com o servidor SFTP seja bem sucedida é preciso
configurar as chaves pública e privada e a respectiva senha da chave
pública na seção [SFTP] do arquivo de configuração do Application
Server. Exemplo de como configurar:
[SFTP]
privatekey = D:\Keys\SFTPDEV_PREFERED\withpass\id_rsa
publickey = D:\Keys\SFTPDEV_PREFERED\withpass\id_rsa.pub
certpassword = m1nh4S3nH4fl3!SXHL3SSD
ShellExec =1
Sintaxe
TSFTPClient():ConnectPubKeyEx( < cServer >, < cPort >, < cUser >,
< cUserPassword > )
Parâmetros
Os parâmetros que esta função recebe são descritos abaixo:

Nome Tipo Descrição Obrigató Referên

rio cia

cServer caracte Endereço do X

re servidor SFTP
a ser
conectado

cPort caracte Número da X

re porta do
servidor SFTP

cUser caracte Login do X

re usuário

cUserPasswo caracte Senha do X

rd re usuário

Retorno
Conforme a tabela abaixo, esta função retonará um valor numérico.
Além disso, no arquivo [Link] serão registradas informações
adicionais importantes caso forem detectados erros.
 Retor Tipo Descrição
no

nRet numéric Status de conexão ao servidor

o SFTP.

Exemplo
user function sftp_open_close_connection_ex1()

local nRet1, nRet2

Local oSftp1 := tSFTPClient():new()

nRet1 :=
oSftp1:ConnectPubKeyEx("[Link]","2222","josevitor",
"Fs74!@bz*@54/")
if (nRet1 <> 0)
conOut("Falha em conectar ao servidor SFTP")
return .F.
endif

nRet2 := oSftp1:Disconnect()
if (nRet2 <> 0)
conOut("Falha em desconectar ao servidor SFTP")
return .F.
endif

Return .T.
Observações
Note que neste método de conexão, temos dois tipos de senhas que
são a do usuário e a da chave pública, no entanto a senha da chave
pública é configurada no arquivo de configuração do Application
Server.
Segue a lista de códigos de status de retorno indicando sucesso ou
falha de conexão:
Códig Símbolo Descrição
o

0 SFTP_OK Sucesso de
conexão ao
servidor SFTP

-1 SFTP_HOST_NOT_FOUND Servidor remoto

não encontrado

-2 SFTP_SOCKET_FAIL Falha no socket da

conexão

-3 SFTP_CONNECTION_FAIL Falha ao conectar

no servidor remoto

-4 SFTP_SESSION_INIT_FAIL Falha ao inicializar

o socket

-5 SFTP_HANDSHAKE_FAIL Falha no
HandShake da
camada SSH

-6 SFTP_SFTP_INIT_FAIL Falha ao inicializar

o subsistema de
SFTP

-28 SFTP_KNOWNHOSTS_READ_FAIL Falha ao realizar

leitura do host

-30 SFTP_KNOWNHOSTS_FINGERPRINT_ Falha ao realizar

FAIL leitura da
assinatura

-31 SFTP_KNOWNHOSTS_MISMATCH Assinatura não-

conforme no
arquivo de
KNOWNHOSTS

-32 SFTP_KNOWNHOSTS_NOTFOUND Assinatura não-

encontrada no
arquivo de
Códig Símbolo Descrição
o

KNOWNHOSTS

-33 SFTP_KNOWNHOSTS_CHECK_FAILU Falha ao verificar o

RE arquivo de
KNOWNHOSTS