Firmas de repositorio

  • Artículo

Si un origen de paquete admite la adición de firmas de repositorio a paquetes publicados, un cliente puede determinar los certificados de firma que utiliza el origen del paquete. Este recurso permite a los clientes detectar si se ha alterado un paquete firmado del repositorio o si existe un certificado de firma inesperado.

El recurso utilizado para capturar esta información de firma del repositorio es el recurso RepositorySignatures ubicado en el índice de servicio.

Control de versiones

Se utiliza el siguiente valor de @type:

Valor de @type Notas
RepositorySignatures/4.7.0 La versión inicial
RepositorySignatures/4.9.0 Compatible con clientes de NuGet v4.9+
RepositorySignatures/5.0.0 Permite habilitar allRepositorySigned. Compatible con clientes de NuGet v5.0+

URL base

La dirección URL de punto de entrada para las siguientes API es el valor de la propiedad @id asociada al valor @type de recurso mencionado anteriormente. En este tema se utiliza la dirección URL {@id} de marcador de posición.

Nota: A diferencia de otros recursos, es necesario proporcionar la dirección URL {@id} a través de HTTPS.

Métodos HTTP

Todas las direcciones URL que se encuentran en el recurso de firmas de repositorio solo admiten los métodos HTTP GET y HEAD.

Índice de firmas de repositorio

El índice de firmas de repositorio contiene dos fragmentos de información:

  1. Indica si todos los paquetes encontrados en el origen tienen firma de repositorio de este origen de paquete.
  2. Incluye también una lista de los certificados utilizados por el origen del paquete para firmar paquetes.

En la mayoría de los casos, la lista de certificados solo se anexará. Los nuevos certificados se agregarán a la lista cuando el certificado de firma anterior haya expirado y el origen del paquete deba empezar a utilizar un nuevo certificado de firma. Si se elimina un certificado de la lista, significa que el cliente ya no debe considerar válidas todas las firmas de paquete creadas con el certificado de firma eliminado. En este caso, la firma del paquete no es válida, pero el paquete sí puede serlo. Una directiva de cliente puede permitir la instalación del paquete sin firmar.

En el caso de la revocación de certificado (por ejemplo, por compromiso de clave), se espera que el origen del paquete vuelva a firmar todos los paquetes firmados por el certificado afectado. Además, el origen del paquete debe eliminar el certificado afectado de la lista de certificados de firma.

La siguiente solicitud captura el índice de firmas de repositorio.

GET {@id}

El índice de firmas de repositorio es un documento JSON que contiene un objeto con las siguientes propiedades:

Nombre Type Obligatorio Notas
allRepositorySigned boolean sí Debe ser false en los recursos 4.7.0 y 4.9.0
signingCertificate matriz de objetos sí

El valor booleano allRepositorySigned se ajusta en “false” si el origen del paquete tiene algunos paquetes sin firma de repositorio. Si el valor booleano se ajusta en “true”, todos los paquetes disponibles en el origen deben tener una firma de repositorio generada por uno de los certificados de firma que se mencionan en signingCertificates.

Advertencia

El valor booleano allRepositorySigned debe ser “false” en los recursos 4.7.0 y 4.9.0. Los clientes de NuGet v4.7, v4.8 y v4.9 no pueden instalar paquetes de orígenes que tengan allRepositorySigned ajustado en “true”.

La matriz signingCertificates debe tener uno o más certificados de firma si el valor booleano allRepositorySigned se ha ajustado en “true”. Si la matriz está vacía y allRepositorySigned se ha ajustado en “true”, todos los paquetes del origen deben considerarse no válidos, aunque una directiva de cliente todavía pueda permitir el consumo de paquetes. Cada elemento de la matriz es un objeto JSON que consta de las siguientes propiedades.

Nombre Type Obligatorio Notas
contentUrl string sí Dirección URL absoluta al certificado público codificado en DER
huellas digitales object sí
subject string sí Nombre completo (DN) del firmante en el certificado
issuer string sí Nombre completo (DN) del emisor de certificado
notBefore string sí Marca de tiempo inicial del período de validez del certificado
NotAfter string sí Marca de tiempo final del período de validez del certificado

Nota: Es necesaria la contentUrl para funcionar a través de HTTPS. Esta dirección URL no tiene ningún patrón de dirección URL específico y debe descubrirse dinámicamente mediante este documento de índice de firmas de repositorio.

Todas las propiedades de este objeto (aparte de contentUrl) deben derivarse del certificado que se encuentra en contentUrl. Estas propiedades derivables se proporcionan a fin de minimizar los recorridos de ida y vuelta.

El objeto fingerprints tiene las siguientes propiedades:

Nombre Type Obligatorio Notas
2.16.840.1.101.3.4.2.1 string sí Huella digital SHA-256

El nombre de clave 2.16.840.1.101.3.4.2.1 es el OID del algoritmo hash SHA-256.

Todos los valores hash deben estar en minúsculas y ser las representaciones de cadena codificadas en hexa del resumen hash.

Solicitud de ejemplo

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

Respuesta de muestra

{
  "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"
    }
  ]
}