Liga-se a um servidor via FTP através do seu editor de código, introduz o host, o login e a password, e recebe uma linha vermelha como resposta: SSL/TLS required on the data channel. Parece-lhe familiar? Este erro ocorre quando o servidor exige uma ligação encriptada, mas o cliente tenta ligar-se por FTP simples. Isto acontece com especial frequência em fornecedores de alojamento com certificados autoassinados.

Anteriormente, este problema era resolvido no Atom através do plugin Remote FTP. O Atom morreu em dezembro de 2022, mas o erro não desapareceu. Continua vivo no VS Code, no FileZilla, no Pulsar e em qualquer cliente FTP que se ligue a um servidor com um certificado SSL autoassinado.

Neste artigo, três formas funcionais de contornar o SSL/TLS required on the data channel: para Atom/Pulsar através do .ftpconfig, para VS Code através da extensão SFTP e para clientes GUI como o FileZilla. Mais um aviso importante: quando rejectUnauthorized: false é uma solução de recurso aceitável e quando é um buraco de segurança.

💡 Resumo rápido:

• Origem do erro: o servidor exige TLS, o cliente envia FTP simples, a ligação cai na fase do canal de dados.
• .ftpconfig com rejectUnauthorized: false e secure: true é a solução para o Atom e o seu fork Pulsar que funciona com o plugin Remote FTP.
• No VS Code, a extensão SFTP de liximomo com o parâmetro secure: true resolve o mesmo problema ao nível da configuração do sftp.json.
• No FileZilla e noutros clientes GUI, basta mudar o protocolo de FTP para FTPS (TLS Explícito) e aceitar o certificado manualmente.
• Segurança: rejectUnauthorized: false desativa a verificação do certificado e é aceitável apenas para servidores de desenvolvimento e ambientes de teste, nunca em produção.

De onde vem o erro SSL/TLS required on the data channel

O protocolo FTP funciona através de dois canais: canal de controlo (comandos) e canal de dados (transferência efetiva de ficheiros). Quando o servidor está configurado para FTPS (FTP sobre TLS), encripta ambos. Um cliente que tenta ligar-se por FTP normal passa a autenticação com sucesso no canal de controlo, mas ao tentar abrir o canal de dados, o servidor responde: 550 SSL/TLS required on the data channel.

A razão técnica reside na implementação do TLS do lado do Node.js (sobre o qual tanto o Remote FTP para Atom como a extensão SFTP do VS Code são construídos). O Node.js valida certificados SSL por predefinição. Um certificado autoassinado falha esta validação e a ligação cai. A solução: ou dizer explicitamente ao cliente para não verificar o certificado (rejectUnauthorized: false), ou mudar para FTPS explícito com aceitação manual do certificado.

Solução 1:.ftpconfig adequado para Atom e Pulsar

O Atom foi oficialmente descontinuado em dezembro de 2022, mas o seu fork Pulsar (anteriormente Atom) é totalmente compatível com os pacotes do Atom, incluindo o Remote FTP. A solução é especificar as secureOptions corretas no .ftpconfig.

Crie (ou edite) o ficheiro .ftpconfig na raiz do projeto:

1
{
2
    "protocol": "ftp",
3
    "host": "your.server.com",
4
    "port": 21,
5
    "user": "login",
6
    "pass": "password",
7
    "promptForPass": false,
8
    "remote": "/",
9
    "secure": true,
10
    "secureOptions": {
11
        "rejectUnauthorized": false
12
    },
13
    "connTimeout": 10000,
14
    "keepalive": 10000
15
}

Parâmetros-chave:

• secure: true ativa o TLS para ambos os canais, de controlo e de dados;
• rejectUnauthorized: false desativa a verificação do certificado (o Node.js deixa de exigir um certificado válido do servidor);
• port: 21 é a porta padrão para FTP; para FTPS via TLS implícito, use a porta 990 e protocol: "ftps".

Depois de guardar o .ftpconfig, volte a ligar-se ao servidor e o erro SSL/TLS required on the data channel desaparecerá.

Solução 2: configurar a extensão SFTP no VS Code

A extensão mais popular para FTP/SFTP no VS Code é o SFTP de liximomo (mais de 1,3 milhões de instalações). O erro 550 SSL/TLS required on the control channel é discutido na issue #872.

Após instalar a extensão, execute Ctrl+Shift+P → SFTP: Config e o ficheiro sftp.json será aberto. Configure-o da seguinte forma:

1
{
2
    "name": "My server",
3
    "host": "your.server.com",
4
    "protocol": "ftp",
5
    "port": 21,
6
    "secure": true,
7
    "username": "login",
8
    "password": "password",
9
    "remotePath": "/",
10
    "uploadOnSave": true
11
}

O parâmetro secure: true é um equivalente direto do rejectUnauthorized: false do .ftpconfig. Diz à extensão para usar FTPS e não derrubar a ligação ao encontrar um certificado autoassinado.

Se o servidor usar FTPS implícito (porta 990), altere protocol para ftps e port para 990. Guarde o sftp.json, execute SFTP: Download Project e a extensão ligar-se-á e descarregará o conteúdo de remotePath.

Solução 3: FileZilla e outros clientes GUI

Nos clientes GUI, o problema resolve-se de forma ainda mais simples ao nível da interface. No FileZilla:

• Abra o Gestor de Sites (Ctrl+S).
• Selecione a ligação e, no campo Protocolo, mude de FTP para FTP over TLS (explicit).
• Na primeira ligação, o FileZilla mostrará um diálogo com a impressão digital do certificado; clique em Confiar neste certificado e marque "Confiar sempre".

O mesmo princípio funciona no WinSCP, Cyberduck e em qualquer cliente FTP moderno: especifique explicitamente o protocolo FTPS e aceite o certificado manualmente. Sem ficheiros de configuração, apenas a interface.

Quando NÃO deve desativar a verificação do certificado

rejectUnauthorized: false é um enfraquecimento deliberado da segurança. Está a dizer ao cliente: «aceita QUALQUER certificado, mesmo que seja falsificado». Isto é aceitável em três casos:

• Um servidor de desenvolvimento local ou ambiente de staging não acessível a partir da internet.
• O seu próprio VPS, onde sabe exatamente de onde veio o certificado.
• Um ambiente de teste atrás de uma VPN corporativa.

Num servidor de produção com um certificado autoassinado, é melhor gastar 15 minutos a configurar o Let's Encrypt, um certificado SSL gratuito que todos os clientes reconhecem sem rejectUnauthorized: false.

Veja este pequeno tutorial sobre ligação SFTP no VS Code, que cobre todos os passos desde a instalação da extensão até à primeira ligação ao servidor:

⁉️🤔 Perguntas frequentes

O erro mantém-se após secure: true; o que mais devo verificar?

Em primeiro lugar, verifique a porta. O FTPS explícito funciona na porta 21, o implícito na 990. Se o administrador do servidor exigir FTPS implícito, mas especificou protocol: "ftp" com port: 21, a ligação não será estabelecida, por mais que altere as secureOptions. Consulte o seu painel de alojamento ou pergunte ao administrador qual o modo FTPS que o servidor utiliza.

Posso usar SFTP em vez de FTPS?

Sim, e esta é a opção preferencial. O SFTP (SSH File Transfer Protocol) funciona sobre SSH, não sobre FTP, pelo que os problemas de certificado SSL simplesmente não existem para ele. Se o servidor fornecer acesso SSH, use SFTP em vez de FTPS. No mesmo .ftpconfig, basta alterar protocol para sftp e port para 22.

O Atom foi descontinuado; o Remote FTP ainda funciona?

O pacote Remote FTP está disponível no repositório do Atom, mas o editor em si não é atualizado desde dezembro de 2022 e contém vulnerabilidades conhecidas. O GitHub chegou mesmo a revogar os certificados de assinatura de código do Atom em janeiro de 2023. Se o Atom ainda arrancar na sua máquina, migre para o fork Pulsar, que utiliza os mesmos pacotes e configurações sem alterações.

E quanto ao VS Code Remote SSH?

O Remote SSH é uma excelente alternativa às ligações FTP se o servidor correr Linux e tiver acesso SSH. Trabalha com os ficheiros diretamente, sem sincronizações e chatices com certificados. Mas para alojamento partilhado onde o SSH está fechado e o acesso é apenas via FTP, as soluções deste artigo continuam a ser relevantes.

O erro SSL/TLS required on the control channel (não data channel): é a mesma coisa?

Sim, a única diferença é em que canal a ligação caiu. O canal de controlo trata dos comandos (autenticação, navegação), o canal de dados trata da transferência de ficheiros. O servidor pode exigir TLS em qualquer um deles. A solução é idêntica: secure: true + rejectUnauthorized: false na configuração.

O erro persiste: lista de verificação final

Percorra os itens; um deles resolverá o problema:

• Protocolo: está secure: true definido na configuração (.ftpconfig ou sftp.json)?
• Porta: FTPS explícito = 21, implícito = 990, SFTP = 22. Verifique em relação às definições do servidor.
• rejectUnauthorized: um certificado autoassinado NÃO passará na validação do Node.js sem esta opção.
• Cliente GUI: mudou o Gestor de Sites para FTP over TLS (explicit) e aceitou manualmente o certificado?
• SFTP em vez de FTPS: se tiver acesso SSH, esqueça o FTP e mude para SFTP.

Se já tentou tudo e o erro persiste, o servidor está muito provavelmente configurado para FTPS implícito (porta 990), enquanto o cliente se liga à porta 21. Verifique com o seu fornecedor de alojamento o modo e a porta necessários.

Este erro não é um bug do editor, mas uma característica do handshake TLS com um certificado autoassinado. Após a configuração adequada, desaparece em qualquer cliente: seja no Atom de 2018, no Pulsar de 2026 ou no VS Code.