Authentication Chain

Muitas ações no protocolo Decentraland exigem ou se beneficiam da autorização com uma assinatura da conta Ethereum do usuário. Por exemplo:

1. Enviar uma nova versão de qualquer Entidade que eles possuam (como seu perfil).

2. Autenticar-se em serviços de terceiros.

3. Autorizar delegados a agir em seu nome.

Para executar essas ações, usuários e delegados devem assinar cargas úteis que descrevam sua intenção e produzir um auth_chain.

Introdução

Cadeias de autenticação encapsulam uma série de etapas de verificação, com cada etapa dependendo da verificação bem-sucedida da anterior. Todas as etapas devem ser consideradas válidas pelo verificador para que qualquer ação restrita ocorra.

Toda cadeia começa identificando o usuário e termina com uma carga útil assinada que representa a ação solicitada. A menor cadeia contém assim dois elementos, que indicam:

1. A autoridade é a conta Ethereum <user-address>
2. A carga útil é <payload>, autorizada por <user-signature>

Essa cadeia básica pode ser avaliada verificando que a chave pública da assinatura corresponde ao endereço. Nesse caso, é equivalente a uma assinatura simples.

Quando usuários autorizam delegados a agir em seu nome, aparecem etapas intermediárias na cadeia. Por exemplo, uma cadeia com uma única delegação indicaria:

1. A autoridade é a conta Ethereum <user-address>
2. O delegado é <delegate-address>, autorizado por <user-signature> até <date>
3. A carga útil é <payload>, autorizada por <delegate-signature>

As cadeias são mais longas quando delegados autorizam seus próprios delegados. Em outras palavras, a autorização é transitiva.

Você pode pensar nas cadeias de autenticação como análogas às cadeias de certificados TLS usadas em HTTPS, com o usuário como o equivalente à autoridade raiz.

Essa cadeia com um único delegado é a forma mais comum de autorização usada no Decentraland, já que os usuários autorizam uma chave para seu World Explorer para evitar ter que assinar cada ação individual com sua conta Ethereum.

Construindo uma Cadeia

Cada etapa na cadeia de autenticação contém três informações: um type, um payload e uma assinatura.

Campo	Valor
type	O nome de um tipo (veja abaixo).
payload	Uma string dependente do tipo.
assinatura	A assinatura Ethereum codificada em hex de payload, começando com 0x.

Como a serialização mais comum de uma cadeia de autenticação é um array JSON, os exemplos abaixo são apresentados nessa forma. Veja Transmitindo uma Cadeia para mais detalhes.

Primeira Etapa: Identificação

A primeira etapa, que identifica a autoridade original (i.e. o usuário), deve satisfazer estas condições:

1. O type estiver SIGNER

2. O payload é a conta Ethereum codificada.

3. O assinatura está vazia.

Por exemplo:

// Primeira etapa em qualquer cadeia de autenticação:
{
  "type": "SIGNER",
  "payload": "0xdB055877e6c13b6A6B25aBcAA29B393777dD0a73",
  "signature": ""
}

A segunda etapa deve conter uma assinatura dessa conta para seu payload.

Etapas Intermediárias: Delegação

Quando delegados estão agindo em nome do usuário, um item é adicionado no meio da cadeia para cada um deles. As condições para essas etapas são:

1. O tipo é ECDSA_EPHEMERAL

2. O payload é um texto especialmente elaborado (veja abaixo).

O payload é projetado para ser fácil de ler e fácil de analisar, já que tanto humanos (ao usar a interface da carteira) quanto programas (ao criar e validar) devem trabalhar com ele. Contém exatamente 3 linhas de texto simples sensível a maiúsculas/minúsculas:

<purpose>
Endereço efêmero: <delegate-address>
Expiração: <date>

Por exemplo, esta é uma carga útil típica usada pelos World Explorers durante o login, quando eles geram sua chave delegada temporária para o usuário aprovar:

Decentraland Login
Endereço efêmero: 0xBB9aDF0183b1742196A4Aa55622D5838f4f483a7
Expiração: 2023-02-25T13:00:19.730Z

Note que:

1. O Endereço efêmero não precisa ser uma conta Ethereum real com fundos na blockchain. O campo pode apenas representar uma chave pública temporária.

2. O Expiração é uma data/hora serializada em ISO-8601 formato. Não precisa ser UTC.

3. A chave delegada deve ser renovada periodicamente com uma nova assinatura do usuário, devido a essa data de expiração.

É prática padrão (e altamente recomendada) gerar uma nova chave para cada renovação (daí o nome ECDSA_EPHEMERAL).

Um exemplo de etapa de delegação (valores abreviados para clareza):

{
  "type": "ECDSA_EPHEMERAL",
  "payload": "Decentraland Login\nEphemeral address: 0xBBa7...\nExpiration: 2021-01-25T...",
  "signature": "0x1370a4120a7cb0d2f6e4a5..."
}

A próxima etapa, seja outra delegação ou a autorização final, carrega uma assinatura da chave deste delegado.

Última Etapa: Autorização

Após o SIGNER ter sido especificado e todas as ECDSA_EPHEMERAL chaves delegadas terem sido validadas verificando a cadeia de assinaturas intermediárias, a etapa final é a ação real que precisa ser autorizada.

O payload depende do type da etapa. Por exemplo, se um usuário está enviando um novo perfil (ou qualquer entidade que possua) para um servidor de conteúdo, o último elemento terá esta forma:

{
  // O tipo indica que `payload` é um ID de entidade (detalhes na seção Content):
  "type": "ECDSA_SIGNED_ENTITY",

  // O payload é a string bruta do ID:
  "payload": "bafkreicfbg7ybpuoslkcf6x2vfnvzl5vwgqtb2pnheqiut2i4sgpblicqi",

  // A assinatura é produzida pela conta na etapa anterior (usuário ou delegado):
  "signature": "0x7e71dbbab..."
}

Se essa última assinatura também for válida, a ação pode prosseguir.

Transmitindo uma Cadeia

Como mencionado acima, a serialização mais comum de uma cadeia de autenticação é um array JSON. Esta é a abordagem recomendada.

No entanto, o protocolo não impõe isso. Desenvolvedores podem usar uma estratégia de serialização alternativa se for mais conveniente para um caso de uso particular, como YAML, arquivos CSV, formatos binários otimizados ou strings simples com campos delimitados.

Um exemplo de serialização alternativa dentro do próprio protocolo pode ser encontrado no SignedFetch módulo, que usa uma sequência de cabeçalhos HTTP em vez de um array JSON.

Escolhendo uma Data de Expiração

Ao selecionar a duração válida para uma chave delegada, há um trade-off: expirações mais curtas aumentam a segurança, mas expirações mais longas melhoram a experiência do usuário (já que delegados precisam ser renovados com interação humana com menor frequência).

Não existe uma estratégia universal para decidir qual deve ser a janela de tempo válida. O World Explorer da Foundation, para referência, solicita autorização para sua chave delegada por um mês.

Chaves efêmeras nunca devem conter fundos nem possuir a capacidade de transferir ativos digitais. É muito mais seguro para usuários finais se o vazamento de uma chave efêmera não puder resultar em perdas financeiras.

Formalização

O que segue é uma definição mais formal e precisa dos processos envolvidos. Siga estas instruções para lidar com cadeias de autenticação com sucesso.

Criação

Clientes que criam uma cadeia de autenticação para o usuário seguem estes passos:

1. Adicione a etapa de identificação:

   1. Defina o type para SIGNER.

   2. Defina o payload para o endereço Ethereum do usuário.

   3. Defina o assinatura para uma string vazia.

2. Adicione etapas de delegação:

   1. Gere ou use uma chave privada delegada existente (pode exigir interação).

   2. Calcule o endereço Ethereum do delegado derivado da correspondente chave pública.

   3. Defina o type para ECDSA_EPHEMERAL.

   4. Defina o expiração para uma data no futuro.

   5. Escolha um propósito para esta chave.

   6. Defina o payload para esta forma exata:

      <purpose>
      Endereço efêmero: <delegate-address>
      Expiração: <date>

   7. Defina o assinatura campo para a payload assinatura da chave anterior (usuário ou delegado).

   8. Repita para todos os delegados sucessivos.

3. Adicione a etapa de autorização da ação:

   1. Defina o type para um valor válido (veja abaixo)

   2. Defina o payload para o valor específico do tipo (como o ID da entidade).

   3. Defina o assinatura campo para a payload assinatura da chave anterior (usuário ou delegado).

4. Envie a cadeia de autenticação ao verificador.

Verificação

Servidores de conteúdo e serviços de terceiros que implementam verificação seguem estes passos:

1. Verificar identificação:

   1. Verifique se o type estiver SIGNER.

   2. Verifique se o payload é o endereço Ethereum do usuário.

   3. Verifique se o assinatura é uma string vazia.

2. Verificar delegados:

   1. Verifique se o type estiver ECDSA_EPHEMERAL.

   2. Verifique se o payload está nesta forma e extraia os campos:

      <purpose>
      Endereço efêmero: <delegate-address>
      Expiração: <date>

   3. Verifique se o data ainda está no futuro.

   4. Verifique se o propósito é suportado pelo seu serviço.

   5. Verifique se o assinatura é válido para o dado payload e a chave pública anterior.

   6. Repita para todos os delegados sucessivos.

3. Verificar autorização da ação:

   1. Verifique se o type é um valor válido (veja abaixo).

   2. Verifique se o payload é válido para este type.

   3. Verifique se o assinatura é válido para o dado payload e a chave pública anterior.

4. Aceite a cadeia de autenticação.

Tipos de Ação e Propósitos Padrão

O type e payload valores para identificação e delegação são padrão e devem ser verificados conforme descrito acima, mas clientes e serviços podem concordar em qualquer type, e sua payload estrutura, bem como definir um propósito para suas chaves delegadas que considerem válido.

O protocolo define três tipos padrão e um propósito padrão:

Tipo SIGNER

Deve ser o type inicial na cadeia, onde payload é o endereço Ethereum do usuário e assinatura é uma string vazia.

Tipo ECDSA_EPHEMERAL

Deve ser o type para etapas intermediárias na cadeia, onde payload está na forma descrita acima.

Tipo ECDSA_SIGNED_ENTITY

O type final na cadeia para autorizar implantações de entidades, onde payload é o ID de uma entidade pertencente ao usuário.

Propósito Decentraland Login

O usual propósito para World Explorers, assinado tanto ao entrar no mundo quanto ao renovar sua chave delegada.