Blog do Fabrício

Entendendo a vulnerabilidade de segurança do JWT

Sat, 21 May 2016 21:00:00 -0300

Table of Contents

Introdução
Conceitos Iniciais
Análise das Vulnerabilidades

Introdução

Em março de 2015 Tim McLean publicou em um blog que após analisar várias implementações do JSON Web Token (JWT) descobriu vulnerabilidades que permitiam que a etapa de verificação pudesse ser burlada.

E nesse artigo vamos entender exatamente como essas vulnerabilidades podem ser exploradas, tanto para auditar uma biblioteca existente quanto para evitar erros ao utilizar quaisquer bibliotecas existentes.

Conceitos Iniciais

Antes de analisarmos a vulnerabilidade, irei revisar os conceitos básicos necessários para entender os problemas.

Hash (Checksum)

Os algoritmos de soma hash são algoritmos que retornam um resultado de comprimento fixo independente do tamanho da entrada, e esse resultado é quase exclusivo para os dados de entrada. Os algoritmos mais conhecidos são: MD5, SHA-1 e SHA-2.

Como os resultados retornados por tais algoritmos são apenas apenas uma soma dos dados de entrada não há como inferir os dados de entrada através do resultado. Esses resultados são muito úteis para verificação de integridade, pois se espera que qualquer alteração nos dados de entrada os resultados sejam diferentes.

Tabela 1. Exemplos de Hashes
Mensagem	Hash
Oi	lxFc
Olá, como vai?	R+bU
Bem-vindo	IB84

Criptografia Simétrica

Os algoritmos de criptografia simétrica utilizam apenas uma chave para criptografar um dado qualquer, que pode ser uma mensagem, um arquivo, um pacote de dados etc. Os algoritmos mais conhecidos são: DES, TripleDES, AES, RC4 e RC5.

A principal vantagem de algoritmos de criptografia simétrica é que são muito rápidos, o que se traduz em baixa latência e pouco uso de CPU. Já a principal desvantagem é que por utilizar a mesma chave quanto para criptografar quanto para descriptografar, essa chave precisa ser compartilhada com o receptor.

Figura 1. Envio de Dados com Criptografia Simétrica

Figura 2. Recebimento de Dados com Criptografia Simétrica

Criptografia Assimétrica

Os algoritmos de criptografia assimétrica utilizam duas chaves complementares para criptografar e descriptografar. Uma das chaves é guardada em segredo e não é revelada ninguém e outra pode ser publicada a qualquer um livremente. Os algoritmos mais conhecidos são: RSA e ECDSA.

Um grande diferencial dessa classe de algoritmos é que um dado criptografado com uma chave pode apenas ser descriptografado com outra e vice-versa. Essa característica permite que estranhos mantenham uma comunicação segura mesmo que o meio de comunicação não o seja, e além disso, não há a necessidade de um meio seguro para que a troca de chave ocorra.

Algoritmos de criptografia assimétrica são muito custosos em termos de CPU, por esse motivo as comunicações, normalmente, os utilizam como meio de troca de chave simétrica. Diminuindo, assim o tempo e recursos da CPU.

Figura 3. Envio de Dados com Criptografia Assimétrica

Figura 4. Recebimento de Dados com Criptografia Assimétrica

Assinaturas

Há também outro uso muito comum para a criptografia assimétrica, além de ser utilizada para garantir privacidade, também é utilizada em assinaturas para garantir identidade.

Quando Anderson quer enviar um dado sigiloso para Roberta, ele utiliza a chave pública de Roberta para garantir que apenas Roberta consiga descriptografar o dado enviado. Entretanto, quando Roberto quer confirmar que um dado foi gerado por ele, o mesmo pode utilizar a chave privada para criptografar o dado e assim qualquer um com sua chave pública pode confirmar a identidade descriptografando o dado.

Apesar de eficaz, criptografar todo o dado para garantir identidade não é muito usual. O problema é que dependendo da aplicação é um gasto de recursos desnecessário.

Quando queremos apenas confirmar identidade o dado não é privado, pois a chave pública está disponível a qualquer um, o que permite que os mesmos acessem os dados. Assim, uma maneira eficiente de alcançar o mesmo objetivo, com quase a mesma eficiência, é gerar uma soma Hash (Checksum) do dado e criptografar esse resultado. Então a confirmação de identidade passaria a ser da seguinte maneira: gerar uma soma Hash do dado recebido, descriptografar a assinatura recebida e por fim comparar se os resultados são iguais.

Figura 5. Assinatura de Dados com Criptografia Assimétrica

Por fim existe a possibilidade combinar a garantia de identidade e a garantia de de privacidade ao mesmo tempo. Para tal basta realizar todo o processo de assinatura e, antes de enviar os dados, criptografar tudo utilizando a chave pública do destinatário.

JSON Web Token (JWT)

O padrão JSON Web Token (RFC 7519) define uma maneira segura, compacta e independente de transmitir informações usando como base objetos JSON. A confiabilidade das informações são asseguradas via assinaturas, conforme a técnica que abordamos na seção anterior.

O padrão JWT permite as informações sejam assinadas tanto com criptografia simétrica (com o algoritmo HMAC) quanto com criptografia assimétrica (com os algoritmos RSA e ECDSA).

JWTs são compactos de uma maneira que permite que os mesmos sejam transmitidos junto ao cabeçalho de uma requisição HTTP ou até na URL. Adicionalmente, JWTs são independentes pois os mesmos podem carregar toda informação necessária sem que seja necessário uma consulta no banco de dados.

Os JWTs são muito utilizados no processo de autenticação permitindo que o processo de autorização de acesso a recursos seja mais rápido e escalável. Mais rápido porque por ser independente retira da equação o tempo de latência de acesso ao banco de dados ou outro mecanismo de cache. E mais escalável pois permite que serviços totalmente independentes compartilhem a mesma autenticação sem necessitar de comunicação entre os mesmos.

Estrutura

A estrutura de um JWT contém três partes separadas por pontos (.), que são: o cabeçalho, informação útil e a assinatura.

Cabeçalho

A implementação mais básica do cabeçalho contém dois campos: um que define o tipo de token e outro que define o algoritmo utilizado. O tipo de token sempre é JWT e o algoritmo é uma combinação de soma Hash com algoritmo de criptografia.

Exemplo de cabeçalho JWT (RSA + SHA-384)

{
    "alg": "RS384",
    "typ": "JWT"
}

Esse cabeçalho é codificado utilizando o algoritmo Base64Url, antes de compor um JWT.

Informação Útil (Payload)

Essa parte do JWT contém as afirmações (claims, em inglês). As afirmações são confirmações sobre uma entidade, normalmente um usuário, e alguns dados adicionais.

Há um conjunto de afirmações pré-definidas pelo padrão que são reservadas, como iss (emissor), exp (data de expiração), sub (entidade), aud (destinatário) etc.

Exemplo de payload JWT

{
    "iss": "accounts.google.com",
    "sub": "110169484474386276334",
    "aud": "1008719970978-hb24n2dstb40o45d4feuo2ukqmcc6381.apps.googleusercontent.com",
    "iat": "1433978353",
    "exp": "1433981953",
    "email": "testuser@gmail.com"
}

A informação útil também é codificada utilizando o algoritmo Base64Url, antes de compor a segunda parte do JWT.

Assinatura

A assinatura é criada a partir das seguintes informações: cabeçalho codificado com Base64Url, a informação útil codificada com Base64Url, uma chave para criptografia e um algoritmo de soma Hash e criptografia.

Exemplo do algoritmo de assinatura com RSA PKCS#1 e SHA-256

// Algoritmo RS256
var hash = sha256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload));
var signature = rsaPKCS1(hash, key);

Da mesma maneira que nas partes anteriores a assinatura também é codificada utilizando o algoritmo Base64Url, antes de compor o JWT.

Conclusão

O resultado final são três partes codificadas com Base64Url e separadas por pontos. Como demonstrado no exemplo logo abaixo.

Exemplo do resultado final de um JWT

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ

O resultado do exemplo acima foi calculado utilizando os seguintes dados:

Cabeçalho

{
    "alg": "HS256",
    "typ": "JWT"
}

Informação Útil

{
    "sub": "1234567890",
    "name": "John Doe",
    "admin": true
}

Assinatura

hmacSha256(
    base64UrlEncode(header) + "." +
    base64UrlEncode(payload),
    "secret");

Você pode realizar testes e colocar esses conceitos em prática no site jwt.io. Lá você pode decodificar, verificar e gerar JWTs, tudo online no navegador.

Análise das Vulnerabilidades

Finalmente irei abordar as vulnerabilidades encontradas nas implementações do JSON Web Token.

Algoritmo Nulo

Quando um token precisa ser validado o primeiro passo é determinar o algoritmo utilizado pelo mesmo, como é indicado pelo campo alg do cabeçalho.

Isso significa que entramos num dilema, o próprio token indica qual algoritmo deve ser utilizado para validar a si próprio. E isso pode ser desastroso, dependendo da implementação.

No padrão JWT há a opção de algoritmo identificado como none indicando um algoritmo nulo, o que significa que não foi utilizado nenhum algoritmo para gerar uma assinatura para o token.

Exemplo de cabeçalho JWT com algoritmo nulo

{
    "alg": "none",
    "typ": "JWT"
}

O problema é que algumas bibliotecas aceitam tokens com algoritmo nulo como se tivessem uma assinatura válida. O que abre uma vulnerabilidade enorme, permitindo que qualquer atacante possa criar um token válido.

A maioria das implementações resolveram esse problema rejeitando algoritmos nulos quando uma chave de criptografia é passada como parâmetro.

Criptografia Simétrica vs Assimétrica

Aceitar algoritmos nulos não é o real problema, o problema é aceitar que atacantes controlem o algoritmo de criptografia.

Se a biblioteca aceita que um token seja validado sem especificar o algoritmo esperado, outra vulnerabilidade grave é aberta. Exatamente no caso esperarmos que o token use uma criptografia assimétrica e o atacante utiliza uma criptografia simétrica.

Figura 6. Lógica de validação de assinatura JWT

O problema com essa lógica é que o atacante pode obter a chave pública e assinar um token qualquer utilizando um algoritmo simétrico (HMAC) e indicar no cabeçalho o mesmo algoritmo. Assim quando um recurso protegido utilizar o mesmo algoritmo e a mesma chave o token será considerado válido, pois a assinatura gerada será igual a assinatura do token.

Lembrando que nesse caso como os tokens válidos estão sendo assinados com a chave privada os mesmos devem ser validados com a chave pública. Por isso o atacante terá sucesso, pois tem a certeza que o token está sendo validado com a chave pública.

Recomendações

Desenvolvedores deveriam exigir que o algoritmo utilizado para validação seja passado como parâmetro. Assim garante-se que será utilizado o algoritmo apropriado para a chave fornecida.

Caso seja necessária a utilização de mais de um algoritmo com chaves diferentes, a solução é atribuir um identificador para cada chave e indicá-la no campo kid do cabeçalho (key identifier, em inglês). Assim será possível inferir o algoritmo de acordo com a chave utilizada. Dessa maneira o campo alg não terá utilidade alguma além de, talvez, validar se ele indica o algoritmo esperado.

Ao utilizar uma implementação do padrão JWT, você deve auditar de maneira consistente se ela rejeita efetivamente algoritmos além do esperado. Assim a possibilidade de sucesso em ataques dessa natureza estarão quase nulos.

Configurações de /proc/sys/net/ipv4/route

Mon, 06 Sep 2010 22:46:08 -0300

Vou falar um pouco das configurações de roteamento disponíveis em /proc/sys/net/ipv4/route.

error_burst: Define, em interrupções de timer, o tempo máximo contabilizado para exibir uma mensagem. O valor predefinido corresponde a 5 segundos.
error_cost: Define, em interrupções de timer, o tempo mínimo para exibir uma mensagem. O valor predefinido corresponde a 1 segundo.

Os valores predefinidos de error_burst e error_cost limitam a uma mensagem a cada 5 segundos.
flush: Escrever nesse arquivo faz com que o cache de roteamento seja descartado.
gc_elasticity: É usado para definir o tamanho médio da lista de rotas, quando excedido a coleta de lixo na tabela de rotas se torna muito agressiva ^[1].
gc_interval: Define, em segundos, o intervalo entre coletas lixo na tabela de rotas. Existe uma recomendação para que a coleta não seja muito frequente pois é uma operação muito pesada ^[2].
gc_min_interval: Obsoleto, usar gc_min_interval_ms ^[3].
gc_min_interval_ms: Define, em milissegundos, o intervalo mínimo entre coletas ^[4]. Predefinido em 500 milissegundos.
gc_thresh: Define a quantidade mínima de rotas para que rotas comecem a ser descartadas na coleta de rotas ^[5].
gc_timeout: Define, em segundos, o tempo máximo que uma rota é mantida. A rota é descartada mesmo se está em uso ^[6]. Predefinido em 300 segundos.
max_size: Define o número máximo de rotas a serem mantidas. As rotas mais antigas serão descartadas quando o número máximo é alcançado.
min_adv_mss: Define, em bytes, a quantidade mínima de dados pode ser enviada em um segmento ^[7]. Predefinido em 256 bytes.
min_pmtu: Define, em bytes, o valor mínimo de PMTU permitido. Se o valor descoberto for menor então o valor mínimo definido aqui prevalece ^[8]. Predefinido em 552 bytes.
mtu_expires: Define, em segundos, o tempo que o PMTU de uma rota é mantido em cache ^[9]. Predefinido em 600 segundos.
redirect_load: Define um tempo mínimo entre tentativas de redirecionamentos ICMP, por rota ^[10].
redirect_number: Define o número máximo de redirecionamentos ICMP ignorados, por rota ^[11] ^[12].
redirect_silence: Define, em interrupções de timer, o tempo máximo de espera por um redirecionamento ICMP. Após esse tempo é enviada um novo redirecionamento, mesmo que o mesmo tenha sido ignorado por causa de redirect_load ou redirect_number. Predefinido em 20,48 segundos.
secret_interval: Define, em segundos, o intervalo entre descarregamento de cache. Predefinido em 600 segundos.

As informações encontradas aqui podem estar incorretas, pois se baseiam em minhas conclusões.

Referências

Documentação do sistema de arquivos /proc: http://www.linuxinsight.com/proc_sys_net_ipv4_route.html
Configurações do kernel obscuras: http://lartc.org/howto/lartc.kernel.obscure.html
Determinando a quantidade de interrupções de timer: http://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=1005802
PMTU: http://www.netheaven.com/pmtu.html

1. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L1178

2. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L950

3. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L3109

4. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L957

5. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L967

6. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L842

7. http://www.tcpipguide.com/free/t_TCPMaximumSegmentSizeMSSandRelationshiptoIPDatagra.htm

8. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L1701

9. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L1706

10. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L1557

11. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L1549

12. http://lxr.free-electrons.com/source/net/ipv4/route.c?v=2.6.35#L1512

Dividir um PDF com página dupla em dois

Sat, 17 Jul 2010 23:47:27 -0300

Abaixo publico um código Perl que divide verticalmente cada página em duas páginas.

Um caminho para o arquivo PDF deve ser fornecido como argumento e o arquivo dividido será criado no mesmo local.

Instale o PDF-API2 (pacote libpdf-api2-perl no Debian/Ubuntu ou perl-PDF-API2 no RHEL/CentOS/Fedora).

split_pdf.pl

#!/usr/bin/env perl
use strict; use warnings;
use PDF::API2;

my $filename = shift || 'test.pdf';
my $oldpdf = PDF::API2->open($filename);
my $newpdf = PDF::API2->new;

for my $page_nb (1..$oldpdf->pages) {
  my ($page, @cropdata);

  $page = $newpdf->importpage($oldpdf, $page_nb);
  @cropdata = $page->get_mediabox;
  $cropdata[2] /= 2;
  $page->cropbox(@cropdata);
  $page->trimbox(@cropdata);
  $page->mediabox(@cropdata);

  $page = $newpdf->importpage($oldpdf, $page_nb);
  @cropdata = $page->get_mediabox;
  $cropdata[0] = $cropdata[2] / 2;
  $page->cropbox(@cropdata);
  $page->trimbox(@cropdata);
  $page->mediabox(@cropdata);
}

(my $newfilename = $filename) =~ s/(.*)\.(\w+)$/$1.clean.$2/;
$newpdf->saveas($newfilename);

___END___

Esse post foi baseado no post em http://snipplr.com/view/18924/split-crop-double-page-pdfs-in-two/

Como criar um repositório Git remoto usando o SSH

Sun, 15 Nov 2009 00:59:25 -0200

Abordarei a criação de um repositório Git remoto usando o SSH num ambiente Linux.

Não incluirei detalhes da configuração do SSH.

É necessário que os seguintes pacotes estejam instalados: git, openssh-server e openssh-client.

Primeiro configure o SSH editando o arquivo /etc/ssh/sshd_config.

Eu recomendo algumas configurações ^[1]:

sshd_config

Protocol 2    # Permite apenas a versão 2 do protocolo (mais seguro)
PermitRootLogin no    # Não permite login como root
PasswordAuthentication no    # Não permite login por senha

Não esqueça de iniciar ou reiniciar o servidor SSH.

Agora é necessário criar um usuário para acesso ao Git através do SSH.

Eu recomendo que o nome do usuário seja git e que seja criado com o seguinte comando ^[2]:

useradd -r -m --shell /usr/bin/git-shell git

Definindo o shell do usuário para /usr/bin/git-shell o acesso do usuário será restrito aos comandos do Git ^[3].

O diretório pessoal do usuário git será criado em /home/git.

Se você não tem uma chave para o SSH, crie-a com o comando ssh-keygen (usando seu usuário).

Será criada uma chave pública e privada em ~/.ssh, a chave pública tem o sufixo .pub (nunca compartilhe sua chave privada).

Agora é necessário adicionar sua chave pública a lista de chaves autorizadas do usuário git, para isso faça o seguinte:

mkdir /home/git/.ssh
cat /home/seu_usuario/.ssh/id_rsa.pub >> /home/git/.ssh/authorized_keys

Supondo que o nome de sua chave pública seja id_rsa.pub.

Agora será necessário criar um repositório no diretório pessoal do usuário git.

Para criar um repositório para o projeto ProjetoTeste, faça o seguinte:

mkdir /home/git/ProjetoTeste cd /home/git/ProjetoTeste git init --bare

Agora é necessário garantir que tudo pertença ao usuário git, faça o seguinte:

cd /home/git chown -R git.git . (1)

1	Não esqueça do ponto no final

Isso é tudo.

Para clonar o repositório use o seguinte comando:

git clone git@ip_do_servidor:ProjetoTeste

1. http://linux.die.net/man/5/sshd_config ou man 5 sshd_config.

2. http://linux.die.net/man/8/useradd ou man 8 useradd.

3. http://linux.die.net/man/1/git-shell ou man 1 git-shell.

Internacionalização (I18n) com Autotools

Sun, 14 Jun 2009 18:07:52 -0300

Explicarei como internacionalizar, ou seja, tornar um programa traduzível.

Tomarei como exemplo o projeto hello-world do post anterior.

Você pode baixar o pacote final do projeto do post anterior em http://dl.getdropbox.com/u/1671797/Blog/hello-world-0.2.0.tar.gz.

Será necessário as seguintes ferramentas: intltool e gettext.

Adicione o seguinte código no arquivo configure.ac:

configure.ac

# Checks for libraries.
PKG_CHECK_MODULES([DEPS],[glib-2.0]) (1)
AC_SUBST(DEPS_CFLAGS) (2)
AC_SUBST(DEPS_LIBS) (3)

# -------------------------------------------------
# Internationalization
# -------------------------------------------------
GETTEXT_PACKAGE=hello-world (4)
AC_SUBST(GETTEXT_PACKAGE) (5)
AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE], ["$GETTEXT_PACKAGE"],
 [the gettext translation domain]) (6)

AM_GLIB_GNU_GETTEXT (7)
GLIB_DEFINE_LOCALEDIR(HELLO_WORLD_LOCALEDIR) (8)

IT_PROG_INTLTOOL([0.35.1]) (9)

# -------------------------------------------------
# Check OS-specific platform

1	Procura pela biblioteca glib-2.0 e define as variáveis DEPS_CFLAGS e DEPS_LIBS (detalhes abaixo). Caso a biblioteca não seja encontrada é retornado um erro.
2	Faz com que @DEPS_CFLAGS@ ou $(DEPS_CFLAGS), nos arquivos de saída do autoconf, seja substituído pelo valor da variável.
3	O mesmo que o comando acima, mas com a variável DEPS_LIBS.
4	Está sendo definida uma variável local.
5	O mesmo que as macros AC_SUBST acima, mas com a variável GETTEXT_PACKAGE.
6	Igual a macro AC_DEFINE com o diferencial de expandir expressões de shell (ver "Definindo símbolos"). Define, no arquivo config.h, o símbolo GETTEXT_PACKAGE com o valor da variável GETTEXT_PACKAGE.
7	Faz verificações se o gettext pode ser usado, define o símbolo HAVE_GETTEXT no arquivo config.h entre outros.
8	Define o nome do símbolo que conterá o caminho do diretório de localização. É o caminho do diretório de onde os catálogos de mensagens de cada língua será instalado.
9	Faz verificações se o intltool pode ser usado e define a versão mínima necessária.

Ainda no arquivo configure.ac adicione o arquivo "po/Makefile.in" em AC_CONFIG_FILES. Desta maneira o arquivo Makefile que será criado no diretório po fará parte da compilação.

configure.ac

AC_CONFIG_FILES([Makefile
    src/Makefile
    po/Makefile.in])

Para que se possa fazer o uso da biblioteca glib-2.0 é necessário indicar ao compilador onde achar os arquivos de cabeçalho e os objetos de ligação. Para isso é necessário modificar o arquivo Makefile.am como abaixo:

Makefile.am

bin_PROGRAMS = hello-world

hello_world_SOURCES = main.cpp
if OS_WIN32
hello_world_SOURCES += windowsdef.h
endif

hello_world_LDADD = $(DEPS_LIBS) (1)
hello_world_CXXFLAGS = $(DEPS_CFLAGS) (2)

1	DEPS_LIBS é a variável com os caminhos para os objetos de ligação. Esses objetos têm a listagem e endereçamento de cada função.
2	DEPS_CFLAGS é a variável com os caminhos para os arquivos de cabeçalho.

Crie o diretório po no diretório raíz do projeto, este diretório conterá os catálogos de cada língua.

Crie um arquivo vazio com o nome LINGUAS, neste arquivo será listado os códigos de cada idioma com suporte.

Crie um arquivo vazio com o nome POTFILES.in, neste arquivo será listado todos os arquivos com mensagens traduzíveis.

No arquivo Makefile.am do diretório raíz do projeto adicione o diretório po em SUBDIRS.

Makefile.am

SUBDIRS = src po

É necessário adicionar os scripts de internacionalização ao pacote de distribuição, para isso adicione o código abaixo ao arquivo Makefile.am do diretório raíz.

Makefile.am

SUBDIRS = src po

INTLTOOL_FILES = \ (1)
 intltool-extract.in \
 intltool-merge.in \
 intltool-update.in

EXTRA_DIST = \ (2)
 $(INTLTOOL_FILES)

DISTCLEANFILES = \ (3)
 intltool-extract \
 intltool-merge \
 intltool-update \
 po/.intltool-merge-cache

1	INTLTOOL_FILES é uma variável com a lista de scripts usados pelo intltool.
2	EXTRA_DIST define arquivos adicionais que serão adicionados ao pacote de distribuição.
3	DISTCLEANFILES define os arquivos adicionais que serão removidos pelo comando "make distclean".

Para atualizar os scripts com as mudanças execute o comando "autoreconf".

Para preparar o projeto para o intltool, execute o comando "intltoolize" no diretório raíz do projeto.

Agora é necessário inicializar o libintl e marcar as strings como traduzíveis. Para isso modifique o arquivo main.cpp como a seguir:

main.cpp

#ifdef HAVE_CONFIG_H
#include <config.h> (1)
#endif

#ifdef WINNT
#include "windowsdef.h"
#endif

#include <iostream>
#include <glib/gi18n.h> (2)

int main()
{
  // Gettext initialization
  setlocale(LC_ALL, ""); (3)
  bindtextdomain(GETTEXT_PACKAGE, HELLO_WORLD_LOCALEDIR); (4)
  bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8"); (5)
  textdomain(GETTEXT_PACKAGE); (6)

  std::cout << _("Hello World!") << std::endl; (7)
  return 0;
}

1	Para usar os símbolos GETTEXT_PACKAGE e HELLO_WORLD_LOCALEDIR é necessário incluir o cabeçalho config.h.
2	O cabeçalho gi18n.h inclui o cabeçalho libintl.h, que contém as funções de internacionalização, e define símbolos comumente usados na internacionalização.
3	A função setlocale() define a localização atual que será usada pelo gettext.
4	A função bindtextdomain() define o caminho do catálogo de GETTEXT_PACKAGE para HELLO_WORLD_LOCALEDIR.
5	A função bind_textdomain_codeset() define a codificação das mensagens do catálogo de GETTEXT_PACKAGE para UTF-8.
6	A função textdomain() define o catálogo de mensagens padrão para GETTEXT_PACKAGE.
7	A função _() é um símbolo que foi definido pelo gi18n.h que é um apelido para a função gettext() do cabeçalho libintl.h.

Agora o projeto está pronto para ser traduzido (localizado).

O pacote final pode ser acessado neste link: http://dl.getdropbox.com/u/1671797/Blog/hello-world-0.3.0.tar.gz.

Referências

Definindo símbolos: http://www.gnu.org/software/hello/manual/autoconf/Defining-Symbols.html

Internacionalização: http://www.gtkmm.org/docs/gtkmm-2.4/docs/tutorial/html/chapter-internationalization.html

pkg-config: http://pkg-config.freedesktop.org/

setlocale: http://www.opengroup.org/onlinepubs/009695399/functions/setlocale.html

Identificando o ambiente de destino com Autotools

Sun, 14 Jun 2009 18:07:52 -0300

Explicarei aqui como identificar qual o ambiente de destino de compilação, ou seja, o ambiente no qual será executado o binário.

Para isso tomarei como exemplo o projeto hello-world do post anterior.

Você pode baixar o pacote final do projeto do post anterior em http://dl.getdropbox.com/u/1671797/Blog/hello-world-0.1.0.tar.gz.

No arquivo configure.ac, é necessário adicionar a seguinte macro:

configure.ac

AM_INIT_AUTOMAKE([1.9 -Wall -Werror])

# Check build environment
AC_CANONICAL_HOST

# Checks for programs.

Com essa macro serão criados os arquivos de script config.guess e config.sub que serão usados para identificar o ambiente de destino.

Serão definidas quatro variáveis de ambiente, que são: host, host_cpu, host_vendor, host_os. Com essas variáveis é possível condicionar a compilação para cada ambiente.

Caso o ambiente de destino seja o MinGW de 32 bits para PC, normalmente, a variável host teria o valor i686-pc-mingw32 e como consequência as variáveis host_cpu, host_vendor e host_os teriam os valores i686, pc e mingw32 respectivamente. Assim podemos dizer que "host=$host_cpu-$host_vendor-$host_os".

Criarei uma verificação para definir a variável OS_WIN32 caso a variável host_os tenha a palavra "mingw". Para isso adicionarei o seguinte script no arquivo configure.ac:

configure.ac

# -------------------------------------------------
# Check OS-specific platform
# -------------------------------------------------
AC_MSG_CHECKING([for native Win32])
case "$host_os" in
  *mingw*)
    iswin32=yes
  ;;
  *)
    iswin32=no
  ;;
esac
AC_MSG_RESULT([$iswin32])

AM_CONDITIONAL(OS_WIN32, [test "$iswin32" = "yes"])

A macro AC_MSG_CHECKING faz imprimir na tela a mensagem "checking for native Win32…" indicando que está sendo feita a verificação por uma característica específica.

Em seguida é verificada a variável de ambiente pela palavra "mingw", caso encontre a variável local iswin32 será definida para o valor "yes", senão para o valor "no" (Leia sobre Bash).

A macro AC_MSG_RESULT imprime na tela o resultado da última macro AC_MSG_CHECKING. Imprime "checking for native Win32… yes", caso a variável iswin32 tenha o valor "yes".

A macro AM_CONDITIONAL de maneira condicional define ou não a variável OS_WIN32 a qual será compartilhada a todos Makefiles. Caso a variável local iswin32 tenha o valor "yes" a variável OS_WIN32 será definida.

Adicionarei o seguinte conteúdo no arquivo Makefile.am:

Makefile.am

hello_world_SOURCES = main.cpp
if OS_WIN32
hello_world_SOURCES += windowsdef.h
endif

Assim o arquivo windowsdef.h só será compilado caso esteja definida a variável OS_WIN32.

Criarei o arquivo windowsdef.h com o seguinte conteúdo:

windowsdef.h

#ifndef _WINDOWSDEF_H
#define _WINDOWSDEF_H

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#ifndef WINVER
// Windows Server 2003 with SP1, Windows XP with SP2
// See http://msdn.microsoft.com/en-us/library/aa383745.aspx
#define WINVER 0x0502
#endif /* WINVER */

#include <windows.h>

#endif    /* _WINDOWSDEF_H */

Definindo a variável WINVER para o valor 0x0502 estaremos limitando o executável ao Windows XP SP2 ou Windows Server 2003 SP1 no mínimo.

Adicionarei o seguinte conteúdo ao arquivo main.cpp:

main.cpp

#ifdef WINNT
#include "windowsdef.h"
#endif

#include <iostream>

O compilador só referenciará o arquivo windowsdef.h caso a variável WINNT esteja definida. A variável WINNT é definida automaticamente pelo compilador caso o mesmo esteja sendo executado em um ambiente do Windows NT.

Para consultar as variáveis automaticamente definidas pelo seu compilador execute o seguinte comando "gcc -E -dM - < /dev/null | sort", sendo que "| sort" é para ordenar a saída em ordem alfabética.

Com essas instruções já se tem o básico para construir um programa multi-plataforma.

O pacote final pode ser acessado neste link: http://dl.getdropbox.com/u/1671797/Blog/hello-world-0.2.0.tar.gz

Referências

Hello World com Autotools

Sun, 24 May 2009 17:23:36 -0300

Para quem não conhece o Autotools, as ferramentas do mesmo têm o principal objetivo de fazer programas portáveis, possibilitando assim que o programa possa ser compilado em qualquer ambiente.

Vou explicar como fazer um programa que exibe “Hello World!” no console configurado com Autotools. Não vou me ater a detalhes, ficando a cargo do leitor pesquisar detalhadamente sobre as ferramentas.

Para continuar você precisará ter instalado as seguintes ferramentas: make, gcc-c++, autoconf e automake. Para Windows você precisará também do MinGW e do MSYS.

Vamos ao projeto:

Primeiramente crie uma pasta para o projeto (hello-world por exemplo).
Agora crie a pasta src (o nome é sua escolha), ela irá conter o código fonte do projeto.

Crie o arquivo main.cpp dentro da pasta src, como o código abaixo.

main.cpp

#include <iostream>

int main()
{
    std::cout << "Hello World!" << std::endl;
    return 0;
}

Dentro da pasta raíz do projeto crie o arquivo Makefile.am, com o conteúdo abaixo.
Makefile.am
```
SUBDIRS = src
```
Os arquivos Makefile.am têm instruções de compilação, mais especificamente, instruções para o comando make.

No caso deste arquivo, ele indica que deve ser pesquisado o diretório src.
Agora crie outro arquivo Makefile.am no diretório src, com o seguinte conteúdo:
Makefile.am
```
bin_PROGRAMS = hello-world

hello_world_SOURCES = main.cpp
```
A primeira linha indica quais são os nomes dos programa executáveis.

A segunda linha indica quais são os arquivos fontes do programa hello-world. Observe que todos os caracteres não alfabéticos devem der substituídos por "", como em _hello_world.
Agora precisamos criar o arquivo configure.ac (no diretório raíz do projeto, daqui em diante iremos trabalhar apenas no diretório raíz), que irá conter as configurações do projeto, como nome, versão e dependências do projeto entre outros.

Para criar um arquivo configure.ac preliminar execute o comando abaixo.
```
$ autoscan
```
Serão criados os arquivos configure.scan e configure.log, sendo que o configure.scan é o configure.ac preliminar e o configure.log contém os erros encontrados.

Renomeie o arquivo configure.scan para configure.ac. O arquivo configure.log pode ser excluído.
Modifique o arquivo configure.ac como abaixo.
configure.ac
```
#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.

AC_PREREQ([2.54])
AC_INIT([Hello World], [0.1.0], [myemail@server.com], [hello-world])
AC_CONFIG_SRCDIR([src])
AC_CONFIG_HEADERS([config.h])
AM_INIT_AUTOMAKE([1.9 -Wall -Werror])

# Checks for programs.
AC_PROG_CXX

# Checks for libraries.

# Checks for header files.

# Checks for typedefs, structures, and compiler characteristics.

# Checks for library functions.

AC_CONFIG_FILES([Makefile
src/Makefile])
AC_OUTPUT
```
AC_PREREQ: A versão mínima necessária do autoconf, geralmente é a versão 2.54.

AC_INIT: Define o nome e versão do projeto, endereço para relatar erros e o nome do pacote do projeto.

AC_CONFIG_SRCDIR: Define a pasta que contém o código fonte.

AC_CONFIG_HEADERS: Define o nome do arquivo de definições do projeto, é recomendável deixar o padrão.

AM_INIT_AUTOMAKE: É necessário para fazer uso dos Makefile.am. Define a versão mínima do automake e as opções -Wall e -Werror definem respectivamente que devem ser mostrados todos os alertas e que todos os alertas devem ser tratados como erros.

AC_PROG_CXX: Verifica e exige o compilador C++ para o projeto.

AC_CONFIG_FILES: Define os locais dos arquivo Makefile do projeto.

AC_OUTPUT: Macro que executa a saída do autoconf.
É necessário executar os comandos aclocal, autoconf, autoheader e automake para gerar o script de configuração do projeto, mas para facilitar há o comando autoreconf que executa todos os comandos necessários.

Inicialmente iremos executar o comando abaixo para que os arquivos iniciais necessários sejam criados.
```
$ autoreconf --install
```
Serão criados vários arquivos, sendo que o arquivo INSTALL contém instruções de instalação e configuração e o arquivo COPYING contém a licença do programa.

O automake exige os arquivos NEWS, README, AUTHORS e ChangeLog. Inicialmente crie-os vazios.
```
$ touch NEWS README AUTHORS ChangeLog
```
Execute o comando autoreconf e será gerado o script de configuração do projeto novamente, agora sem erros com o automake.
Execute o script ./configure para configurar o projeto.
Execute o comando make para compilar o projeto.
Teste o executável do projeto:
```
$ src/hello-world
```
Para criar um pacote do projeto execute o seguinte comando:
```
$ make dist
```
E será criado um pacote distribuível para outros que queiram compilar o projeto.

Para que além de ser criado o pacote o mesmo seja testado, execute o seguinte comando:
```
$ make distcheck
```

Pronto, é isso.

Aqui só é mostrado o básico necessário para começar a usar o Autotools, as possibilidades vão muito além destas explicadas.

O pacote final pode ser acessado neste link: http://dl.getdropbox.com/u/1671797/Blog/hello-world-0.1.0.tar.gz

Referências

Manual do autoconf: http://www.gnu.org/software/autoconf/manual/index.html
Manual do automake: http://www.gnu.org/software/automake/manual/index.html