Signatures de dépôt

Article
12/22/2023

Si une source de package prend en charge l’ajout de signatures de référentiel aux packages publiés, il est possible qu’un client détermine les certificats de signature utilisés par la source du package. Cette ressource permet aux clients de détecter si un package signé de référentiel a été falsifié ou a un certificat de signature inattendu.

La ressource utilisée pour récupérer ces informations de signature de référentiel est la ressource RepositorySignatures trouvée dans l’index de service.

Contrôle de version

La valeur suivante @type est utilisée :

Valeur @type	Notes
RepositorySignatures/4.7.0	La version initiale
RepositorySignatures/4.9.0	Pris en charge par les clients NuGet v4.9+
RepositorySignatures/5.0.0	Autorise l’activation `allRepositorySigned`. Pris en charge par les clients NuGet v5.0+

URL de base

L’URL de point d'entrée pour les API suivantes est la valeur de la propriété @id associée à la valeur de ressource @type mentionnée ci-dessus. Ce sujet utilise l’URL de l’espace réservé {@id}.

Notez que contrairement à d’autres ressources, l’URL {@id} doit être servie via HTTPS.

Méthodes HTTP

Toutes les URL trouvées dans la ressource signatures de référentiel prennent uniquement en charge les méthodes HTTP GET et HEAD.

Indice de signatures de référentiel

L’index des signatures du référentiel contient deux informations :

Indique si tous les packages trouvés sur la source sont signés par cette source de package.
Liste des certificats utilisés par la source du package pour signer des packages.

Dans la plupart des cas, la liste des certificats ne sera jamais qu’un ajout. De nouveaux certificats sont ajoutés à la liste lorsque le certificat de signature précédent a expiré et que la source du package doit commencer à utiliser un nouveau certificat de signature. Si un certificat est supprimé de la liste, cela signifie que toutes les signatures de package créées avec le certificat de signature supprimé ne doivent plus être considérées comme valides par le client. Dans ce cas, la signature du package (mais pas nécessairement le package) n’est pas valide. Une stratégie cliente peut autoriser l’installation du package comme non signé.

Dans le cas de la révocation de certificats (par ex. clé compromise), la source du package est censée réinscrire tous les packages signés par le certificat concerné. En outre, la source du package doit supprimer le certificat affecté de la liste des certificats de signature.

La requête suivante récupère l’index des signatures du référentiel.

GET {@id}

L’index de signature du référentiel est un document JSON qui contient un objet avec les propriétés suivantes :

Nom	Type	Requise	Notes
allRepositorySigned	booléen	Oui	Doit être `false` sur les ressources 4.7.0 et 4.9.0
signingCertificates	tableau d'objets	Oui

La valeur booléenne allRepositorySigned est définie sur faux si la source du package contient certains packages qui n’ont aucune signature de référentiel. Si la valeur booléenne est définie sur vrai, tous les packages disponibles sur la source doivent avoir une signature de référentiel produite par l’un des certificats de signature mentionnés dans signingCertificates.

Avertissement

La valeur booléenne allRepositorySigned doit être faux sur les ressources 4.7.0 et 4.9.0. Les clients NuGet v4.7, v4.8 et v4.9 ne peuvent pas installer de packages à partir de sources qui ont allRepositorySigned défini sur vrai.

Il doit y avoir un ou plusieurs certificats de signature dans le tableau signingCertificates si la valeur booléenne allRepositorySigned est définie sur vrai. Si le tableau est vide et si allRepositorySigned est défini sur vrai, tous les packages de la source doivent être considérés comme non valables, bien qu’une stratégie cliente puisse toujours autoriser la consommation de packages. Chaque élément dans ce tableau est un objet JSON avec les propriétés suivantes :

Nom	Type	Requise	Notes
contentUrl	string	Oui	URL absolue du certificat public codé en DER
empreintes digitales	object	Oui
subject	string	Oui	Nom unique du sujet à partir du certificat
issuer	string	Oui	Le nom unique de l’émetteur du certificat.
notBefore	string	Oui	Horodatage de début de la période de validité du certificat
notAfter	string	Oui	Horodatage de fin de la période de validité du certificat

Notez que le contentUrl doit être servi via HTTPS. Cette URL n’a pas de modèle d’URL spécifique et doit être découverte dynamiquement à l’aide de ce document d’index de signatures de référentiel.

Toutes les propriétés de cet objet (à part contentUrl) doivent être dérivables du certificat trouvé dans contentUrl. Ces propriétés dérivables sont fournies comme commodité pour réduire les allers-retours.

L’objet fingerprints dispose des propriétés suivantes :

Nom	Type	Requise	Notes
2.16.840.1.101.3.4.2.1	string	Oui	Empreinte digitale SHA-256

Le nom clé 2.16.840.1.101.3.4.2.1 est l’OID de l’algorithme de hachage SHA-256.

Toutes les valeurs de code de hachage doivent être en minuscules, des représentations sous forme de chaîne encodées en hexadécimal du code de hachage.

Exemple de requête

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

Exemple de réponse

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