Firmas de repositorio

Artículo
12/22/2023

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:

Indica si todos los paquetes encontrados en el origen tienen firma de repositorio de este origen de paquete.
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/5.0.0/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"
    },
    {
      "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"
    }
  ]
}

Compartir a través de