Assinaturas de repositório
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:
- Se todos os pacotes encontrados na origem são ou não um repositório assinado por essa origem do pacote.
- 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/5.0.0/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"
},
{
"fingerprints": {
"2.16.840.1.101.3.4.2.1": "1f4b311d9acc115c8dc8018b5a49e00fce6da8e2855f9f014ca6f34570bc482d"
},
"subject": "CN=NuGet.org Repository by Microsoft, O=NuGet.org Repository by Microsoft, L=Redmond, S=Washington, C=US",
"issuer": "CN=DigiCert Trusted G4 Code Signing RSA4096 SHA384 2021 CA1, O=\"DigiCert, Inc.\", C=US",
"notBefore": "2024-02-23T00:00:00.0000000Z",
"notAfter": "2027-05-18T23:59:59.0000000Z",
"contentUrl": "https://api.nuget.org/v3-index/repository-signatures/certificates/1f4b311d9acc115c8dc8018b5a49e00fce6da8e2855f9f014ca6f34570bc482d.crt"
}
]
}