Anahtar rotasyonu

Robert Ferens

Demián Renzulli

Bu belgede, izole web uygulaması (IWA) için anahtar döndürme işlemiyle ilgili temel bilgiler verilmektedir. Bu bilgiler arasında, anahtar döndürmenin ne zaman gerekli olduğu ve bir anahtarın kaybolması veya güvenliğinin ihlal edilmesi durumunda geliştiricilerin izlemesi gereken adımlar yer almaktadır.

IWAs için anahtar rotasyonu

Anahtar rotasyonu, IWA'nızı imzalamak için kullanılan özel anahtarların sızıntı veya kayıp durumunda değiştirilmesine olanak tanıyan bir mekanizmadır. Bu işlem, uygulamanın işlevsel kalmasını ve kararlı bir paket kimliği ile kaynak sürdürmesini sağlayarak uygulamanızın dağıtımının ve güncellemelerinin devamlılığını sağlar.

Anahtar döndürme işlemi için yönetici veya kullanıcı değişikliği gerekmez ve doğru şekilde yapıldığında bu değişiklikler yönetici ya da kullanıcılar tarafından fark edilmez. İlk izin verilenler listesi süreci sırasında oluşturulan güvenilen kişi kanalları, anahtar döndürmeyi etkinleştirmek için gereklidir.

Anahtar rotasyonunun gerekliliği

Anahtar değiştirme işlemi iki temel senaryoda kesinlikle gereklidir:

• Anahtar sızıntısı veya güvenliğinin ihlal edilmesi: Özel imzalama anahtarınızın güvenliği ihlal edilirse veya anahtarınız sızdırılırsa uygulamanızın güvenliğini sağlamak için anahtar değiştirme sürecini hemen başlatmanız gerekir. Sızdırılan bir anahtar, kimliğinize bürünmek, uygulama kullanıcılarınıza zarar vermek ve şirketinizin itibarını tehlikeye atmak için kullanılabilir.
• Anahtar kaybı: Özel imzalama anahtarınıza erişiminizi kaybederseniz ve yeni güncellemeleri imzalayamazsanız uygulamanızı dağıtma olanağınızı yeniden kazanmak için anahtar döndürme işlemi yapmanız gerekir.

Geliştirici şartları

Anahtar döndürme işlemini başlatmadan önce aşağıdaki ölçütleri karşılamanız gerekir:

• İzin verilenler listesindeki uygulama: Yalnızca izin verilenler listesindeki uygulamalarda anahtar değiştirme işlemi yapılabilir.
• Güvenilen e-posta: Anahtar rotasyonu isteğinde bulunmak için izin verilenler listesine ekleme işlemi sırasında sağlanan güvenilen e-posta adresini kullanmanız gerekir.

Barındırılan uygulamaları yeniden imzalama ve yeni sürümler yayınlama

Anahtar değiştirildikten sonra, geçerli bir anahtarla imzalanmamış tüm yüklü uygulama örnekleri engellenir. Kullanıcılarınızın hizmette kesinti yaşamaması için yeni anahtarla (veya her iki anahtarla) imzalanmış bir uygulama sunmanız gerekir. Yeniden imzalama paketlerinin teknik ayrıntılarını Bir paketi birden fazla anahtarla imzalama bölümünde bulabilirsiniz. Durumunuza bağlı olarak farklı senaryolar vardır:

A senaryosu: Anahtar kaybolmamıştır (ör. proaktif döndürme veya sızıntı).

Uygulamayı her iki anahtarla (eski ve yeni) imzalamanız ve kullanıcıya aşağıdaki yöntemlerden biriyle sunmanız gerekir:

• Yeni bir uygulama sürümü yayınlama (yeni sürümü güncelleme manifestlerinize ekleme) veya
• Barındırılan .swbn dosyalarınızı (güncelleme manifestlerinizde bağlantısı verilen) her iki anahtarla da imzalanacak şekilde güncelleyin. KSA aracı, mevcut swbn paketine başka bir imza eklemenizi sağlar.

Kullanıcılarınızın değişikliği fark etmemesi için bu işlem, anahtar döndürme işlemi Google tarafından işlenmeden önce yapılmalıdır.

B senaryosu: Anahtar kayboldu

Uygulama, kayıp anahtarla imzalanamadığı için bu durum daha karmaşıktır. Anahtar rotasyonu isteğinde bulunun ve sonraki adımlar için Google kişinizle iletişime geçin. Bu talimatları uygulayarak yeni imzaları barındırılan paketlerinize eklemeniz istenebilir.

Anahtar rotasyonu süreci

Anahtar döndürme işlemi aşağıdaki adımları içerir:

Güncelleme kanalı ve sürüm sabitleme

Yöneticiler bazen özel güncelleme kanalları veya sürüm sabitleme kullanır. Bu sayede, istemci cihazlarındaki uygulama sürümlerini yönetebilirler. Anahtar rotasyonundan sonra, geçersiz anahtarlarla yüklenen tüm uygulamalar geçersiz hale gelir ve engellenir. Bunu önlemek için update_manifest.json içinde sağlanan bağlantılar altında barındırılan uygulamaların önceki sürümlerinin de anahtar rotasyonundan önce güncellenmesi ve iki imza ile imzalanması gerekir. Eski anahtarınız kaybolduysa ve uygulama iki anahtarla imzalanamıyorsa Google'daki ilgili kişinize hemen bildirin. Uygulamanın, kullanıcılarınızın iş akışlarını kesintiye uğratmadan güncellenebilmesi için bu durumu hafifletmek üzere sizinle birlikte çalışacağız.

Birden fazla anahtarla paket imzalama

Bu bölümde, web paketlerinizi CLI araçları veya Webpack/Rollup/Vite eklentileri yapılandırması aracılığıyla bir veya iki anahtarla nasıl imzalayabileceğiniz açıklanmaktadır. CLI araçları, mevcut swbn paketlerine bir imza daha eklemeyi de sağlar. Bu, anahtar kaybı durumlarında veya daha önce barındırılan paketleri güncellemek için yararlı olabilir.

CLI Araçları

Öncelikle, wbn-sign paketinin npm ile yüklendiğinden emin olun:

$ npm i wbn-sign

Paketi yalnızca geçerli klasörde değil, global olarak yüklemek için -g ekleyin.

Tek anahtarla imzalama

$ wbn-sign -i unsigned.wbn -o signed.swbn -k private.pem

İki anahtarla imzalama

$ wbn-sign sign webbundle.wbn old_key.pem new_key.pem -o signed.swbn --web-bundle-id <your-id-from-old-private>

Uygulamanın ilk sürümünün imzalandığı ilk anahtar old_key ise --web-bundle-id <id> bağımsız değişkeni atlanabilir. Bu durumda paket kimliği anahtardan türetilir. Paket kimliğini wbn-sign info signed.swbn komutuyla doğrulayabilirsiniz.

Mevcut pakete imza ekleme

$ wbn-sign add-signature signed.swbn key3.pem --in-place

Paketi geçersiz kılmak istemiyorsanız ancak yeni bir çift imzalı paket oluşturmak istiyorsanız -o simgesini kullanın.

CLI aracı hakkında daha fazla bilgi

CLI aracını kullanma hakkında daha fazla bilgi için npm wbn-sign page sayfasına bakın. Alternatif olarak, wnb-sign help. seçeneğini kullanın.

Webpack eklentisi

Tek anahtarla imzalama

Webpack eklentisini, IWA'nızı tek bir özel anahtarla imzalayacak şekilde yapılandırmak için:

• Gerekli temel URL'yi doğrudan bu anahtardan otomatik olarak türetmek için WebBundlePlugin öğesini ayarlayın.
• İmzalı NodeCryptoSigningStrategy dosyanızı oluşturmak için tek bir NodeCryptoSigningStrategy kullanın..swbn

// key is parsePemKey(private.pem)

plugins.push(
  new WebBundlePlugin({
    baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategy: new NodeCryptoSigningStrategy(key)
    }
  })
)

İki anahtarla imzalama

Anahtar değiştirme işlemi sırasında uygulamanızı iki kez imzalamanız gerektiğinde:

• Uygulamanın kimliğinin kullanıcılarınız için sabit kalmasını sağlamak amacıyla webBundleId ve temel URL'yi orijinal (old_key) uygulamanıza göre tanımlayın.
• Hem eski hem de yeni özel anahtarlarınızı uygulamak için çeşitli imzalama stratejileri kullanın.

// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)

plugins.push(
  new WebBundlePlugin({
    baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public') },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategies: [
        new NodeCryptoSigningStrategy(old_key),
        new NodeCryptoSigningStrategy(new_key)
      ],
      webBundleId: new WebBundleId(old_key).serialize()
    }
  })
)

Rollup veya Vite eklentisi

Tek anahtarla imzalama

Uygulamanızı tek bir özel anahtarla imzalamak için Rollup veya Vite eklentisini kullanmak istiyorsanız (Webpack kurulumuna benzer şekilde) eklenti tek bir imzalama stratejisi kullanır ve imzalı çıktınızı oluşturmak için sağlanan anahtardan temel URL'yi türetmeyi yönetir.

// key is parsePemKey(private.pem)

plugins.push({
  ...wbn({
    baseURL: new WebBundleId(key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategy: new NodeCryptoSigningStrategy(key)
    }
  }),
  enforce: 'post'
})

İki anahtarla imzalama

Rollup veya Vite kullanarak uygulamanızı iki kez imzalamak için eklentiyi birden fazla anahtarı kabul edecek şekilde yapılandırmanız gerekir. Bu snippet, stratejiler dizisini kullanarak hem eski hem de yeni özel anahtarları uygular. Bu yöntem, ana URL'yi ve webBundleId değerini açıkça koruyarak sorunsuz bir geçiş sağlar. Bu değerler, orijinal ve mevcut anahtarınızdan türetilir.

// old_key is parsePemKey(old_private.pem)
// new_key is parsePemKey(new_private.pem)

plugins.push({
  ...wbn({
    baseURL: new WebBundleId(old_key).serializeWithIsolatedWebAppOrigin(),
    static: { dir: 'public' },
    output: 'signed.swbn',
    integrityBlockSign: {
      strategies: [
        new NodeCryptoSigningStrategy(old_key),
        new NodeCryptoSigningStrategy(new_key)
      ],
      webBundleId: new WebBundleId(old_key).serialize()
    }
  }),
  enforce: 'post'
})

Sonuç

IWA'nız için anahtar döndürmeyi başarıyla yönetmek, uygulamanızın dağıtımının güvenliğini ve sürekliliğini sağlamak açısından çok önemlidir. Belirtilen adımları uyguladığınızda, anahtarın kaybolup kaybolmadığı gibi özel durumunuzdan bağımsız olarak kullanıcılarınızın en az kesintiyle karşılaşmasını sağlayabilirsiniz. Webpack, Rollup veya Vite için sağlanan KSA araçlarını ya da eklenti yapılandırmalarını kullanarak uygulamanızın imzalarını verimli bir şekilde yönetebilir ve anahtar döndürme sürecinde sorunsuz bir şekilde ilerleyebilirsiniz. Acil durumlarda, belirlenen güvenilir e-posta adresiniz üzerinden Google Kişinizle hızlıca iletişim kurmayı unutmayın.