Como Instalar um Certificado SSL no Unifi Cloud Key

Este tutorial fornece instruções passo a passo sobre como instalar um certificado SSL no UniFi Cloud Key. O Cloud Key executa a aplicação UniFi Network sobre um Java keystore, então a instalação é feita via SSH: você monta um pacote PKCS#12 a partir do seu certificado, chave privada e cadeia CA, depois o importa para o keystore do Cloud Key com o utilitário Java keytool e reinicia o serviço UniFi.

Gerar um código CSR no UniFi Cloud Key

O Certificate Signing Request, ou CSR, é um bloco de texto codificado que contém seus dados de contato, como seu domínio e organização. Todo solicitante deve gerar um CSR e enviá-lo à Autoridade Certificadora (CA) para validação antes que um certificado possa ser emitido. Para um Cloud Key, o common name no CSR deve ser o hostname que você usa para acessar o controlador, por exemplo unifi.seusite.com.

Você tem duas opções:

• Use nosso Gerador de CSR para criar o CSR automaticamente.
• Siga nosso tutorial passo a passo sobre como gerar um CSR no UniFi Cloud Key.

Você pode abrir seu arquivo CSR com qualquer editor de texto, como o Bloco de Notas, e colá-lo durante o processo de pedido do certificado junto ao seu fornecedor SSL. Mantenha a chave privada correspondente em segurança: você precisará dela novamente no Passo 3 para montar o pacote PKCS#12. Assim que a CA validar sua solicitação e enviar os arquivos SSL por e-mail, prossiga com a instalação abaixo.

Instalar um certificado SSL no UniFi Cloud Key

O Cloud Key serve HTTPS a partir de um Java keystore em /usr/lib/unifi/data/keystore. Por padrão, esse keystore contém um certificado autoassinado sob o alias unifi, protegido pela senha aircontrolenterprise. Para instalar seu próprio certificado, você substitui essa entrada: agrupa seus arquivos em um pacote PKCS#12, importa-o para o mesmo alias e depois reinicia o serviço UniFi. Você trabalhará via SSH, então conecte-se primeiro ao Cloud Key (o usuário SSH padrão é root na Gen1, ou a conta de administrador que você definiu durante a adoção na Gen2).

Passo 1: Prepare seus arquivos SSL

Verifique sua caixa de entrada e baixe o arquivo ZIP contendo seu certificado. Extraia-o. Dependendo do seu provedor SSL, você deve ter alguns ou todos estes arquivos:

• O certificado SSL primário (seu certificado de servidor).
• O certificado SSL intermediário.
• O certificado SSL raiz.
• O CA bundle, um único arquivo que já contém os certificados raiz e intermediário.

Você também precisa da chave privada que gerou junto com o CSR. Se você usou nosso Gerador de CSR, a chave foi disponibilizada para download naquele momento.

Passo 2: Copie seus arquivos SSL para o Cloud Key

Envie seus arquivos para o Cloud Key via SCP ou SFTP e coloque-os em /etc/ssl/private/. Use estes nomes para que correspondam aos comandos nos próximos passos:

• Certificado primário como /etc/ssl/private/cloudkey.crt
• Chave privada como /etc/ssl/private/cloudkey.key
• CA bundle (raiz e intermediário) como /etc/ssl/private/yourcaname.crt

Nota: cada arquivo PEM deve terminar com uma quebra de linha após a linha final. A última linha do certificado é exatamente cinco hifens, as palavras END CERTIFICATE, e mais cinco hifens (—–END CERTIFICATE—–); certifique-se de que há uma quebra de linha após isso. A ausência dessa quebra de linha final é uma causa frequente de erros de importação.

Passo 3: Agrupe seu certificado em um arquivo PKCS#12

Combine sua chave privada, certificado primário e CA bundle em um único arquivo PKCS#12. O alias deve ser unifi, pois é esse o alias que o keystore do UniFi espera. Substitua enteryourpassword por uma senha de sua escolha e lembre-se dela: você passará o mesmo valor ao keytool no Passo 4 como a senha de origem.

openssl pkcs12 -export -in /etc/ssl/private/cloudkey.crt -inkey /etc/ssl/private/cloudkey.key -out /etc/ssl/private/cloudkey.p12 -name unifi -CAfile /etc/ssl/private/yourcaname.crt -caname root -password pass:enteryourpassword

Isso gera /etc/ssl/private/cloudkey.p12, contendo a chave, seu certificado e a cadeia, tudo sob o alias unifi.

Passo 4: Importe o arquivo PKCS#12 para o keystore do Cloud Key

Importe o arquivo PKCS#12 para o keystore existente em /usr/lib/unifi/data/keystore. O keystore de destino já usa a senha aircontrolenterprise, então as senhas do store e da chave de destino devem permanecer como aircontrolenterprise. A senha de origem é a que você definiu no arquivo PKCS#12 no Passo 3.

keytool -importkeystore -deststorepass aircontrolenterprise -destkeypass aircontrolenterprise -destkeystore /usr/lib/unifi/data/keystore -srckeystore /etc/ssl/private/cloudkey.p12 -srcstoretype PKCS12 -srcstorepass enteryourpassword -alias unifi

Se o keytool informar que o alias unifi já existe, ele está se referindo à entrada autoassinada padrão. Confirme a substituição quando solicitado, ou exclua a entrada antiga primeiro com o comando abaixo e depois execute novamente a importação:

keytool -delete -alias unifi -keystore /usr/lib/unifi/data/keystore -storepass aircontrolenterprise

Importante: não altere a senha do keystore para um valor próprio. O serviço UniFi está codificado para abrir o keystore com aircontrolenterprise; se você a alterar, o controlador não conseguirá ler o certificado e o HTTPS falhará.

Passo 5: Defina as permissões e remova os arquivos temporários

Restrinja a propriedade e as permissões dos arquivos em /etc/ssl/private/ para que a chave privada não seja legível por todos, e depois exclua os arquivos intermediários que não são mais necessários. Execute estes comandos um de cada vez:

chown root:ssl-cert /etc/ssl/private/*
chmod 640 /etc/ssl/private/*
rm /etc/ssl/private/cloudkey.p12

O certificado agora reside dentro do keystore, então o arquivo PKCS#12 não é mais necessário. Se você também enviou o CSR ou o arquivo CA apenas para este processo, pode removê-los também:

rm /etc/ssl/private/cloudkey.csr
rm /etc/ssl/private/yourcaname.crt

Dica: antes de reiniciar, você pode fazer backup do keystore para poder reverter se necessário. A partir de dentro de /usr/lib/unifi/data/, arquive-o com tar -cvf keystore-backup.tar keystore.

Passo 6: Combine o hostname do controlador com o seu certificado

Para que os navegadores confiem no certificado sem um aviso de incompatibilidade de nome, defina o hostname ou IP do controlador com o nome constante no seu certificado. Na aplicação UniFi Network, vá para Settings > System (versões mais antigas: Settings > Controller) e defina o Controller Hostname/IP para o common name do seu certificado, por exemplo unifi.seusite.com. Certifique-se de que esse hostname resolve para o Cloud Key no seu DNS.

Passo 7: Reinicie o serviço UniFi

O novo certificado só é lido quando o serviço UniFi é iniciado, então reinicie-o para carregar o seu certificado:

service unifi restart

Em firmwares mais recentes do Cloud Key que usam systemd, o comando equivalente é:

systemctl restart unifi

Aguarde um minuto para o serviço voltar a funcionar e, em seguida, recarregue o controlador no seu navegador. Parabéns, seu certificado SSL agora está instalado no seu UniFi Cloud Key.

Teste sua instalação SSL

Depois de instalar o certificado, verifique sua configuração em busca de erros ou vulnerabilidades, como um certificado intermediário ausente ou uma cadeia não confiável. Use nosso SSL Checker para uma verificação e relatório instantâneos. Como o controlador UniFi geralmente escuta na porta 8443, aponte o verificador para seu endereço completo, por exemplo unifi.seusite.com:8443. Você também pode confirmar o resultado pela linha de comando:

echo | openssl s_client -connect unifi.yoursite.com:8443 -servername unifi.yoursite.com 2>/dev/null | openssl x509 -noout -issuer -dates

Isso exibe o emissor do certificado e as datas de validade, para que você possa confirmar que o Cloud Key está servindo o seu certificado e não o antigo autoassinado.

Perguntas Frequentes