Klasik API isteği yapma

Yalnızca geliştiricilerin çoğu için uygun olan standart API istekleri göndermeyi planlıyorsanız dürüstlük kararlarına atlayabilirsiniz. Bu sayfada, Android 4.4 (API düzeyi 19) veya sonraki sürümlerde desteklenen bütünlük kararları için klasik API isteklerinin nasıl yapılacağı açıklanmaktadır.

Dikkat edilmesi gereken noktalar

Standart ve klasik istekleri karşılaştırma

Uygulamanızın güvenlik ve kötüye kullanım önleme ihtiyaçlarına bağlı olarak standart istek, klasik istek veya bunların bir kombinasyonunu gönderebilirsiniz. Standart istekler tüm uygulamalar ve oyunlar için uygundur ve herhangi bir işlemin veya sunucu çağrısının orijinal olup olmadığını kontrol etmek için kullanılabilir. Ayrıca, yeniden oynanabilirliğe ve veri sızıntılarına karşı korumanın bir kısmını Google Play'e devreder. Klasik isteklerin yapılması daha pahalıdır ve veri sızıntısına ve belirli saldırı türlerine karşı koruma sağlamak için bunları doğru şekilde uygulamaktan siz sorumlusunuz. Klasik istekler, standart isteklerden daha seyrek gönderilmelidir. Örneğin, çok değerli veya hassas bir işlemin gerçek olup olmadığını kontrol etmek için zaman zaman tek seferlik gönderilebilir.

Aşağıdaki tabloda, iki istek türü arasındaki temel farklılıklar vurgulanmaktadır:

* Herkese açık sınırı olmayanlar da dahil olmak üzere tüm istekler, yüksek değerlerde herkese açık olmayan savunma sınırlarına tabidir

Klasik istekleri seyrek gönderin

Bir bütünlük jetonu oluşturmak zaman, veri ve pil kullanır. Ayrıca her uygulamanın günde gönderebileceği maksimum klasik istek sayısı vardır. Bu nedenle, yalnızca standart bir istek için ek garanti istediğinizde en yüksek değere sahip veya en hassas işlemlerin orijinal olup olmadığını kontrol etmek için klasik istekler göndermeniz gerekir. Yüksek sıklıkta veya düşük değerli işlemler için klasik istekler göndermemelisiniz. Uygulama her ön plana çıktığında veya arka planda birkaç dakikada bir klasik istek göndermeyin ve aynı anda çok sayıda cihazdan arama yapmaktan kaçının. Çok fazla klasik istek çağrısı yapan bir uygulama, kullanıcıları yanlış uygulamalardan korumak için kısıtlanabilir.

Kararları önbelleğe almaktan kaçının

Kararın önbelleğe alınması, iyi bir kararın güvenilmeyen bir ortamdan yeniden kullanıldığı dışa aktarma ve yeniden oynatma gibi saldırı riskini artırır. Klasik bir istek gönderip daha sonra kullanmak için isteği önbelleğe almayı düşünüyorsanız bunun yerine isteği isteğe bağlı olarak standart şekilde göndermeniz önerilir. Standart istekler cihazda bazı önbelleğe alma işlemlerini içerir ancak Google Play, yeniden oynatma saldırıları ve veri sızıntısı riskini azaltmak için ek koruma teknikleri kullanır.

Klasik istekleri korumak için tek seferlik sayı alanını kullanma

Play Integrity API, uygulamanızı yeniden oynatma ve müdahale saldırıları gibi belirli saldırılara karşı daha fazla koruma sağlamak için kullanılabilecek nonce adlı bir alan sunar. Play Integrity API, bu alanda ayarladığınız değeri imzalı bütünlük yanıtının içinde döndürür. Uygulamanızı saldırılara karşı korumak için tek seferlik rastgele sayı oluşturma ile ilgili talimatları dikkatlice uygulayın.

Klasik istekleri eksponansiyel geri yüklemeyle yeniden deneme

Kararsız internet bağlantısı veya aşırı yüklenmiş cihaz gibi çevresel koşullar, cihaz bütünlüğü kontrollerinin başarısız olmasına neden olabilir. Bu durum, güvenilir olan bir cihaz için etiket oluşturulmamasına neden olabilir. Bu senaryoları azaltmak için eksponansiyel geri yükleme içeren bir yeniden deneme seçeneği ekleyin.

Genel Bakış

Kullanıcı, uygulamanızda bir bütünlük kontrolüyle korumak istediğiniz yüksek değerli bir işlem gerçekleştirdiğinde aşağıdaki adımları tamamlayın:

1. Uygulamanızın sunucu tarafı arka ucu, istemci tarafı mantığına benzersiz bir değer oluşturup gönderir. Kalan adımlarda bu mantık "uygulamanız" olarak adlandırılır.
2. Uygulamanız, nonce değerini yüksek değerli işleminizin benzersiz değerinden ve içeriğinden oluşturur. Ardından, nonce parametresini ileterek Play Integrity API'yi çağırır.
3. Uygulamanız, Play Integrity API'den imzalanmış ve şifrelenmiş bir karar alır.
4. Uygulamanız, imzalanmış ve şifrelenmiş kararı uygulamanızın arka ucuna iletir.
5. Uygulamanızın arka ucu, sonucu bir Google Play sunucusuna gönderir. Google Play sunucusu, sonucun şifresini çözer ve doğrular, ardından sonuçları uygulamanızın arka ucuna döndürür.
6. Uygulamanızın arka ucu, jeton yükünde bulunan sinyallere göre nasıl devam edileceğine karar verir.
7. Uygulamanızın arka ucu, karar sonuçlarını uygulamanıza gönderir.

Tek seferlik bir sayı oluşturun

Uygulamanızdaki bir işlemi Play Integrity API ile koruduğunuzda, ortadaki kişi (PITM) izinsiz değişiklik saldırıları ve yeniden oynatma saldırıları gibi belirli saldırı türlerini azaltmak için nonce alanından yararlanabilirsiniz. Play Integrity API, bu alanda ayarladığınız değeri imzalanan bütünlük yanıtında döndürür.

nonce alanında ayarlanan değer doğru şekilde biçimlendirilmelidir:

• String
• URL güvenli
• Base64 olarak kodlanmış ve sarmalayıcı içermeyen
• Minimum 16 karakter
• Maksimum 500 karakter

Play Integrity API'de nonce alanını kullanmanın bazı yaygın yolları aşağıda verilmiştir. nonce'ten en güçlü korumayı almak için aşağıdaki yöntemleri birlikte kullanabilirsiniz.

Kurcalamaya karşı koruma sağlamak için istek karması ekleme

Klasik bir API isteğinde nonce parametresini, standart bir API isteğinde requestHash parametresine benzer şekilde kullanarak isteğin içeriğini değiştirmeye karşı koruyabilirsiniz.

Bütünlük değerlendirmesi istediğinizde:

1. Devam eden kullanıcı işlemi veya sunucu isteğinden tüm kritik istek parametrelerinin (ör. kararlı bir istek serileştirmesinin SHA256'sı) özetini hesaplayın.
2. nonce alanını, hesaplanan özetin değerine ayarlamak için setNonce değerini kullanın.

Bütünlük değerlendirmesi aldığınızda:

1. Bütünlük jetonunun kodunu çözerek doğrulayın ve nonce alanından özeti alın.
2. İsteğin özetini uygulamadakiyle aynı şekilde hesaplayın (ör. kararlı bir istek serileştirmesinin SHA256'sı).
3. Uygulama tarafı ve sunucu tarafı özetlerini karşılaştırın. Eşleşmezlerse istek güvenilir değildir.

Tekrar oynatma saldırılarına karşı koruma sağlamak için benzersiz değerler ekleme

Kötü amaçlı kullanıcıların Play Integrity API'den önceki yanıtları yeniden kullanmasını önlemek için her mesajı benzersiz şekilde tanımlamak üzere nonce alanını kullanabilirsiniz.

Bütünlük değerlendirmesi istediğinizde:

1. Kötü amaçlı kullanıcıların tahmin edemeyeceği bir şekilde dünya genelinde benzersiz bir değer elde edin. Örneğin, sunucu tarafında oluşturulan kriptografik olarak güvenli bir rastgele sayı veya oturum ya da işlem kimliği gibi önceden var olan bir kimlik bu tür bir değer olabilir. Daha basit ve daha az güvenli bir yöntem de cihazda rastgele bir sayı oluşturmaktır. 128 bit veya daha büyük değerler oluşturmanızı öneririz.
2. nonce alanını 1. adımdaki benzersiz değere ayarlamak için setNonce() işlevini çağırın.

Bütünlük değerlendirmesi aldığınızda:

1. Bütünlük jetonunun kodunu çözerek doğrulayın ve nonce alanından benzersiz değeri alın.
2. 1. adımdaki değer sunucuda oluşturulduysa alınan benzersiz değerin, oluşturulan değerlerden biri olup olmadığını ve ilk kez kullanılıp kullanılmadığını kontrol edin (sunucunuzun, oluşturulan değerleri uygun bir süre boyunca kaydetmesi gerekir). Alınan benzersiz değer daha önce kullanılmışsa veya kayıtta görünmüyorsa isteği reddedin
3. Aksi takdirde, benzersiz değer cihazda oluşturulduysa alınan değerin ilk kez kullanılıp kullanılmadığını kontrol edin (sunucunuzun, daha önce görülen değerleri uygun bir süre boyunca kaydetmesi gerekir). Alınan benzersiz değer daha önce kullanıldıysa isteği reddedin.

Hem bozulma hem de tekrar oynatma saldırılarına karşı korumaları birlikte kullanma (önerilir)

Hem bozma hem de yeniden oynatma saldırılarına karşı koruma sağlamak için nonce alanını aynı anda kullanabilirsiniz. Bunu yapmak için yukarıda açıklandığı gibi benzersiz değeri oluşturun ve isteğinizin bir parçası olarak ekleyin. Ardından, benzersiz değeri karma değerin bir parçası olarak eklediğinizden emin olarak istek karmasını hesaplayın. Her iki yaklaşımı da birleştiren bir uygulama aşağıdaki gibidir:

Bütünlük değerlendirmesi istediğinizde:

1. Kullanıcı, yüksek değerli işlemi başlatır.
2. Tekrar oynatma saldırılarına karşı koruma sağlamak için benzersiz değerler ekleme bölümünde açıklandığı gibi bu işlem için benzersiz bir değer elde edin.
3. Korumak istediğiniz bir mesaj hazırlayın. 2. adımdaki benzersiz değeri mesaja ekleyin.
4. Uygulamanız, Kurcalamaya karşı koruma sağlamak için istek karması ekleme bölümünde açıklandığı gibi, korumak istediği mesajın özetini hesaplar. İleti benzersiz değeri içerdiğinden benzersiz değer karmanın bir parçasıdır.
5. nonce alanını önceki adımda hesaplanan özet olarak ayarlamak için setNonce()'ü kullanın.

Bütünlük değerlendirmesi aldığınızda:

1. İstekten benzersiz değeri alma
2. Bütünlük jetonunun kodunu çözerek doğrulayın ve nonce alanından özeti alın.
3. Kurcalamaya karşı koruma sağlamak için istek karması ekleyin bölümünde açıklandığı gibi, sunucu tarafında karmayı yeniden hesaplayın ve bütünlük jetonundan elde edilen karmayla eşleşip eşleşmediğini kontrol edin.
4. Tekrar oynatma saldırılarına karşı koruma sağlamak için benzersiz değerler ekleyin bölümünde açıklandığı gibi, benzersiz değerin geçerliliğini kontrol edin.

Aşağıdaki ardışık düzen şemasında, bu adımlar sunucu tarafı nonce ile gösterilmektedir:

Bütünlük değerlendirmesi isteme

nonce oluşturduktan sonra Google Play'den bütünlük kararı isteyebilirsiniz. Bunun için aşağıdaki adımları uygulayın:

1. Aşağıdaki örneklerde gösterildiği gibi bir IntegrityManager oluşturun.
2. İlişkili oluşturucudaki setNonce() yöntemi aracılığıyla nonce'yi sağlayarak bir IntegrityTokenRequest oluşturun. Yalnızca Google Play dışında dağıtılan uygulamaların ve SDK'ların da setCloudProjectNumber() yöntemi aracılığıyla Google Cloud proje numaralarını belirtmesi gerekir. Google Play'deki uygulamalar Play Console'daki bir Cloud projesine bağlıdır ve istekte Cloud projesi numarasının ayarlanması gerekmez.

3. Yöneticiyi kullanarak requestIntegrityToken()'ü arayın ve IntegrityTokenRequest'yi belirtin.

// Receive the nonce from the secure server.
val nonce: String = ...

// Create an instance of a manager.
val integrityManager =
    IntegrityManagerFactory.create(applicationContext)

// Request the integrity token by providing a nonce.
val integrityTokenResponse: Task<IntegrityTokenResponse> =
    integrityManager.requestIntegrityToken(
        IntegrityTokenRequest.builder()
             .setNonce(nonce)
             .build())

import com.google.android.gms.tasks.Task; ...

// Receive the nonce from the secure server.
String nonce = ...

// Create an instance of a manager.
IntegrityManager integrityManager =
    IntegrityManagerFactory.create(getApplicationContext());

// Request the integrity token by providing a nonce.
Task<IntegrityTokenResponse> integrityTokenResponse =
    integrityManager
        .requestIntegrityToken(
            IntegrityTokenRequest.builder().setNonce(nonce).build());

IEnumerator RequestIntegrityTokenCoroutine() {
    // Receive the nonce from the secure server.
    var nonce = ...

    // Create an instance of a manager.
    var integrityManager = new IntegrityManager();

    // Request the integrity token by providing a nonce.
    var tokenRequest = new IntegrityTokenRequest(nonce);
    var requestIntegrityTokenOperation =
        integrityManager.RequestIntegrityToken(tokenRequest);

    // Wait for PlayAsyncOperation to complete.
    yield return requestIntegrityTokenOperation;

    // Check the resulting error code.
    if (requestIntegrityTokenOperation.Error != IntegrityErrorCode.NoError)
    {
        AppendStatusLog("IntegrityAsyncOperation failed with error: " +
                requestIntegrityTokenOperation.Error);
        yield break;
    }

    // Get the response.
    var tokenResponse = requestIntegrityTokenOperation.GetResult();
}

// .h
void MyClass::OnRequestIntegrityTokenCompleted(
  EIntegrityErrorCode ErrorCode,
  UIntegrityTokenResponse* Response)
{
  // Check the resulting error code.
  if (ErrorCode == EIntegrityErrorCode::Integrity_NO_ERROR)
  {
    // Get the token.
    FString Token = Response->Token;
  }
}

// .cpp
void MyClass::RequestIntegrityToken()
{
  // Receive the nonce from the secure server.
  FString Nonce = ...

  // Create the Integrity Token Request.
  FIntegrityTokenRequest Request = { Nonce };

  // Create a delegate to bind the callback function.
  FIntegrityOperationCompletedDelegate Delegate;

  // Bind the completion handler (OnRequestIntegrityTokenCompleted) to the delegate.
  Delegate.BindDynamic(this, &MyClass::OnRequestIntegrityTokenCompleted);

  // Initiate the integrity token request, passing the delegate to handle the result.
  GetGameInstance()
    ->GetSubsystem<UIntegrityManager>()
    ->RequestIntegrityToken(Request, Delegate);
}

/// Create an IntegrityTokenRequest opaque object.
const char* nonce = RequestNonceFromServer();
IntegrityTokenRequest* request;
IntegrityTokenRequest_create(&request);
IntegrityTokenRequest_setNonce(request, nonce);

/// Prepare an IntegrityTokenResponse opaque type pointer and call
/// IntegerityManager_requestIntegrityToken().
IntegrityTokenResponse* response;
IntegrityErrorCode error_code =
        IntegrityManager_requestIntegrityToken(request, &response);

/// ...
/// Proceed to polling iff error_code == INTEGRITY_NO_ERROR
if (error_code != INTEGRITY_NO_ERROR)
{
    /// Remember to call the *_destroy() functions.
    return;
}
/// ...
/// Use polling to wait for the async operation to complete.
/// Note, the polling shouldn't block the thread where the IntegrityManager
/// is running.

IntegrityResponseStatus response_status;

/// Check for error codes.
IntegrityErrorCode error_code =
        IntegrityTokenResponse_getStatus(response, &response_status);
if (error_code == INTEGRITY_NO_ERROR
    && response_status == INTEGRITY_RESPONSE_COMPLETED)
{
    const char* integrity_token = IntegrityTokenResponse_getToken(response);
    SendTokenToServer(integrity_token);
}
/// ...
/// Remember to free up resources.
IntegrityTokenRequest_destroy(request);
IntegrityTokenResponse_destroy(response);
IntegrityManager_destroy();

Bütünlük değerlendirmesinin şifresini çözme ve doğrulama

Bütünlük değerlendirmesi istediğinizde Play Integrity API, imzalı bir yanıt jetonu sağlar. İsteğinize eklediğiniz nonce, yanıt jetonunun bir parçası olur.

Jeton biçimi

Jeton, JSON Web Signature (JWS)'ın JSON Web Encryption (JWE) olan iç içe yerleştirilmiş bir JSON Web Token'u (JWT)'dur. JWE ve JWS bileşenleri kompakt serileştirme kullanılarak gösterilir.

Şifreleme / imzalama algoritmaları, çeşitli JWT uygulamalarında iyi desteklenir:

• JWE, alg için A256KW ve enc için A256GCM kullanır

• JWS, ES256'yı kullanır.

Google sunucularında şifren çözme ve doğrulama (önerilen)

Play Integrity API, Google sunucularındaki bütünlük değerlendirmesinin şifresini çözmenize ve doğrulamanıza olanak tanır. Bu da uygulamanızın güvenliğini artırır. Bunun için aşağıdaki adımları uygulayın:

1. Uygulamanıza bağlı Google Cloud projesinde bir hizmet hesabı oluşturun.

2. Uygulamanızın sunucusunda, playintegrity kapsamını kullanarak hizmet hesabı kimlik bilgilerinizden erişim jetonunu alın ve aşağıdaki isteği gönderin:

   playintegrity.googleapis.com/v1/PACKAGE_NAME:decodeIntegrityToken -d \
   '{ "integrity_token": "INTEGRITY_TOKEN" }'

3. JSON yanıtını okuyun.

Yerel olarak şifreyi çözme ve doğrulama

Yanıt şifreleme anahtarlarınızı yönetmeyi ve indirmeyi seçerseniz döndürülen jetonun şifresini kendi güvenli sunucu ortamınızda çözebilir ve doğrulayabilirsiniz. IntegrityTokenResponse#token() yöntemini kullanarak döndürülen jetonu alabilirsiniz.

Aşağıdaki örnekte, Play Console'dan imza doğrulaması için AES anahtarının ve DER kodlamalı herkese açık EC anahtarının, uygulamanın arka ucundaki dile özgü anahtarlara (bizim durumumuzda Java programlama dili) nasıl kodunun çözüleceği gösterilmektedir. Anahtarların varsayılan işaretler kullanılarak base64 olarak kodlandığını unutmayın.

// base64OfEncodedDecryptionKey is provided through Play Console.
var decryptionKeyBytes: ByteArray =
    Base64.decode(base64OfEncodedDecryptionKey, Base64.DEFAULT)

// Deserialized encryption (symmetric) key.
var decryptionKey: SecretKey = SecretKeySpec(
    decryptionKeyBytes,
    /* offset= */ 0,
    AES_KEY_SIZE_BYTES,
    AES_KEY_TYPE
)

// base64OfEncodedVerificationKey is provided through Play Console.
var encodedVerificationKey: ByteArray =
    Base64.decode(base64OfEncodedVerificationKey, Base64.DEFAULT)

// Deserialized verification (public) key.
var verificationKey: PublicKey = KeyFactory.getInstance(EC_KEY_TYPE)
    .generatePublic(X509EncodedKeySpec(encodedVerificationKey))

// base64OfEncodedDecryptionKey is provided through Play Console.
byte[] decryptionKeyBytes =
    Base64.decode(base64OfEncodedDecryptionKey, Base64.DEFAULT);

// Deserialized encryption (symmetric) key.
SecretKey decryptionKey =
    new SecretKeySpec(
        decryptionKeyBytes,
        /* offset= */ 0,
        AES_KEY_SIZE_BYTES,
        AES_KEY_TYPE);

// base64OfEncodedVerificationKey is provided through Play Console.
byte[] encodedVerificationKey =
    Base64.decode(base64OfEncodedVerificationKey, Base64.DEFAULT);
// Deserialized verification (public) key.
PublicKey verificationKey =
    KeyFactory.getInstance(EC_KEY_TYPE)
        .generatePublic(new X509EncodedKeySpec(encodedVerificationKey));

Ardından, bu anahtarları kullanarak önce bütünlük jetonunun (JWE bölümü) şifresini çözebilir, ardından iç içe yerleştirilmiş JWS bölümünü doğrulayıp ayıklayabilirsiniz.

val jwe: JsonWebEncryption =
    JsonWebStructure.fromCompactSerialization(integrityToken) as JsonWebEncryption
jwe.setKey(decryptionKey)

// This also decrypts the JWE token.
val compactJws: String = jwe.getPayload()

val jws: JsonWebSignature =
    JsonWebStructure.fromCompactSerialization(compactJws) as JsonWebSignature
jws.setKey(verificationKey)

// This also verifies the signature.
val payload: String = jws.getPayload()

JsonWebEncryption jwe =
    (JsonWebEncryption)JsonWebStructure
        .fromCompactSerialization(integrityToken);
jwe.setKey(decryptionKey);

// This also decrypts the JWE token.
String compactJws = jwe.getPayload();

JsonWebSignature jws =
    (JsonWebSignature) JsonWebStructure.fromCompactSerialization(compactJws);
jws.setKey(verificationKey);

// This also verifies the signature.
String payload = jws.getPayload();

Elde edilen yük, bütünlük kararlarını içeren düz metin jetonudur.