O que você vai aprender#
- o que é assinado e atestado em uma versão;
- os comandos que verificam o arquivo compactado e a imagem;
- o que uma falha significa.
A ideia#
Toda versão é construída por um único workflow, release.yml, no GitHub. Ele assina o checksums.txt com o cosign (sem chave, pelo Sigstore), anexa uma atestação de proveniência da construção e assina e atesta os digests da imagem de contêiner nos dois registros. Você verifica que o arquivo que tem em mãos é o que aquele workflow construiu a partir de uma tag, sem confiar no download.
Instale o cosign, a CLI do GitHub gh e, para a imagem, o docker.
Início rápido#
Defina a versão, depois baixe e verifique o arquivo compactado da sua plataforma:
VERSION=vX.Y.Z
V="${VERSION#v}"
REPO=AlexGalhardo/vukem-video
ARCHIVE="vukem-video_${V}_linux_amd64.tar.gz"
IDENTITY="^https://github[.]com/$REPO/[.]github/workflows/release[.]yml@refs/tags/v"
ISSUER=https://token.actions.githubusercontent.com
gh release download "$VERSION" -R "$REPO" -p checksums.txt -p checksums.txt.sigstore.json \
-p "$ARCHIVE" -p "$ARCHIVE.sbom.json"
cosign verify-blob checksums.txt --bundle checksums.txt.sigstore.json \
--certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER"
sha256sum --ignore-missing -c checksums.txt
gh attestation verify "$ARCHIVE" -R "$REPO"No macOS, use shasum -a 256 -c para a conferência dos checksums. A versão também anexa o pacote de proveniência, vukem-video.intoto.jsonl, e uma lista de materiais de software (SBOM) para cada arquivo compactado.
Verifique a imagem de contêiner nos dois registros. Os dois digests impressos precisam ser iguais, porque uma única construção é enviada aos dois:
for image in ghcr.io/alexgalhardo/vukem-video alexgalhardo/vukem-video; do
digest="$(docker buildx imagetools inspect "$image:$V" --format "{{.Manifest.Digest}}")"
cosign verify "$image@$digest" \
--certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER"
echo "$image $digest"
done
docker run --rm "ghcr.io/alexgalhardo/vukem-video:$V" versionO último comando imprime vukem-video vX.Y.Z. Os instaladores de Windows e macOS não são assinados com um certificado pago de assinatura de código; o checksums.txt assinado é como você os verifica.
Os instaladores do BETA não são assinados#
O BETA não tem assinatura de código paga: não há Apple Developer ID nem notarização, e não há certificado de assinatura de código do Windows. Isso vale para os instaladores do servidor local e para os instaladores do aplicativo desktop (vukem-video-desktop_X.Y.Z_windows_amd64_setup.exe, ..._darwin_arm64.dmg, ..._darwin_amd64.dmg e ..._linux_amd64.deb). A assinatura paga será decidida de novo antes da 1.0. Até lá, a prova de que um arquivo é o que o projeto construiu é a assinatura do checksums.txt e a atestação do arquivo, e o seu sistema avisa antes de executá-lo:
- O SmartScreen do Windows mostra "O Windows protegeu seu PC". Escolha Mais informações e depois Executar assim mesmo. O publicador aparece como desconhecido porque não há certificado.
- O Gatekeeper do macOS diz que o app ou o pacote não pode ser aberto porque a Apple não consegue verificá-lo. Clique com o botão direito (ou com Control), escolha Abrir e depois Abrir de novo; ou execute
xattr -d com.apple.quarantine <caminho do arquivo ou do app>.
Um aviso não é um veredito, e a ausência de aviso não é prova. Verifique o arquivo antes; as conferências abaixo não dependem do que o sistema diz.
Baixe o instalador e execute, com a versão e o nome do arquivo do seu sistema:
FILE="vukem-video-desktop_${V}_windows_amd64_setup.exe"
gh release download "$VERSION" -R "$REPO" -p "$FILE"
bash scripts/desktop-verify.sh "$VERSION" "$FILE"O scripts/desktop-verify.sh está no repositório (clone-o, ou baixe-o a partir da tag). Ele baixa o checksums.txt e a assinatura dele, verifica a assinatura com o cosign, confere que o SHA-256 do seu arquivo é igual à linha dele no checksums.txt e executa gh attestation verify no arquivo. Ele não usa codesign nem signtool, porque não há assinatura de código para conferir. Sem o script, faça o mesmo à mão com os comandos do início rápido, usando $FILE onde eles usam $ARCHIVE.
O feed de atualização#
O aplicativo desktop pode procurar uma versão mais nova, mas só quando você ativa: a configuração update.check vem desligada e, desligada, o aplicativo não abre nenhuma conexão. Ele lê um único arquivo assinado, feed.json, do site do projeto no GitHub Pages (<site>/updates/feed.json), e os instaladores que ele lista vêm do mesmo endereço. O feed e cada instalador são assinados com uma chave Ed25519 cuja metade pública está embutida no aplicativo; um arquivo que não bate com a assinatura ou com o digest é recusado. A versão também anexa o feed.json, e bash scripts/release-verify.sh vX.Y.Z confere que cada digest dele é igual ao do checksums.txt.
Erros comuns#
- Pular o
cosign verify-blobe executar apenas osha256sum: um arquivo de checksums que você não verificou não prova nada. - Mudar a regexp de identidade para aceitar qualquer workflow. Mantenha-a exata: a identidade é a prova de quem construiu o arquivo.
- Uma execução de recuperação assinada a partir de um branch em vez de uma tag tem a identidade
@refs/heads/<branch>; a regexp acima a rejeita de propósito. Use a próxima versão com tag.