Integração de smart cards (PC/SC, CCID, OpenSC) no IPFire 2.19

Introdução

Este artigo é a continuação do nosso trabalho anterior sobre o firewall IPFire. Aqui mostramos como integrar suporte a tokens de hardware (por exemplo, smart cards) e seus leitores compatíveis com CCID ao projeto IPFire. As ferramentas compiladas e empacotadas com sucesso para a versão IPFire 2.19 são:

• pcsc-lite (PC/SC Smart Card Daemon)
• CCID (Chip/Smart Card Interface Devices) — drivers livres
• OpenSC (bibliotecas e utilitários open source para smart cards)

Resumo técnico rápido: pcsc-lite fornece o daemon pcscd que expõe a API PC/SC no Linux. CCID contém drivers para leitores compatíveis CCID. OpenSC oferece suporte ao PKCS#11 e ao layout de ficheiros PKCS#15, permitindo uso de smart cards para autenticação, encriptação e geração de chaves.

Casos de uso comuns para tokens de hardware:

• Autenticação em web sites e aplicações
• Login em estações de trabalho
• Encriptação de ficheiros
• VPNs (OpenVPN, L2TP)
• Encriptação de email

Fornecedores e cartões suportados por OpenSC — exemplos:

• ASEPCOS
• FTCOSPK01C
• OpenPGP Card
• Cyberflex
• CardOs
• STARCOS

Importante: não inventamos números de compatibilidade; verifique sempre a lista de cartões suportados pela versão do OpenSC utilizada.

Ambiente de desenvolvimento

O ambiente de desenvolvimento foi preparado conforme descrito no artigo anterior. Neste texto assumimos que existe uma árvore LFS do IPFire com o diretório raiz do projeto e que os pacotes fonte já foram colocados em /usr/src/cache.

Nota: muitos comandos a seguir são executados dentro do shell LFS de IPFire, invocado com ./make shell a partir do diretório raiz do projeto.

Fluxo geral

1. Entrar no shell de teste do IPFire com ./make shell
2. Compilar e instalar pcsc-lite no ambiente de teste
3. Compilar e instalar CCID apontando para as headers de pcsc-lite
4. Compilar e instalar OpenSC
5. Criar lfs scripts e atualizar make.sh para gerar pacotes .ipfire
6. Ajustar rootfiles, construir pacotes via make.sh build
7. Copiar pacotes gerados para o sistema vivo e instalar via pakfire

Entrando no shell de testes

Execute na raiz do projeto:

./make shell

O cache de fontes do ambiente de build fica em /usr/src/cache. Todos os pacotes necessários para este tutorial foram colocados nesse diretório.

A seguir demonstramos os passos de compilação por pacote, com screenshots de exemplo do processo.

Compilar e instalar pcsc-lite

No diretório de fontes execute:

tar -xf pcsc-lite-1.8.18.tar.bz2
cd pcsc-lite-1.8.18
./configure
make
make install

É recomendável instalar a dependência libudev-dev no ambiente antes de compilar:

apt-get install libudev-dev

Se tudo correr bem, o script configure não apresenta erros e o make instala os binários e as headers em /usr/local onde poderão ser detectados pelos próximos pacotes.

Após a instalação, verifique se o daemon pcscd está em execução no shell de teste:

ps aux | grep pcscd

Caminhos importantes mostrados pelo install do pcsc-lite serão usados pelo configure do CCID.

Compilar e instalar CCID

No diretório contendo o tarball do CCID execute:

tar -xf ccid-1.4.24.tar.bz2
cd ccid-1.4.24
./configure PCSC_CFLAGS=-I/usr/local/include/PCSC

Se o configure reclamar que libpcsclite.pc não foi encontrado pelo pkg-config, exporte PKG_CONFIG_PATH para que ele encontre os ficheiros .pc instalados em /usr/local/lib/pkgconfig:

export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/
./configure PCSC_CFLAGS=-I/usr/local/include/PCSC

Quando o configure localizar corretamente as dependências do PCSC, proceda com:

make
make install

Após a instalação, copie as regras udev fornecidas pelo CCID para o diretório de regras do sistema de destino, garantindo que leitores sejam reconhecidos automaticamente:

cp drivers/92_pcscd_ccid.rules /etc/udev/rules

Verifique o conteúdo do ficheiro 92_pcscd_ccid.rules; ele mapeia IDs de fornecedores e dispositivos para permissões corretas.

Compilar e instalar OpenSC

Extraia e configure o OpenSC:

tar -xf opensc-0.16.0.tar.bz2
cd opensc-0.16.0
./configure
make
make install

O configure do OpenSC verifica dependências como libpcsclite, libp11 e outras. Corrija paths de pkg-config se necessário como feito anteriormente.

Após a instalação, valide algumas ferramentas básicas do OpenSC, por exemplo:

opensc-tool --list-readers
pkcs11-tool --list-slots

Preparar os lfs scripts e gerar pacotes para IPFire

No diretório de desenvolvimento do IPFire, crie os lfs scripts para pcsc-lite-1.8.18, ccid-1.4.24 e opensc-0.16.0 e salve-os em lfs/. Edite o make.sh conforme necessário para incluir os novos pacotes no processo de build.

Coloque os três lfs scripts dentro de lfs/ e execute os comandos ipfiremake correspondentes para cada pacote:

ipfiremake pcsc-lite
ipfiremake ccid
ipfiremake opensc

Depois execute o build geral (necessário rodar duas vezes em alguns casos):

./make.sh build

Se o build gerar rootfiles ausentes para os novos pacotes, copie os ficheiros de log para config/rootfiles/packages e renomeie-os para os nomes esperados pelo sistema de build:

cp log/pcsc-lite-1.8.18 config/rootfiles/packages/pcsc-lite
cp log/ccid-1.4.24 config/rootfiles/packages/ccid
cp log/opensc-0.16.0 config/rootfiles/packages/opensc

Alguns rootfiles podem conter o caractere + no seu conteúdo; remova-o com sed antes de relançar a compilação:

sed -i 's/+//g' config/rootfiles/packages/pcsc-lite
sed -i 's/+//g' config/rootfiles/packages/ccid
sed -i 's/+//g' config/rootfiles/packages/opensc

Pacote gerado: ao final do build, os ficheiros .ipfire serão colocados em packages/ com o formato nome-versão-revisao.ipfire, por exemplo pcsc-lite-1.8.18-2.ipfire.

Preparar scripts de instalação para pakfire

PakFire é o gestor de pacotes do IPFire. Para cada novo addon crie um diretório em src/paks com o mesmo nome do pacote e copie os scripts padrão install.sh, uninstall.sh e update.sh a partir de src/paks/default/.

mkdir -p src/paks/pcsc-lite
cp src/paks/default/{install.sh,uninstall.sh,update.sh} src/paks/pcsc-lite/
# repetir para ccid e opensc

Relance o build final para gerar pacotes completos:

./make.sh build

Ignore mensagens iniciais de rootfiles ausentes se já tiver atualizado config/rootfiles.

Instalar os pacotes no sistema vivo IPFire

Copie os pacotes gerados para o sistema IPFire em /opt/pakfire/tmp/ e extraia cada pacote no sistema alvo:

cp packages/pcsc-lite-1.8.18-2.ipfire /opt/pakfire/tmp/
# no sistema alvo
cd /opt/pakfire/tmp
tar -xvf pcsc-lite-1.8.18-2.ipfire
tar -xvf ccid-1.4.24-2.ipfire
tar -xvf opensc-0.16.0-2.ipfire

Em seguida execute os scripts install.sh extraídos para cada pacote:

cd pcsc-lite
./install.sh
cd ../ccid
./install.sh
cd ../opensc
./install.sh

As capturas a seguir mostram instalações bem-sucedidas para cada pacote.

Verificações pós-instalação

1. Reinicie udev ou reconecte o leitor para aplicar regras:

systemctl restart systemd-udevd || /etc/init.d/udev restart
udevadm control --reload-rules
udevadm trigger

2. Verifique se pcscd está ativo e escutando sockets:

ps aux | grep pcscd
ss -x | grep pcscd

3. Teste leitores e cartões com OpenSC:

opensc-tool --list-readers
pkcs11-tool --list-slots

4. Revise permissões das portas USB e dos dispositivos em /dev, como /dev/bus/usb/*, e ajuste conforme necessário via udev rules.

Runbook de incidente: leitor não detectado

Passos rápidos para resolver um leitor não detectado após instalação:

1. Confirmar USB físico: trocar cabo, porta e testar em outro host.
2. Confirmar udev: udevadm monitor –udev e verificar se o evento aparece ao conectar.
3. Verificar regras: confere se 92_pcscd_ccid.rules está presente em /etc/udev/rules e sem erros de sintaxe.
4. Reiniciar pcscd: systemctl restart pcscd ou /etc/init.d/pcscd restart.
5. Ver logs: journalctl -u pcscd -n 200 ou olhar /var/log/messages.
6. Teste OpenSC: opensc-tool –list-readers.
7. Se o ficheiro libpcsclite.pc não for encontrado, revalide PKG_CONFIG_PATH e paths de instalação de pcsc-lite.
8. Se continua falhar, testar com pcscd em foreground: pcscd -f -d para obter debug detalhado.

Importante: ao reportar um incidente inclua saídas de pcscd -f -d, lsusb, udevadm info –query=all –name=/dev/bus/usb/BBB/DDD e versões dos pacotes.

Checklist por papel

Desenvolvedor do addon

• Preparar fonte em /usr/src/cache
• Criar lfs script em lfs/
• Ajustar make.sh conforme padrão do projeto
• Executar builds locais e corrigir dependências

Packager

• Atualizar config/rootfiles/packages com rootfiles corretos
• Remover caracteres indesejados dos rootfiles
• Criar diretório em src/paks e copiar scripts padrão
• Gerar pacotes .ipfire e testar extração

Administrador do sistema destino

• Copiar pacotes para /opt/pakfire/tmp
• Extrair e executar install.sh
• Aplicar regras udev e reiniciar serviços
• Testar leitores com opensc-tool e pkcs11-tool

Critérios de aceitação

• pcscd inicia automaticamente no boot
• leitores CCID aparecem em opensc-tool –list-readers
• pkcs11-tool lista slots do cartão
• pacotes .ipfire instalam sem erros via install.sh
• regras udev aplicam permissão de acesso ao dispositivo

Compatibilidade e migração

• Verifique a compatibilidade do OpenSC com versões mais antigas de cartões; algumas features PKCS#15 podem variar por cartão e fornecedor.
• Ao migrar de uma versão pré-existente do IPFire, faça backup de /etc/pcscd e de regras udev personalizadas antes de sobrescrever.
• Em ambientes com custom SELinux/AppArmor, ajuste políticas para permitir acesso a /dev/bus/usb/ e sockets pcscd.

Segurança e boas práticas

• Nunca exponha o daemon pcscd a redes não confiáveis; rode-o localmente e limite acessos.
• Revise e aplique regras udev que atribuam permissões mínimas necessárias para usuários ou grupos específicos.
• Quando usar smart cards para autenticação, combine com políticas de revogação e armazenamento seguro de chaves de backup.

Mini-metodologia para reproduzir o build em outra máquina

1. Preparar árvore de build do IPFire e copiar pacotes-fonte para /usr/src/cache
2. Entrar no shell de build com ./make shell
3. Compilar pcsc-lite, instalar em /usr/local
4. Exportar PKG_CONFIG_PATH=/usr/local/lib/pkgconfig e compilar CCID
5. Compilar OpenSC com dependências resolvidas
6. Criar/ajustar lfs scripts e executar ./make.sh build
7. Validar pacotes gerados e copiá-los para o sistema destino

Testes e casos de aceitação básicos

• Teste 1: Conectar leitor USB e verificar que opensc-tool –list-readers reporta ao menos um leitor
• Teste 2: Inserir cartão compatível e executar pkcs11-tool –list-slots para confirmar slot
• Teste 3: Gerar um par de chaves no cartão via pkcs11-tool e verificar que operações criptográficas funcionam
• Teste 4: Reboot do sistema alvo e confirmação de que pcscd é iniciado automaticamente

Glossário (uma linha cada)

pcsc-lite: pacote que fornece o daemon pcscd e a implementação PC/SC no Linux. CCID: padrão de interface para leitores de smart card que funcionam sobre USB. OpenSC: conjunto de ferramentas e bibliotecas para interagir com smart cards via PKCS#11 e PKCS#15. PKCS#11: API padrão para dispositivos criptográficos, incluindo smart cards. udev: gerenciador de dispositivos do Linux que aplica regras de permissão e nomes de dispositivo.

Perguntas frequentes rápidas

Q: Preciso recompilar o kernel para suportar CCID? A: Não, CCID funciona como driver em espaço de usuário, desde que o kernel exponha o barramento USB e permissão de acesso a dispositivos.

Q: Todos os leitores USB são compatíveis? A: Nem todos. Procure leitores com conformidade CCID e verifique se o vendor/device ID está coberto por regras udev e drivers.

Conclusão

Neste tutorial demonstramos como compilar pcsc-lite, CCID e OpenSC no ambiente de build do IPFire, como preparar lfs scripts e criar pacotes .ipfire para instalação no sistema alvo. Também incluímos checklists por papel, um runbook de incidente para leitores não detectados, critérios de aceitação e sugestões de segurança. Com estes passos é possível integrar leitores de smart card e tokens de hardware ao IPFire 2.19 e habilitar usos como autenticação forte, VPNs e encriptação de ficheiros.

Resumo rápido: configure dependências, garanta caminhos de pkg-config, copie regras udev, atualize rootfiles, gere pacotes .ipfire e instale no sistema vivo. Teste leitores com opensc-tool e pkcs11-tool.

Notas finais

• Sempre teste com o hardware alvo antes de fazer rollout em produção.
• Mantenha backups das regras udev e dos scripts de instalação para recuperação rápida.