Assinaturas de repositório

  • Artigo

Se uma origem de pacote oferecer suporte à adição de assinaturas de repositório a pacotes publicados, é possível que um cliente determine os certificados de autenticação usados pela origem do pacote. Esse recurso permite que os clientes detectem se um pacote assinado do repositório foi violado ou se tem um certificado de autenticação inesperado.

O recurso usado para buscar essas informações de assinatura do repositório é o recurso RepositorySignatures encontrado no índice de serviço.

Controle de versão

O seguinte valor @type é usado:

@type valor Observações
RepositorySignatures/4.7.0 O lançamento inicial
RepositorySignatures/4.9.0 Suportado por clientes do NuGet v4.9 ou superior
RepositorySignatures/5.0.0 Permite habilitar o allRepositorySigned. Suportado por clientes do NuGet v5.0 ou superior

URL base

A URL do ponto de entrada para as APIs a seguir é o valor da propriedade @id associada ao valor do recurso @type mencionado anteriormente. Este tópico usa a URL do espaço reservado {@id}.

Observe que, ao contrário de outros recursos, a URL {@id} é necessária para ser servida por HTTPS.

Métodos HTTP

Todas as URLs encontradas no recurso de assinaturas do repositório suportam apenas os métodos HTTP GET e HEAD.

Índice de assinaturas de repositório

O índice de assinaturas de repositório contém duas informações:

  1. Se todos os pacotes encontrados na origem são ou não um repositório assinado por essa origem do pacote.
  2. A lista de certificados usados pela origem do pacote para assinar pacotes.

Na maioria dos casos, a lista de certificados só será acrescentada. Novos certificados serão adicionados à lista quando o certificado de autenticação anterior tiver expirado e a origem do pacote precisar começar a usar um novo certificado de autenticação. Se um certificado for removido da lista, isso significa que todas as assinaturas de pacote criadas com o certificado de autenticação removido não devem mais ser consideradas válidas pelo cliente. Nesse caso, a assinatura do pacote (mas não necessariamente o pacote) é inválida. Uma política de cliente pode permitir a instalação do pacote como não assinado.

No caso de revogação de certificado (por exemplo, comprometimento de chave), espera-se que a origem do pacote assine novamente todos os pacotes assinados pelo certificado afetado. Além disso, a origem do pacote deve remover o certificado afetado da lista de certificados de autenticação.

A solicitação a seguir efetua fetch do índice de assinaturas do repositório.

GET {@id}

O índice de assinatura do repositório é um documento JSON que contém um objeto com as seguintes propriedades:

Nome Digitar Obrigatória Observações
allRepositorySigned boolean sim Deve ser false nos recursos 4.7.0 e 4.9.0
signingCertificates matriz de objetos sim

O booliano allRepositorySigned será definido como falso se a origem do pacote tiver alguns pacotes que não têm assinatura de repositório. Se o booliano estiver definido como verdadeiro, todos os pacotes disponíveis na origem deverão ter uma assinatura de repositório produzida por um dos certificados de autenticação mencionados em signingCertificates.

Aviso

O booliano allRepositorySigned deve ser falso nos recursos 4.7.0 e 4.9.0. Os clientes do NuGet v4.7, v4.8 e v4.9 não podem instalar pacotes de origens com allRepositorySigned definido como verdadeiro.

Deve haver um ou mais certificados de autenticação na matriz signingCertificates se o booliano allRepositorySigned estiver definido como verdadeiro. Se a matriz estiver vazia e allRepositorySigned estiver definido como verdadeiro, todos os pacotes da origem deverão ser considerados inválidos, embora uma política de cliente ainda possa permitir o consumo de pacotes. Cada elemento desta matriz é um objeto JSON com as seguintes propriedades.

Nome Digitar Obrigatória Observações
contentUrl string sim URL absoluta para o certificado público codificado por DER
impressões digitais objeto sim
subject string sim O nome diferenciado do assunto do certificado
emissor string sim O nome diferenciado do emissor do certificado
notBefore string sim O carimbo de data/hora inicial do período de validade do certificado
notAfter string sim O carimbo de data/hora final do período de validade do certificado

Observe que o contentUrl é necessário para ser servido por HTTPS. Essa URL não tem um padrão de URL específico e deve ser descoberta dinamicamente usando este documento de índice de assinaturas do repositório.

Todas as propriedades neste objeto (exceto contentUrl) devem ser deriváveis do certificado encontrado em contentUrl. Essas propriedades deriváveis são fornecidas como uma conveniência para minimizar viagens de ida e volta.

O objeto fingerprints tem as seguintes propriedades:

Nome Digitar Obrigatória Observações
2.16.840.1.101.3.4.2.1 string sim A impressão digital SHA-256

O 2.16.840.1.101.3.4.2.1 do nome da chave é o OID do algoritmo de hash SHA-256.

Todos os valores de hash devem ser minúsculos, representações de cadeias de caracteres codificadas por hexadecimal do resumo de hash.

Solicitação de exemplo

GET https://api.nuget.org/v3-index/repository-signatures/index.json

Resposta de exemplo

{
  "allRepositorySigned": true,
  "signingCertificates": [
    {
      "fingerprints": {
        "2.16.840.1.101.3.4.2.1": "0e5f38f57dc1bcc806d8494f4f90fbcedd988b46760709cbeec6f4219aa6157d"
      },
      "subject": "CN=NuGet.org Repository by Microsoft, O=NuGet.org Repository by Microsoft, L=Redmond, S=Washington, C=US",
      "issuer": "CN=DigiCert SHA2 Assured ID Code Signing CA, OU=www.digicert.com, O=DigiCert Inc, C=US",
      "notBefore": "2018-04-10T00:00:00.0000000Z",
      "notAfter": "2021-04-14T12:00:00.0000000Z",
      "contentUrl": "https://api.nuget.org/v3-index/repository-signatures/certificates/0e5f38f57dc1bcc806d8494f4f90fbcedd988b46760709cbeec6f4219aa6157d.crt"
    },
    {
      "fingerprints": {
        "2.16.840.1.101.3.4.2.1": "5a2901d6ada3d18260b9c6dfe2133c95d74b9eef6ae0e5dc334c8454d1477df4"
      },
      "subject": "CN=NuGet.org Repository by Microsoft, O=NuGet.org Repository by Microsoft, L=Redmond, S=Washington, C=US",
      "issuer": "CN=DigiCert SHA2 Assured ID Code Signing CA, OU=www.digicert.com, O=DigiCert Inc, C=US",
      "notBefore": "2021-02-16T00:00:00.0000000Z",
      "notAfter": "2024-05-15T23:59:59.0000000Z",
      "contentUrl": "https://api.nuget.org/v3-index/repository-signatures/certificates/5a2901d6ada3d18260b9c6dfe2133c95d74b9eef6ae0e5dc334c8454d1477df4.crt"
    }
  ]
}