Guia prático do age no Linux
· 25 min de leitura
- linux
- security
- cryptography
Antes de começar
O age criptografa arquivos com uma linha de comando e chaves de uma linha de texto. Este guia mostra cada comando rodando de verdade, o output que ele imprime e o que acontece por baixo.
Todos os outputs abaixo foram capturados com o age v1.3.2 no Linux (e, onde aparecem, com o ssh-keygen do OpenSSH e o sops 3.13.3). As chaves que aparecem foram geradas só para este artigo e já foram descartadas: nunca publique a sua.
Quem faz o age
O age (sempre escrito em minúsculas) foi projetado por Filippo Valsorda (@FiloSottile) e Ben Cox (@benjojo). As peças que você vai encontrar:
| O quê | Onde |
|---|---|
| Especificação do formato | c2sp.org/age |
Implementação de referência em Go (age, age-keygen, age-inspect) | github.com/FiloSottile/age |
| Binários oficiais | dl.filippo.io/age |
| Implementação em Rust, totalmente compatível | rage |
| Implementação em TypeScript (navegador, Node.js) | typage |
| Plugins, ferramentas e integrações | awesome-age |
Como o formato é uma especificação pública, um arquivo criado com o age abre com o rage e vice-versa. Para uma ferramenta em que você vai confiar seus dados, instale a partir dessas fontes ou da sua distribuição, não de um mirror qualquer.
O que o age faz, e o que ele não faz
O age faz uma coisa só: criptografa arquivos para que só quem tem certas chaves consiga ler. Se você já usou o GPG, a diferença é o escopo. O GPG (OpenPGP) também assina, mantém chaveiros, tem rede de confiança e dezenas de opções. O age não tem configuração, nem chaveiros, nem assinaturas. Menos recursos significa menos jeitos de errar, mas também significa que tem uma coisa que o age não diz: quem criou um arquivo.
Para criptografar, basta a chave pública, que por definição você distribui. Então qualquer pessoa que tenha ela consegue criar um arquivo que abre normalmente com a sua chave privada. Aqui, uma "mensagem de outra pessoa" criptografada para uma chave gerada para este exemplo:
echo 'Please wire the payment to account 99-1234.' \
| age -r age1kayung4jcqqar5m50l82jyd87zmkdz24fh7mcgqnwl963vmx696q79xdjk -o invoice.txt.age
age -d -i key.txt invoice.txt.age
Please wire the payment to account 99-1234.
Nenhum aviso. O age garante que ninguém mais lê o conteúdo e que ninguém alterou o arquivo depois de criado (seção 2), mas não que ele veio de quem você espera. Arquivos com senha são a exceção: só quem conhece a senha consegue criar um (seção 3).
Quando a autoria importa, assine o arquivo criptografado. O ssh-keygen que você já tem faz isso:
ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n file report.age
Signing file report.age
Write signature to report.age.sig
Quem recebe mantém um arquivo allowed_signers com as chaves em que confia, uma linha por pessoa (um identificador e a chave pública SSH):
[email protected] ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBqTqH...
E confere a assinatura antes de abrir o arquivo:
ssh-keygen -Y verify -f allowed_signers -I [email protected] -n file -s report.age.sig < report.age
Good "file" signature for [email protected] with ED25519 key SHA256:BO8eWB7uElf7Lv2mWQSMgnFCQv4UKtc+3Z1pfxRL5WY
A mesma assinatura conferida contra a fatura forjada:
Signature verification failed: incorrect signature
Could not verify signature.
O -n file é um namespace: uma assinatura feita para arquivos não pode ser reaproveitada, por exemplo, como assinatura de commit no git. Se você preferir não assinar com chaves SSH, o minisign faz o mesmo papel.
Instalação
No Ubuntu, o pacote vem direto do repositório:
sudo apt install age
age --version
1.1.1
Repare na versão. O repositório do Ubuntu costuma estar atrás da versão oficial, e recursos como chaves pós-quânticas (-pq) e o comando age-inspect só existem a partir da v1.3.0. Para ter a última versão, baixe o binário oficial:
curl -L -o age.tar.gz "https://dl.filippo.io/age/latest?for=linux/amd64"
tar xzf age.tar.gz
sudo install age/age age/age-keygen age/age-inspect /usr/local/bin/
age --version
v1.3.2
O pacote instala alguns comandos. Os que importam para o dia a dia:
| Comando | Para que serve |
|---|---|
age | Criptografa e descriptografa |
age-keygen | Gera chaves e extrai a chave pública de uma privada |
age-inspect | Mostra informações de um arquivo .age sem abri-lo (v1.3.0+) |
1. Gerando suas chaves
Tudo começa com um par de chaves: a privada (sua, secreta) e a pública (que você distribui). Quem tem a pública consegue trancar arquivos para você; só a privada destranca.
mkdir -p ~/.config/age
chmod 700 ~/.config/age
age-keygen -o ~/.config/age/key.txt
Public key: age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4
O que aconteceu: o age-keygen sorteou 32 bytes aleatórios (a chave privada X25519), calculou a chave pública correspondente, gravou tudo em key.txt e imprimiu a pública na tela. O arquivo já nasce com permissão 600 (só você lê):
ls -l ~/.config/age/key.txt
-rw------- 1 david david 189 Oct 1 09:31 key.txt
Por dentro, o key.txt tem só três linhas:
# created: 2026-10-01T09:31:13-03:00
# public key: age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4
AGE-SECRET-KEY-1QUS6JV3SG65QCQHVHNVN4CEGY5QJKWVUDDMEYX067HVR5Y45LD0Q926WJ2
- As linhas com
#são comentários: data de criação e a chave pública, para consulta. - A linha
AGE-SECRET-KEY-1...é a chave privada inteira. Quem tiver essa linha abre todos os seus arquivos. - O formato é Bech32 (o mesmo usado em endereços Bitcoin): tem checksum embutido, então um caractere digitado errado é detectado em vez de gerar uma chave diferente silenciosamente.
Recuperando a chave pública depois
Perdeu o age1...? Ele é derivado da privada, então dá para recalcular a qualquer momento:
age-keygen -y ~/.config/age/key.txt
age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4
Proteção contra sobrescrever
O age-keygen se recusa a apagar uma chave existente, o que evita perder a chave por acidente:
age-keygen -o ~/.config/age/key.txt
age-keygen: error: failed to open output file "key.txt": open key.txt: file exists
Sem -o, ele imprime a chave nova na tela em vez de gravar, útil para mandar direto para outro comando (veremos isso na seção 8).
2. Criptografando e descriptografando um arquivo
Vamos criar um arquivo com algo sensível e trancá-lo para a nossa própria chave pública.
printf 'Senha do wifi: banana123\nPIN do cofre: 4271\n' > notas.txt
age -r age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4 \
-o notas.txt.age notas.txt
Não aparece nada na tela. No mundo UNIX, silêncio significa sucesso.
-r(recipient) diz para quem você está criptografando: a chave pública.-o(output) é o arquivo de saída. Sem ele, o resultado vai para a saída padrão: é isso que faz pipes e>funcionarem, mas num terminal o age se recusa a imprimir binário (veja Erros que você vai encontrar). Na prática, sempre termine o comando com-o, um>ou um pipe.- O último argumento é a entrada. Sem ele, o age lê da entrada padrão (por isso funciona em pipes).
Um atalho para criptografar para você mesmo: em vez da chave pública, passe o seu próprio arquivo de chave com -i. Nesse caso o -e (encrypt) é obrigatório, senão o age acha que você esqueceu o -d:
age: error: -i/--identity and -j can't be used in encryption mode unless symmetric encryption is explicitly selected with -e/--encrypt
age: hint: did you forget to specify -d/--decrypt?
age -e -i ~/.config/age/key.txt -o notas.txt.age notas.txt
O resultado é o mesmo: um arquivo criptografado para a sua chave pública, que o age deriva da privada.
O que aconteceu por baixo
- O age sorteou uma file key de 16 bytes, exclusiva deste arquivo.
- Gerou um par de chaves descartável, fez um acordo X25519 com a sua chave pública e usou o resultado para trancar a file key. Esse "envelope" é a stanza.
- Calculou um selo (HMAC) sobre o cabeçalho, para detectar adulteração.
- Criptografou o conteúdo com ChaCha20-Poly1305, em blocos de 64 KiB.
Como o arquivo .age parece por dentro
O cabeçalho é texto legível; só o conteúdo é binário:
head -c 200 notas.txt.age
age-encryption.org/v1 <- versão do formato
-> X25519 s9NpeNrYYto2vMS96IR5GbM2oP+bXmN53bgC6wdiDUA <- stanza: tipo + chave descartável
VzNEka0tpZrzqf57D5qJxRAA/Kja1jrc+v7l36mjlfI <- file key trancada
--- fxUc7YAlZIygGc+opSRyP0PfK7qEGzFfLpTQkWMtREU <- selo (MAC) do cabeçalho
�'L`5&�"0�.�)���:6�>6�l ... <- conteúdo criptografado
As setas e comentários à direita foram adicionados para explicar; não fazem parte do arquivo.
Detalhe importante: o cabeçalho não diz para qual chave o arquivo foi criptografado. Ele só diz que é X25519. Quem interceptar o arquivo não sabe que ele é seu.
Tamanho
ls -l notas.txt notas.txt.age
-rw-r--r-- 1 david david 44 Oct 1 09:31 notas.txt
-rw-r--r-- 1 david david 244 Oct 1 09:31 notas.txt.age
Os 200 bytes extras são fixos: 168 do cabeçalho, 16 de nonce e 16 da etiqueta de autenticação. Para um arquivo de 1 GB, o acréscimo é desprezível (16 bytes a cada 64 KiB).
Descriptografando
age -d -i ~/.config/age/key.txt -o notas.txt notas.txt.age
cat notas.txt
Senha do wifi: banana123
PIN do cofre: 4271
-d(decrypt) inverte a operação.-i(identity) aponta para a chave privada. Pode repetir-icom várias chaves; o age testa todas.
Para só ler, sem gravar em disco, omita o -o. O texto vai para a tela ou para outro programa:
age -d -i ~/.config/age/key.txt notas.txt.age | less
Erros que você vai encontrar
Chave errada:
age: error: no identity matched any of the recipients
Nenhuma das chaves passadas em -i consegue abrir nenhum envelope do cabeçalho.
Arquivo alterado ou corrompido (troquei um único byte no final):
age: error: failed to decrypt and authenticate payload chunk, file may be corrupted or tampered with
O age nunca entrega conteúdo adulterado em silêncio: se um byte mudou, ele para.
Mandar binário para o terminal (esqueceu o -o):
age: error: refusing to output binary to the terminal
age: hint: did you mean to use -a/--armor?
age: hint: force anyway with "-o -"
age: report unexpected or unhelpful errors at https://filippo.io/age/report
Proteção contra encher a tela de lixo binário. Use -o arquivo, um pipe, ou -a (seção 7). O -o - da dica significa "saída padrão": ele não salva nada, só força os bytes criptografados na tela.
Atenção: o age sobrescreve o arquivo de -o sem perguntar, e não apaga o original. Depois de criptografar, notas.txt continua lá em texto puro até você removê-lo, e removê-lo direito exige mais que um rm (seção 14).
3. Usando senha em vez de chave
Para mandar um arquivo para alguém que não tem chave age, ou para proteger algo rápido, use -p. Não precisa de nenhuma chave gerada antes.
age -p -o segredo.age notas.txt
Enter passphrase (leave empty to autogenerate a secure one):
age: using autogenerated passphrase "erase-resource-child-candy-example-pear-pave-finish-social-cinnamon"
O que aconteceu: apertei Enter sem digitar nada e o age gerou uma senha de 10 palavras aleatórias. Ela é forte (cerca de 100 bits de entropia) e mais fácil de ditar ao telefone do que uma sequência de símbolos. Copie para o gerenciador de senhas: ela não aparece de novo.
Se preferir digitar a sua, o age pede duas vezes:
Enter passphrase (leave empty to autogenerate a secure one):
Confirm passphrase:
A senha nunca aparece na tela nem pode ser passada como argumento. Isso é proposital: um argumento ficaria no histórico do shell e visível no ps para outros usuários.
O cabeçalho muda
age-encryption.org/v1
-> scrypt 8CmxPV7t2hEFpbJXxmtuKQ 18
luCBRo3+FegXbAvg5C1qn4K35ldq1S1xMQACKoG91Ms
--- NzEnS4EHMGRzBfGkjTORkJ7K10upGbpyJXsEy8MQm6U
A stanza agora é scrypt. Os dois valores são o sal aleatório e o fator de trabalho 18, ou seja, 2^18 iterações do scrypt. É isso que faz cada tentativa de senha custar memória e tempo, tornando força bruta cara.
Abrindo
Não precisa de -i: o age percebe pelo cabeçalho que é senha e pergunta.
age -d segredo.age
Enter passphrase:
Senha do wifi: banana123
PIN do cofre: 4271
Senha errada:
age: error: incorrect passphrase
Limitação
Senha e chave não se misturam no mesmo arquivo:
age: error: -p/--passphrase can't be combined with -r/--recipient
Um arquivo com senha tem exatamente uma senha e nenhum outro destinatário. O motivo está na especificação: um arquivo com senha traz uma garantia implícita de autoria, porque só quem conhece a senha poderia ter criado ele. Adicionar uma chave pública quebraria isso, porque qualquer pessoa com a chave pública poderia criar o arquivo (veja "O que o age faz, e o que ele não faz"). Para compartilhar com várias pessoas, use chaves (próxima seção).
4. Vários destinatários
Um mesmo arquivo pode ser aberto por várias chaves. Basta repetir -r:
age -r age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4 \
-r age18cmdfem3afacqvmmaqajevjykjwqjvqh4rvxsmq3p66af2nk83hs2p2u8n \
-o multi.age notas.txt
Com muitas chaves, a linha fica ilegível. Melhor guardar as chaves públicas num arquivo e usar -R (maiúsculo).
Para montar esse arquivo a partir da sua chave, use o age-keygen -y, que imprime a chave pública de uma chave privada (seção 1). O >> acrescenta ao final do arquivo, então rode uma vez por chave, com um comentário em cima dizendo de quem ela é (um > só substituiria o arquivo, o que só serve para a primeira chave):
echo "# David (laptop)" >> ~/.config/age/recipients.txt
age-keygen -y ~/.config/age/key.txt >> ~/.config/age/recipients.txt
Para a chave de outra pessoa, ela te manda a linha age1... dela (que é pública) e você acrescenta do mesmo jeito. Uma chave pública SSH (a linha de um arquivo .pub) também funciona (seção 6). O resultado:
cat ~/.config/age/recipients.txt
# David (notebook)
age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4
# Servidor de backup
age18cmdfem3afacqvmmaqajevjykjwqjvqh4rvxsmq3p66af2nk83hs2p2u8n
age -R ~/.config/age/recipients.txt -o multi.age notas.txt
Linhas vazias e linhas com # são ignoradas, então dá para documentar de quem é cada chave. Esse arquivo só contém chaves públicas: pode ir para o git sem problema.
O que muda no arquivo
O cabeçalho agora tem dois envelopes, um para cada chave, ambos contendo a mesma file key:
age-encryption.org/v1
-> X25519 CEWWVmjfNsH6CV2r8mo41d9yWWthHXgtjdfYfmjxuW0 <- envelope 1
XJLtj5tF6HfQetjxYo5aLY9xoiWVE6IdEngR/enCeLY
-> X25519 +tqbJAovTLWwj0tRCVw3e8ppTkAPHlOb0Z6VQIMGBEE <- envelope 2
LsG4O64UFy26E208VtQLOO8IdgBwlTyb7ilYfi4IKwc
--- sqKMheXQyjVDCDUAZrb6h1Ier1sSej4Yft5yy72mm+s
O conteúdo é criptografado uma vez só. Cada destinatário extra custa só cerca de 100 bytes de cabeçalho, não importa o tamanho do arquivo: o arquivo de 44 bytes foi de 244 para 342 bytes.
Na hora de abrir, cada pessoa usa a própria chave e o age testa os envelopes até achar o seu:
age -d -i chave-do-servidor.txt multi.age
Senha do wifi: banana123
PIN do cofre: 4271
Esse é o mecanismo por trás da estratégia de backup com chave de recuperação: criptografe sempre para a chave do dia a dia e para uma chave guardada offline.
O outro lado: tirar uma chave do recipients.txt só vale para os arquivos que você criar daí em diante. Os arquivos que já existem continuam com o envelope daquela chave (seção 12).
5. Pastas inteiras com tar e pipes
O age criptografa um fluxo de bytes, não pastas. Para uma pasta, junte tudo com o tar e passe o resultado direto para o age por um pipe (|):
tar czf - ~/Documentos | age -R ~/.config/age/recipients.txt > documentos.tar.gz.age
Lendo da esquerda para a direita:
tar czf - ~/Documentosempacota (c), comprime com gzip (z) e escreve no arquivo-, que significa a saída padrão.|liga essa saída na entrada do age.age -R ...criptografa o que chega, sem saber nem se importar que é um tar.>grava o resultado em disco.
Por que pipe e não dois passos? Se você fizesse tar czf docs.tar.gz e depois age docs.tar.gz, uma cópia completa e legível dos seus documentos ficaria gravada no disco, mesmo que por segundos. Em SSD, apagar depois não garante que os dados sumiram. Com pipe, o conteúdo em claro só existe na memória.
Outra vantagem: o age processa em blocos de 64 KiB, então uma pasta de 50 GB não precisa caber na memória.
Restaurando
O caminho inverso: o age descriptografa e entrega para o tar extrair.
age -d -i ~/.config/age/key.txt documentos.tar.gz.age | tar xzvf -
Documentos/
Documentos/notas.txt
Documentos/contrato.pdf
O v do tar lista cada arquivo extraído. Para só ver o conteúdo do backup sem extrair, troque x por t:
age -d -i ~/.config/age/key.txt documentos.tar.gz.age | tar tzf -
Esse mesmo padrão funciona com qualquer coisa que escreva na saída padrão: pg_dump, mysqldump, docker save, zfs send. Por exemplo, um dump de banco criptografado direto:
pg_dump meu_banco | age -R recipients.txt > banco-$(date +%F).sql.age
6. Usando chaves SSH que você já tem
Se você já tem uma chave SSH, o age aceita ela no lugar de uma chave age. A pública criptografa, a privada abre:
age -R ~/.ssh/id_ed25519.pub -o ssh.age notas.txt
age -d -i ~/.ssh/id_ed25519 ssh.age
Senha do wifi: banana123
PIN do cofre: 4271
Repare que usei -R com o arquivo .pub: ele é tratado como um arquivo de destinatários com uma linha. Com -r, você passaria o conteúdo da chave entre aspas.
Se a sua chave privada SSH tiver senha, o age pede essa senha na hora de abrir. O ssh-agent não é suportado.
Mandando algo para alguém pelo GitHub
O GitHub publica as chaves SSH de qualquer usuário em github.com/<usuario>.keys. Combinando com -R - (ler destinatários da entrada padrão):
curl -s https://github.com/usuario.keys | age -R - relatorio.pdf > relatorio.pdf.age
O arquivo sai criptografado para todas as chaves que a pessoa tem cadastradas, e qualquer uma delas abre.
O que muda no arquivo, e por que isso importa
age-encryption.org/v1
-> ssh-ed25519 nQeBCQ VG6b+02qyQ27wq/sBjnKf8UA6eQxkH/ScBHfnrQbDiQ
2CSuE4Z+V0OhaekPTwgePe1EYcocZNk4tkkNuq9D8Hk
--- Js2SddA8dlfpSoncdyCEgVtKn9jgPyMaK7bzZrYs8no
O nQeBCQ é uma etiqueta derivada da chave pública. Ela serve para o age achar o envelope certo rápido, mas tem um efeito colateral: criptografei outro arquivo para a mesma chave e a etiqueta se repetiu (nQeBCQ de novo). Quem tiver vários arquivos seus consegue saber que todos foram para a mesma chave, e quem souber sua chave pública (que está no GitHub) consegue ligá-los a você. Com chaves age1... isso não acontece.
Quando usar SSH: para mandar algo pontual para alguém que só tem chave SSH. Quando evitar: para guardar arquivos a longo prazo, porque chaves SSH costumam ser trocadas ou descartadas sem ninguém lembrar que arquivos dependiam delas, e chaves SSH em YubiKey não servem para descriptografar.
7. Formato texto (armor)
O arquivo .age normal é binário, o que quebra se você colar num chat, num e-mail ou num arquivo YAML. A opção -a (armor) gera a mesma coisa codificada em texto:
echo "token=abc123" | age -a -r age1ydslw3ud3lhduft004quqne7qtyqjt3df7wj6dw5puurfqayzymq8u6zg4
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBHaEhydE42Tm1WY2d6S1E3
eTdEVnNZYmxtZ21CZkkvT1FtQk9sakl6YkhzCnpNcUMwOTNYc0lBV2tXNUVaWVht
eVRTN05ONHJlWXQ1ZndlN0p6RzN2SjQKLS0tIFMyUHNlLytKeUVzNzA3OUhGQWFK
U1N5dVU1aXVCWStlTEJhSUtwdmkrRlUKEkPt/tHuycOo+rAklxObxTCOogCoBydR
blr/KSzvZsDBT76g+zMLQ9q1ATGs
-----END AGE ENCRYPTED FILE-----
O que aconteceu: é o mesmo arquivo de antes, só que passado por Base64 e embrulhado entre as linhas BEGIN e END (formato PEM, o mesmo de certificados TLS). Se você decodificar o Base64, encontra o cabeçalho age-encryption.org/v1 lá dentro. O tamanho cresce cerca de 33%.
Para abrir, não precisa avisar que é armor: o age detecta sozinho.
age -d -i ~/.config/age/key.txt << 'EOF'
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBHaEhydE42Tm1WY2d6S1E3
...
-----END AGE ENCRYPTED FILE-----
EOF
token=abc123
O << 'EOF' é um heredoc: tudo até a linha EOF vira a entrada do comando. É um jeito prático de colar um bloco recebido no chat direto no terminal.
Quando usar: segredos em arquivos de configuração versionados, mensagens em chat, campos de texto em banco. Quando não usar: arquivos grandes, porque o binário é menor e mais rápido.
Segredos no git: sops
Para arquivos de configuração num repositório, a ferramenta comum é o sops, que usa o age por baixo. Você declara quem pode ler num .sops.yaml:
creation_rules:
- age: age1kayung4jcqqar5m50l82jyd87zmkdz24fh7mcgqnwl963vmx696q79xdjk
sops encrypt --in-place secrets.yaml
cat secrets.yaml
database:
user: ENC[AES256_GCM,data:+Cbo,iv:jewOHvfShqtXjrFDgWXfo4Ox/wFlWjPjgzu9SJWe1tU=,tag:yc4HU9+iKEGCVGspYTf8HQ==,type:str]
password: ENC[AES256_GCM,data:BWALoqm5pg==,iv:UAyb4utFNLIdabUru/JQwzvs3lxm9J/NE5WVZbvIg9A=,tag:MWn1rA5pcd5Us0je9X1+9g==,type:str]
sops:
age:
- enc: |
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBjVElXdWtLbzFrNEUxRlp2
...
-----END AGE ENCRYPTED FILE-----
recipient: age1kayung4jcqqar5m50l82jyd87zmkdz24fh7mcgqnwl963vmx696q79xdjk
(Resumido.) É o envelope da seção 2 de novo: o sops criptografa os valores com uma chave própria e tranca essa chave com o age, em formato armor. Só os valores são criptografados: os nomes (database, user, password) continuam legíveis, então o diff no git ainda mostra o que mudou. Isso é prático, e também é metadado (seção 11).
Para ler:
SOPS_AGE_KEY_FILE=~/.config/age/key.txt sops decrypt secrets.yaml
database:
user: app
password: hunter2
8. Protegendo a própria chave privada com senha
O key.txt é texto puro: quem copiar o arquivo usa a chave. Se a chave vai ficar num lugar menos confiável (pendrive, nuvem, servidor compartilhado), dá para trancá-la com uma senha usando o próprio age:
age-keygen | age -p -o ~/.config/age/key.age
Public key: age1va6rkr2j3klf7qewphexy37wcy3ndnmkrnr2wnghv2yr5kvdwalspmex6j
Enter passphrase (leave empty to autogenerate a secure one):
Confirm passphrase:
O que aconteceu: o age-keygen sem -o jogou a chave nova na saída padrão, e o pipe entregou ela direto para age -p, que a criptografou com senha. A chave em texto puro nunca tocou o disco. A pública aparece na tela (o age-keygen a imprime separadamente, no stderr): anote-a, porque para recuperá-la depois você vai precisar da senha.
O arquivo resultante é um .age comum com stanza scrypt:
age-encryption.org/v1
-> scrypt sa5OxAPP8cKFzORwhMpNMQ 18
JHJelDmEZGXtmSrJQJmJgsIrauj9WPd90jGiGm50CmM
Usando
Passe o key.age em -i como se fosse um key.txt. O age percebe que ele está criptografado e pede a senha:
age -d -i ~/.config/age/key.age arquivo.age
Enter passphrase for identity file "key.age":
oi
Vale a pena? Para a chave do dia a dia num notebook com disco criptografado, normalmente não: quem consegue ler o arquivo já está dentro da sua sessão e pode capturar a senha também. Vale para cópias de backup da chave, que ficam fora do seu controle direto. É a forma recomendada de guardar a chave de recuperação num pendrive.
9. Chaves pós-quânticas
A partir da v1.3.0, o age gera chaves que resistem a um futuro computador quântico. O risco que elas cobrem é o de alguém guardar seus arquivos hoje e quebrá-los daqui a 10 ou 20 anos.
age-keygen -pq -o ~/.config/age/key-pq.txt
age-keygen -y ~/.config/age/key-pq.txt > recipient-pq.txt
Public key: age1pq1hetmtqfse3la3nges4v4x5zu4qzj3t5fhmxeyfg6tsh4mz5ymtu9dj7tf2mv2ul...
O output real tem 1.959 caracteres numa linha só (cortei aqui). Esse é o principal incômodo: a chave pública do algoritmo pós-quântico ML-KEM é grande. Por isso o fluxo recomendado é salvar a pública num arquivo e usar -R, em vez de colar com -r.
A privada, ao contrário, continua curta (AGE-SECRET-KEY-PQ-1...), porque é só uma semente de onde as chaves são derivadas.
Usando
Exatamente como antes:
age -R recipient-pq.txt -o pq.age notas.txt
age -d -i ~/.config/age/key-pq.txt pq.age
O cabeçalho agora tem a stanza mlkem768x25519, o híbrido de ML-KEM-768 (pós-quântico, padronizado pelo NIST) com X25519 (clássico). Para quebrar, um atacante precisa vencer os dois.
age-encryption.org/v1
-> mlkem768x25519 1GfS0gGndg60MDBCj2Ejhb7MXTmGCfzBJsJCR3UCs7aqMuHl/0A/FqWcUdH4cXG/...
Custos e restrições
- Tamanho: o cabeçalho foi de 168 para 1.627 bytes. Irrelevante para um backup de gigabytes, perceptível para mil arquivos pequenos.
- Não mistura com chaves clássicas:
age: error: incompatible recipients: can't mix post-quantum and classic recipients, or the file would be vulnerable to quantum computers
Faz sentido: se uma das chaves fosse clássica, o atacante quântico simplesmente abriria aquele envelope. Se você quer chave de recuperação, ela também precisa ser -pq.
- Senha já é pós-quântica: arquivos com
-pusam só criptografia simétrica, que computadores quânticos não quebram de forma prática. Oage-inspectconfirma isso (próxima seção). - Versão: o age 1.1.x do repositório do Ubuntu não entende essas chaves. Quem for abrir o arquivo precisa da v1.3.0+, ou do binário
age-plugin-pqinstalado.
10. Inspecionando sem abrir
O age-inspect (v1.3.0+) lê só o cabeçalho e conta o que dá para saber sem a chave. Útil para responder "com que tipo de chave eu tranquei esse backup de 2024?".
age-inspect multi.age
multi.age is an age file, version "age-encryption.org/v1".
This file is encrypted to the following recipient types:
- "X25519"
- "X25519"
This file does NOT use post-quantum encryption.
Size breakdown (assuming it decrypts successfully):
Header 266 bytes
Encryption overhead 32 bytes
Payload 44 bytes
-------------------
Total 342 bytes
Tip: for machine-readable output, use --json.
Lendo o resultado:
- Recipient types: um item por envelope. Dois
X25519= criptografado para duas chaves age. Note que ele mostra o tipo, mas não qual chave: essa informação não existe no arquivo. - Post-quantum: se o arquivo resiste a computador quântico.
- Size breakdown: cabeçalho, overhead (16 bytes de nonce + 16 de autenticação a cada bloco de 64 KiB) e o tamanho do conteúdo original. Dá para saber o tamanho exato do arquivo em claro sem abri-lo.
Comparando os arquivos criados neste guia:
| Arquivo | Tipo de destinatário | Pós-quântico | Cabeçalho |
|---|---|---|---|
notas.txt.age | X25519 | Não | 168 bytes |
multi.age | X25519, X25519 | Não | 266 bytes |
segredo.age | scrypt | Sim | 150 bytes |
pq.age | mlkem768x25519 | Sim | 1.627 bytes |
Para scripts, --json devolve o mesmo em formato estruturado:
age-inspect --json notas.txt.age
{
"version": "age-encryption.org/v1",
"postquantum": "no",
"armor": false,
"stanza_types": ["X25519"],
"sizes": {"header": 168, "overhead": 32, "min_payload": 44, "max_payload": 44}
}
(JSON resumido; o real traz também campos de armor e padding.) Um exemplo de uso: varrer a pasta de backups e listar quais arquivos ainda não são pós-quânticos.
for f in backups/*.age; do
age-inspect --json "$f" | grep -q '"postquantum": "no"' && echo "$f"
done
11. O que um arquivo criptografado ainda revela
O age esconde o conteúdo, não tudo em volta dele:
ls -l resignation-letter.txt.age
age-inspect resignation-letter.txt.age
-rw-rw-r-- 1 david david 238 Oct 1 18:47 resignation-letter.txt.age
Size breakdown (assuming it decrypts successfully):
Header 168 bytes
Encryption overhead 32 bytes
Payload 38 bytes
-------------------
Total 238 bytes
(Output do age-inspect resumido.)
- O nome: o age não mexe nele.
resignation-letter.txt.age(carta de demissão) diz muita coisa sem ser aberto. - O tamanho exato: o payload tem exatamente os 38 bytes do texto original, porque o age não adiciona preenchimento (
"max_padding": 0no--json). Para conteúdo curto e previsível (um sim ou não, um PIN, um entre poucos documentos conhecidos), só o tamanho já pode entregar. - Datas e dono: os metadados normais do sistema de arquivos, como em qualquer arquivo.
- Para quem ele é, às vezes: chaves age não deixam rastro no cabeçalho, mas chaves SSH deixam uma tag (seção 6), e chaves em hardware também (seção 13).
Quando isso importa, criptografe um pacote em vez de arquivos soltos: tar mais age (seção 5) deixa um arquivo só, com nome neutro, e os nomes, tamanhos e a quantidade de arquivos lá dentro só aparecem depois de descriptografar.
12. Quando uma chave vaza
O age não tem revogação. Cada arquivo guarda no cabeçalho um envelope para cada chave para a qual foi criptografado, para sempre. Se uma chave privada vazar, todo arquivo já criptografado para ela pode ser aberto, inclusive backups antigos.
Tirar a chave do recipients.txt não muda os arquivos que já existem. Aqui, um segredo criptografado para duas chaves (um notebook e um servidor antigo), depois que a chave do servidor vazou e foi removida da lista:
cat recipients.txt
age -d -i old-server.txt secrets.age
# laptop
age14smdf4csaq89p6740gykhwsrn8gsl5zxprswsczsl8gj5zvsxckqensy50
db password: hunter2
A correção é recriptografar para a lista atual. Faça isso por pipe, para o texto puro nunca tocar o disco:
age -d -i laptop.txt secrets.age | age -R recipients.txt -o secrets.age.new && mv secrets.age.new secrets.age
age -d -i old-server.txt secrets.age
age: error: no identity matched any of the recipients
O && só substitui o arquivo se a recriptografia deu certo.
Recriptografar só protege as cópias que você controla. Qualquer cópia feita antes (um backup em outro lugar, um arquivo já nas mãos de outra pessoa) continua abrindo com a chave vazada. Então, na prática:
- Gere uma chave nova e atualize o
recipients.txt. - Recriptografe os arquivos que você controla.
- Troque os próprios segredos (senhas, tokens) que estavam em arquivos que a chave antiga abria. Assuma que eles foram lidos.
13. Chaves em hardware e plugins
Até aqui a chave privada é uma linha de texto num arquivo: quem copia o arquivo tem a chave. Chaves em hardware, como um YubiKey, guardam ela dentro de um chip de onde não sai, e para descriptografar o dispositivo precisa estar conectado. O age suporta essas chaves por meio de plugins: programas separados chamados age-plugin-<nome>, que o age encontra no seu PATH e chama quando vê uma chave daquele tipo.
A configuração está em Chaves em hardware para o age: YubiKey e plugins.
Duas coisas importam para o resto deste guia:
- Perder o dispositivo é perder a chave, então criptografe sempre para uma segunda chave também, como a chave de recuperação em papel da seção 14.
- Chaves em hardware deixam uma tag, como as chaves SSH (seção 6): quem tem a chave pública consegue saber que um arquivo foi endereçado a ela.
14. Backup da chave, e o teste de restauração
O checklist do final pede backup da chave e teste de restauração. Veja como fazer os dois.
Em papel
A chave privada é uma linha só, e essa linha é o backup inteiro:
grep -v '^#' ~/.config/age/key.txt
AGE-SECRET-KEY-1WQ3AZLFDJMCPFR6YKKRD9VSD638GWR5V0T9G6WN8Q5VNTD9GL5SQMVX4VR
Imprima ou escreva à mão, e guarde fora de casa. Copiar à mão é mais seguro do que parece, graças ao Bech32 (seção 1): depois do prefixo, o alfabeto deixa de fora caracteres fáceis de confundir (1, b, i e o), e o checksum pega erros de digitação. Com um caractere errado:
age: error: reading "typo-key.txt": failed to read "typo-key.txt": error at line 1: malformed secret key: invalid checksum
Uma armadilha: digite de volta em maiúsculas. Em minúsculas, o age não reconhece:
age: error: reading "lower-key.txt": failed to read "lower-key.txt": error at line 1: unknown identity type
Se você prefere escanear a digitar, o PaperAge é uma ferramenta feita para backups de segredos em papel.
O teste de restauração
Um backup que nunca foi restaurado é uma esperança, não um backup. Teste usando só o que você teria depois de perder o notebook: a chave de recuperação do papel. Digite ela num arquivo novo e abra o backup:
mkdir restore-test && cd restore-test
nano key-from-paper.txt # a linha do papel
age -d -i key-from-paper.txt ../documents.tar.gz.age | tar xzf -
Depois compare com os originais, byte a byte:
(cd .. && sha256sum Documents/*) > ../original.sha
sha256sum -c ../original.sha
Documents/contract.pdf: OK
Documents/notes.txt: OK
No fim, apague o restore-test: o key-from-paper.txt é a sua chave privada em texto puro.
Apagando o original
Depois de criptografar, o original continua lá em texto puro (seção 2), e o rm só remove o nome: os dados ficam no disco até algo sobrescrevê-los. A ferramenta clássica é o shred, mas a própria documentação dele avisa que ele depende de o sistema de arquivos sobrescrever os dados no mesmo lugar, o que sistemas com journaling, RAID, snapshots e compressão não garantem (nem os copy-on-write, como btrfs e ZFS). Num SSD, o próprio disco decide onde cada escrita cai, então sobrescrever um arquivo normalmente preenche células novas e deixa as antigas intactas. E um backup ou snapshot pode já ter uma cópia.
O que funciona na prática:
- Criptografia de disco inteiro (LUKS, no Linux): o que sobrar no disco fica ilegível de qualquer jeito. Essa é a proteção de verdade.
- Pipes (seção 5): texto puro que nunca toca o disco nunca precisa ser apagado.
- Depois um
rmnormal no original.
15. Atalhos para o dia a dia
Digitar -R, -i e caminhos toda vez cansa. Coloque isto no final do ~/.bashrc (ou ~/.zshrc):
# --- age ---
export AGE_KEY="$HOME/.config/age/key.txt"
export AGE_RECIPIENTS="$HOME/.config/age/recipients.txt"
# enc arquivo1 arquivo2 ... -> cria arquivo1.age, arquivo2.age
enc() {
for f in "$@"; do
age -R "$AGE_RECIPIENTS" -o "$f.age" "$f" && echo "trancado: $f.age"
done
}
# dec arquivo1.age ... -> recria arquivo1
dec() {
for f in "$@"; do
[[ "$f" == *.age ]] || { echo "ignorado (não é .age): $f" >&2; continue; }
age -d -i "$AGE_KEY" -o "${f%.age}" "$f" && echo "aberto: ${f%.age}"
done
}
# ver arquivo.age -> mostra o conteúdo sem gravar em disco
ver() { age -d -i "$AGE_KEY" "$1"; }
# encdir pasta -> cria pasta.tar.gz.age via pipe
encdir() {
tar czf - "$1" | age -R "$AGE_RECIPIENTS" > "${1%/}.tar.gz.age" && echo "trancado: ${1%/}.tar.gz.age"
}
Recarregue com source ~/.bashrc e teste:
enc a.txt b.txt
rm a.txt
dec a.txt.age b.txt
ver a.txt.age
encdir Documentos/
trancado: a.txt.age
trancado: b.txt.age
aberto: a.txt
ignorado (não é .age): b.txt
a
trancado: Documentos.tar.gz.age
O ${f%.age} é expansão do bash que remove o sufixo .age do nome. A checagem em dec evita sobrescrever um arquivo por engano quando você passa o nome errado. Como enc usa o recipients.txt, tudo o que você tranca já sai criptografado também para a chave de recuperação, se ela estiver lá.
Resumo
| Quero... | Comando |
|---|---|
| Gerar chave | age-keygen -o key.txt |
| Ver minha chave pública | age-keygen -y key.txt |
| Criptografar para mim | age -R recipients.txt -o x.age x |
| Criptografar com senha | age -p -o x.age x |
| Abrir | age -d -i key.txt -o x x.age |
| Só ler, sem gravar | age -d -i key.txt x.age |
| Pasta inteira | tar czf - pasta | age -R recipients.txt > pasta.tar.gz.age |
| Restaurar pasta | age -d -i key.txt pasta.tar.gz.age | tar xzf - |
| Texto para colar | age -a -r age1... |
| Chave com senha | age-keygen | age -p -o key.age |
| Pós-quântico | age-keygen -pq -o key-pq.txt |
| Inspecionar | age-inspect x.age |
| Assinar | ssh-keygen -Y sign -f ~/.ssh/id_ed25519 -n file x.age |
| Conferir uma assinatura | ssh-keygen -Y verify -f allowed_signers -I email -n file -s x.age.sig < x.age |
| Recriptografar depois de trocar chaves | age -d -i key.txt x.age | age -R recipients.txt -o x.age.new |
Antes de confiar seus dados ao age, confira:
- Chave em
~/.config/age/com permissão600, em disco criptografado -
recipients.txtcom a chave do dia a dia e uma chave de recuperação guardada offline - Backup da chave em papel ou pendrive, fora de casa (seção 14)
- Teste de restauração feito usando só o backup (seção 14)
- Pipes no lugar de arquivos intermediários em texto puro
- Originais apagados depois de criptografar, em disco criptografado (seção 14)
- Assinaturas nos arquivos cuja autoria importa
- Um plano para chave vazada: recriptografar e trocar os segredos (seção 12)