JSON Web Tokens (JWTs)

A Tink é compatível com a geração e verificação de JWTs, que são um padrão amplamente usado na Web. A implementação do JWT da Tink fornece um subconjunto do padrão JWT definido na RFC 7519 (links em inglês) que a equipe do Tink considera seguro de uso e que se encaixa bem na biblioteca do Tink.

A Tink não oferece suporte a partes do padrão que são raramente usadas ou difíceis de usar corretamente. Estas são as limitações:

• A Tink só é compatível com o formato de serialização compacta JWS. A serialização JSON da JWS e a JWE não têm suporte.
• A Tink não é compatível com o valor None no cabeçalho alg.
• O Tink só é compatível com os cabeçalhos typ, alg e kid. Nenhum outro cabeçalho é compatível.
• A Tink não permite que os tokens sejam analisados antes da verificação da assinatura ou do MAC.

Assinaturas JWT

Se os tokens forem gerados e verificados por entidades diferentes, use chaves assimétricas com as primitivas JwtPublicKeySign e JwtPublicKeyVerify. A chave privada é usada para gerar tokens, e a chave pública é usada para verificar tokens. Os algoritmos aceitos por esses primitivos são: ES256, ES384, ES512, RS256, RS384, RS512, PS256, PS384 e PS512.

Como escolher um tipo de chave

As assinaturas JWT usam tipos de chaves diferentes da assinatura digital normal no Tink. Isso é necessário porque alguns metadados, como alg e kid, precisam ser armazenados com a chave.

Recomendamos o uso de JWT_ES256 para a maioria dos casos de uso. Os tokens gerados com esse tipo de chave sempre têm um cabeçalho kid. Se você preferir tokens um pouco mais curtos sem um cabeçalho kid, escolha o tipo de chave JWT_ES256_RAW. Para ver todos os tipos de chave compatíveis, consulte Tipos de chave compatíveis.

Distribuição do conjunto de chaves públicas

A Tink permite que o conjunto de chaves públicas seja convertido de/para o formato de conjuntos JWK definido na RFC 7517 (link em inglês), que a maioria das bibliotecas JWT entende.

Observação :o formato de serialização do conjunto de chaves JSON do Tink não é um conjunto JWK, e outras bibliotecas provavelmente não poderão lê-lo.

A Tink não oferece suporte à exportação de chaves JWT públicas em nenhum outro formato. O motivo é que outros formatos não contêm os metadados alg e kid a serem usados na verificação, o que torna o uso deles mais propenso a erros e pode dificultar a rotação das chaves.

É preferível não compartilhar o conjunto de chaves públicas somente uma vez, mas oferecer uma maneira de atualizar automaticamente o conjunto de chaves públicas. Caso contrário, será muito difícil fazer a rotação para uma nova chave. Isso geralmente é feito publicando o conjunto de chaves públicas em um URL confiável e seguro. Um servidor que verifica os tokens precisa refazer periodicamente o conjunto de chaves públicas desse URL, por exemplo, uma vez por dia. Para alternar a chave, a nova chave pública precisa ser adicionada ao conjunto de chaves públicas pelo menos um dia antes de ser usado para assinar tokens. Caso contrário, os novos tokens assinados com a chave privada nova serão rejeitados pelos servidores que ainda usarem o conjunto de chaves públicas antigo.

Observação: algumas implementações buscam novamente a chave pública assim que um token com um cabeçalho kid desconhecido é recebido. Não é possível implementar essa lógica no Tink, já que o token não é analisado antes de ser verificado. Não recomendamos fazer isso de qualquer maneira, já que isso poderá resultar em muitas solicitações extras para o URL do conjunto de chaves se tokens maliciosos com cabeçalhos kid aleatórios forem enviados.

MAC do JWT

A Tink também oferece suporte a JWT com chaves simétricas com o JwtMac primitivo. Use esse primitivo somente se os tokens forem gerados e verificados pela mesma entidade. Os algoritmos com suporte a esse primitivo são HS256, HS384 e HS512.

Como escolher um tipo de chave

Os tipos de chave MAC do JWT são diferentes dos tipos de chave MAC normais. Recomendamos o uso de JWT_HS256 para a maioria dos casos.