Podpisy repozytorium

Artykuł
12/14/2023

Jeśli źródło pakietu obsługuje dodawanie podpisów repozytorium do opublikowanych pakietów, istnieje możliwość określenia przez klienta certyfikatów podpisywania używanych przez źródło pakietu. Ten zasób umożliwia klientom wykrywanie, czy podpisany pakiet repozytorium został naruszony, czy ma nieoczekiwany certyfikat podpisywania.

Zasób używany do pobierania informacji o sygnaturze repozytorium jest zasobem RepositorySignatures znajdującym się w indeksie usługi.

Wersje

Używana jest następująca @type wartość:

@type Wartość	Uwagi
RepositorySignatures/4.7.0	Wersja początkowa
RepositorySignatures/4.9.0	Obsługiwane przez klientów NuGet w wersji 4.9 lub nowszej
RepositorySignatures/5.0.0	Umożliwia włączenie funkcji `allRepositorySigned`. Obsługiwane przez klientów NuGet w wersji 5.0 lub nowszej

Podstawowy adres URL

Adres URL punktu wejścia dla następujących interfejsów API to wartość @id właściwości skojarzonej z wyżej wymienioną wartością zasobu @type . W tym temacie jest używany adres URL {@id}symbolu zastępczego .

Należy pamiętać, {@id} że w przeciwieństwie do innych zasobów adres URL jest wymagany do obsługi za pośrednictwem protokołu HTTPS.

Metody HTTP

Wszystkie adresy URL znalezione w zasobie sygnatur repozytorium obsługują tylko metody GET HTTP i HEAD.

Indeks podpisów repozytorium

Indeks podpisów repozytorium zawiera dwie informacje:

Określa, czy wszystkie pakiety znalezione w źródle są repozytorium podpisane przez to źródło pakietu.
Lista certyfikatów używanych przez źródło pakietu do podpisywania pakietów.

W większości przypadków lista certyfikatów będzie dołączana tylko do. Nowe certyfikaty zostaną dodane do listy, gdy poprzedni certyfikat podpisywania wygasł, a źródło pakietu musi rozpocząć korzystanie z nowego certyfikatu podpisywania. Jeśli certyfikat zostanie usunięty z listy, oznacza to, że wszystkie podpisy pakietów utworzone przy użyciu usuniętego certyfikatu podpisywania nie powinny być już uznawane za prawidłowe przez klienta. W takim przypadku podpis pakietu (ale niekoniecznie pakiet) jest nieprawidłowy. Zasady klienta mogą zezwalać na instalowanie pakietu jako niepodpisanego.

W przypadku odwołania certyfikatu (e.g. key naruszenia zabezpieczeń) źródło pakietu powinno ponownie podpisać wszystkie pakiety podpisane przez certyfikat, którego dotyczy problem. Ponadto źródło pakietu powinno usunąć certyfikat, którego dotyczy problem, z listy certyfikatów podpisywania.

Następujące żądanie pobiera indeks podpisów repozytorium.

GET {@id}

Indeks podpisu repozytorium jest dokumentem JSON zawierającym obiekt o następujących właściwościach:

Nazwisko	Type	Wymagania	Uwagi
allRepositorySigned	boolean	tak	Muszą znajdować się `false` w zasobach 4.7.0 i 4.9.0
signingCertificates	tablica obiektów	tak

Wartość allRepositorySigned logiczna jest ustawiona na wartość false, jeśli źródło pakietu zawiera pakiety, które nie mają podpisu repozytorium. Jeśli wartość logiczna jest ustawiona na true, wszystkie pakiety dostępne w źródle muszą mieć podpis repozytorium utworzony przez jeden z certyfikatów podpisywania wymienionych w pliku signingCertificates.

Ostrzeżenie

Wartość allRepositorySigned logiczna musi mieć wartość false dla zasobów 4.7.0 i 4.9.0. Klienci NuGet w wersji 4.7, 4.8 i 4.9 nie mogą instalować pakietów ze źródeł, które mają allRepositorySigned ustawioną wartość true.

W tablicy powinien znajdować się co najmniej jeden certyfikat signingCertificates podpisywania, jeśli allRepositorySigned wartość logiczna jest ustawiona na wartość true. Jeśli tablica jest pusta i allRepositorySigned jest ustawiona na wartość true, wszystkie pakiety ze źródła powinny być uznawane za nieprawidłowe, chociaż zasady klienta mogą nadal zezwalać na użycie pakietów. Każdy element w tej tablicy jest obiektem JSON o następujących właściwościach.

Nazwisko	Type	Wymagania	Uwagi
contentUrl	string	tak	Bezwzględny adres URL certyfikatu publicznego zakodowanego w formacie DER
Odciski palców	obiekt	tak
subject	string	tak	Nazwa wyróżniająca podmiotu od certyfikatu
issuer	string	tak	Nazwa wyróżniająca wystawcy certyfikatu
notBefore	string	tak	Znacznik czasu rozpoczęcia okresu ważności certyfikatu
notAfter	string	tak	Znacznik czasu zakończenia okresu ważności certyfikatu

Należy pamiętać, że contentUrl element jest wymagany do obsługi za pośrednictwem protokołu HTTPS. Ten adres URL nie ma określonego wzorca adresu URL i musi zostać dynamicznie odnaleziony przy użyciu tego dokumentu indeksu podpisów repozytorium.

Wszystkie właściwości tego obiektu (oprócz contentUrl) muszą być wyprowadzane z certyfikatu znalezionego w lokalizacji contentUrl. Te właściwości pochodne są dostarczane jako wygoda, aby zminimalizować rundy.

Obiekt fingerprints ma następujące właściwości:

Nazwisko	Type	Wymagania	Uwagi
2.16.840.1.101.3.4.2.1	string	tak	Odcisk palca SHA-256

Nazwa 2.16.840.1.101.3.4.2.1 klucza to identyfikator OID algorytmu wyznaczania wartości skrótu SHA-256.

Wszystkie wartości skrótu muszą mieć małe litery, reprezentacje ciągów szesnastkowych skrótu.

Przykładowe żądanie

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

Przykładowa odpowiedź

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

Udostępnij za pośrednictwem