Aracılığıyla paylaş

JavaScript için Azure Doğrulama istemci kitaplığı - sürüm 1.0.0

Microsoft Azure Doğrulama (MAA) hizmeti, bir platformun güvenilirliğini ve içinde çalışan ikili dosyaların bütünlüğünü uzaktan doğrulamaya yönelik birleşik bir çözümdür. Hizmet, Güvenilir Platform Modülleri (TPM' ler) tarafından desteklenen platformların kanıtlamasını ve Intel(tm) Software Guard Uzantıları (SGX) kuşatmaları ve Sanallaştırma Tabanlı Güvenlik (VBS) kuşatmaları gibi Güvenilir Yürütme Ortamlarının (TEEs) durumunu kanıtlama özelliğini destekler.

Kanıtlama, yazılım ikili dosyalarının güvenilir bir platformda düzgün bir şekilde başlatıldığını gösteren bir işlemdir. Daha sonra, uzak bağlı olan taraflar yalnızca bu tür hedeflenen yazılımların güvenilen donanımlarda çalıştığından emin olabilir. Azure Doğrulama, müşteriye yönelik birleşik bir hizmet ve kanıtlama çerçevesidir.

Azure Doğrulama, Azure Gizli bilgi işlem ve Akıllı Uç koruması gibi son teknoloji güvenlik paradigmalarını etkinleştirir. Müşteriler bir makinenin konumunu, bu makinedeki bir sanal makinenin (VM) duruşunu ve bu VM üzerinde kuşatmaların çalıştığı ortamı bağımsız olarak doğrulama olanağı talep ediyor. Azure Doğrulama bunları ve birçok ek müşteri isteğini güçlendirecektir.

Azure Doğrulama işlem varlıklarından kanıt alır, bunları bir talep kümesine dönüştürür, yapılandırılabilir ilkelere karşı doğrular ve talep tabanlı uygulamalar (örneğin, bağlı olan taraflar ve denetim yetkilileri) için şifreleme kanıtı oluşturur.

Azure kitaplıklarının daha eksiksiz bir görünümü için bkz. azure sdk typescript sürümü.

NOT: Bu, Microsoft Azure Doğrulama hizmeti için bir önizleme SDK'sıdır. Azure Doğrulama hizmetine erişmek için tüm temel işlevleri sağlar, "olduğu gibi" kabul edilmelidir ve gelecekte önceki sürümlerle uyumluluğu bozabilecek değişikliklere tabidir.

Önemli bağlantılar:

Başlarken

Şu anda desteklenen ortamlar

Daha fazla ayrıntı için destek ilkemize bakın.

Önkoşullar

  • Azure Aboneliği
  • Mevcut bir Azure Doğrulama Örneği veya her Azure bölgesinde bulunan "paylaşılan sağlayıcıyı" kullanabilirsiniz. Azure Doğrulama hizmet örneği oluşturmanız gerekiyorsa Azure Portal'ı veya Azure CLI'yı kullanabilirsiniz.

@azure/attestation paketini yükleyin

NPM ile JavaScript için Microsoft Azure Doğrulama istemci kitaplığını yükleyin:

npm install @azure/attestation

İstemcinin kimliğini doğrulama

Microsoft Azure Doğrulama hizmetiyle etkileşim kurmak için Kanıtlama İstemcisi veya KanıtlamaYönetimi İstemcisi sınıfının bir örneğini oluşturmanız gerekir. Portalda gösterilen "Kanıtlama URI'si" veya paylaşılan kanıtlama sağlayıcılarından biri olacak bir kanıtlama örneği URL'sine ihtiyacınız vardır. Kanıtlama Yönetim İstemcisi'ni kullanmak veya API'yi çağırmak için de istemci kimlik bilgilerine attestTpm ihtiyacınız olacaktır. İstemci kimlik bilgileri, bir istemci nesnesinin örneğini oluşturmak için (istemci kimliği, istemci gizli dizisi, kiracı kimliği) gerektirir.

Bu başlangıç bölümünde DefaultAzureCredential sağlayıcısı aracılığıyla gizli istemci kimlik bilgilerini kullanarak kimlik doğrulaması yapacağız, ancak @azure/kimlik paketi aracılığıyla daha fazla kimlik doğrulama mekanizması sunuyoruz. Paketi yüklemek @azure/identity için:

npm install @azure/identity

Kimlik bilgilerini oluşturma/alma

İstemci gizli anahtarı kimlik bilgilerini oluşturmak/almak için aşağıdaki Azure CLI kod parçacığını kullanın.

  • Bir hizmet sorumlusu oluşturun ve Azure kaynaklarına erişimini yapılandırın:

    az ad sp create-for-rbac -n <your-application-name> --skip-assignment

    Çıkış:

    {
  "appId": "generated-app-ID",
  "displayName": "dummy-app-name",
  "name": "http://dummy-app-name",
  "password": "random-password",
  "tenant": "tenant-ID"
}

  • Hizmet sorumlusu objectId değerini not alın

    az ad sp show --id <appId> --query objectId

    Çıkış:

    "<your-service-principal-object-id>"

  • AZURE_CLIENT_ID (appId), AZURE_CLIENT_SECRET (parola) ve AZURE_TENANT_ID (kiracı) ortam değişkenlerini ayarlamak için yukarıdaki döndürülen kimlik bilgilerini kullanın. Aşağıdaki örnekte, PowerShell'de bunu yapmak için bir yol gösterilmektedir:

    $Env:AZURE_CLIENT_ID="generated-app-ID"
    $Env:AZURE_CLIENT_SECRET="random-password"
    $Env:AZURE_TENANT_ID="tenant-ID"

Azure Identity API'leri ve bunların nasıl kullanılacağı hakkında daha fazla bilgi için bkz. Azure Identity istemci kitaplığı

Önemli kavramlar

Bu önizleme SDK'sında dört önemli işlev ailesi sağlanır:

Microsoft Azure Doğrulama hizmeti iki ayrı modda çalışır: "Yalıtılmış" ve "AAD". Hizmet "Yalıtılmış" modda çalışırken, müşterinin bir kanıtlama örneğinin durumunu değiştirme yetkisine sahip olduğunu doğrulamak için kimlik doğrulaması kimlik bilgilerinin ötesinde ek bilgiler sağlaması gerekir.

Son olarak, Microsoft Azure Doğrulama hizmetinin kullanılabilir olduğu her bölge, yalnızca Azure temeline karşı doğrulama gerektiren SGX kuşatmalarını doğrulamak için kullanılabilen bir "paylaşılan" örneği destekler (paylaşılan sağlayıcıya uygulanan ilke yoktur). TPM kanıtlama paylaşılan sağlayıcıda kullanılamaz. Paylaşılan örnek AAD kimlik doğrulaması gerektiriyor olsa da RBAC ilkeleri yoktur. Geçerli bir AAD taşıyıcı belirteci olan tüm müşteriler paylaşılan örneği kullanarak bunu kanıtlayabilir.

Kanıtlama

SGX veya TPM kanıtlama, güvenilir bir yürütme ortamından toplanan kanıtların hem o ortam için Azure temeline hem de bu ortama uygulanan müşteri tanımlı ilkelere uyduğunu doğrulamak için gerçekleştirilir.

Kanıtlama hizmeti belirteci imzalama sertifikası bulma ve doğrulama

Azure Doğrulama Hizmetinin temel operasyonel garantilerinden biri, hizmetin "TCB'nin dışında operasyonel olarak" çalışmasıdır. Başka bir deyişle, bir Microsoft operatörünün hizmetin işlemiyle oynaması veya istemciden gönderilen verileri bozması söz konusu değildir. Bu garantiyi sağlamak için kanıtlama hizmetinin çekirdeği bir Intel(tm) SGX kapanımında çalışır.

Müşterilerin işlemlerin aslında kapanım içinde gerçekleştirildiğini doğrulamasına izin vermek için Kanıtlama Hizmeti'nden gelen çoğu yanıt, kanıtlama hizmetinin kapanımında tutulan bir anahtar tarafından imzalanan bir JSON Web Belirtecinde kodlanır.

Bu belirteç, belirtilen örnek için MAA hizmeti tarafından verilen bir imzalama sertifikası tarafından imzalanır.

MAA hizmet örneği hizmetin bir SGX kapanımında çalıştığı bir bölgede çalışıyorsa, sunucu tarafından verilen sertifika oe_verify_attestation_certificate API'sini kullanarak doğrulanabilir.

AttestationResponse nesnesi iki ana öznitelik içerir: token ve value. token özniteliği kanıtlama hizmeti tarafından döndürülen tam belirteci, value özniteliği ise JSON Web Belirteci yanıtının gövdesini içerir.

İlke Yönetimi

Her kanıtlama hizmeti örneğine, müşterinin tanımladığı ek ölçütleri tanımlayan bir ilke uygulanır.

Kanıtlama ilkeleri hakkında daha fazla bilgi için bkz. Kanıtlama İlkesi

İlke Yönetimi sertifika yönetimi

Bir kanıtlama örneği "Yalıtılmış" modunda çalışırken, örneği oluşturan müşteri, örnek oluşturulduğu sırada bir ilke yönetim sertifikası sağlamış olur. Tüm ilke değiştirme işlemleri, müşterinin ilke verilerini mevcut ilke yönetimi sertifikalarından biriyle imzalamasını gerektirir. İlke Yönetimi Sertifika Yönetimi API'leri, istemcilerin ilke yönetimi sertifikalarını "dağıtmasını" sağlar.

Yalıtılmış Mod ve AAD Modu

Her Microsoft Azure Doğrulama hizmet örneği "AAD" modunda veya "Yalıtılmış" modda çalışır. bir MAA örneği AAD modunda çalışırken, kanıtlama örneğini oluşturan müşterinin, Kanıtlama örneğine erişimi doğrulamak için Azure Active Directory ve Azure Rol Tabanlı Erişim denetim ilkelerine izin verdiği anlamına gelir.

Kanıtlama Türü

Microsoft Azure Doğrulama hizmeti, ortama bağlı olarak farklı kanıt türlerinin kanıtlanması destekler. Şu anda, MAA aşağıdaki Güvenilen Yürütme ortamlarını destekler:

  • OpenEnclave - Kanıtlama kanıtının OpenEnclave oe_get_report veya oe_get_evidence API kullanılarak toplandığı bir SGX Kapanımında kod çalıştıran Intel(tm) İşlemcisi.
  • SgxEnclave - Kanıtlama kanıtının Intel SGX SDK'sı kullanılarak toplandığı bir SGX Kapanımında kod çalıştıran Intel(tm) İşlemcisi.
  • Tpm - Kanıtlama kanıtı sağlamak için işlemcinin Güvenilir Platform Modülü'nin kullanıldığı Sanallaştırma Tabanlı Güvenlik ortamı.

Çalışma Zamanı Verileri ve Inittime Verileri

RuntimeData, Intel SGX Teklif oluşturma mantığına veya oe_get_report/oe_get_evidence API'lere sunulan verileri ifade eder. Attest API'sine çağıran bir runtime_data öznitelik sağladıysa, Azure Doğrulama hizmeti SGX Teklif/OE Raporu/OE Kanıtı alanındaki alanın ilk 32 baytının report_data öğesinin runtime_dataSHA256 karmasıyla eşleşip eşleşmediğini doğrular.

InitTime verileri, kanıtlanan SGX kapanımını yapılandırmak için kullanılan verileri ifade eder.

InitTime verilerinin Azure DCsv2 Serisi sanal makinelerde desteklenmediğini unutmayın.

Ek kavramlar

Örnekler

İstemci örneği oluşturma

Varsayılan Azure kimlik bilgilerini ()DefaultAzureCredential kullanarak uri'de endpointKanıtlama İstemcisi'nin bir örneğini oluşturur.

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

API'yi attestTpm çağırmıyorsanız, kanıtlama istemcisine erişmek için kimlik bilgileri sağlamanız gerekmez. Bu, bir istemcinin şu şekilde oluşturulabileceği anlamına gelir:

const client = new AttestationClient(endpoint);

// Retrieve the set of attestation policy signers from the attestation client.
const attestationSigners = await client.getAttestationSigners();

uri'de Kanıtlama Yönetim İstemcisi'nin bir örneğini endpointoluşturur.

Yönetim istemcisinin Azure kimlik bilgileri gerektirdiğini unutmayın.

  const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

  // Retrieve the SGX policy from the specified attestation instance.
  const policyResponse = await client.getPolicy(KnownAttestationType.SgxEnclave);

Kanıtlama ilkesini alma

getPolicy yöntemi, kanıtlama ilkesini hizmetten alır. Kanıtlama İlkeleri kanıtlama türü temelinde örneklenir, AttestationType parametresi alınacak örneğin türünü tanımlar.

const policyResult = await adminClient.getPolicy(attestationType);

// The text policy document is available in the `policyResult.body`
// property.

// The actual attestation token returned by the MAA service is available
// in `policyResult.token`.

Belirtilen kanıtlama türü için kanıtlama ilkesi ayarlama

Kanıtlama hizmeti örneği Yalıtılmış modda çalışıyorsa, set_policy API'sinin çağıranın kanıtlama örneğinde ilkeyi değiştirme yetkisi olduğunu doğrulamak için kullanılabilecek bir imzalama sertifikası (ve özel anahtar) sağlaması gerekir. Hizmet örneği AAD modunda çalışıyorsa imzalama sertifikası ve anahtarı isteğe bağlıdır.

Hizmet örneği AAD modunda çalışıyorsa setPolicy çağrısı beklendiği gibi olur:

const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Attestation Policy>`;

// Set the new attestation policy. Set the policy as an unsecured policy.
const setPolicyResult = await client.setPolicy(KnownAttestationType.SgxEnclave, newPolicy);

Hizmet örneği Yalıtılmış modda çalışıyorsa setPolicy çağrısı, istemcinin ilke yönetimi özel anahtarlarından ve sertifikalarından birine erişimi olduğunu kanıtlayabilmesini gerektirir.

const client = new AttestationAdministrationClient(endpoint, new DefaultAzureCredential());

const newPolicy = `<New Policy Document>`;

// Set the new attestation policy. Set the policy as an secured policy.
const privateKey = <Retrieve isolated mode private key from storage>
const certificate = <Retrieve certificate associated with that private key>

const setPolicyResult = await client.setPolicy(
  KnownAttestationType.OpenEnclave,
  newPolicy,
  {
    privateKey: privateKey,
    certificate: certificate
  }
);

SetPolicy API'leri, ilke belgesinde certificate bulunan ve daha sonra kanıtlama hizmetine gönderilen ile privateKey imzalanan bir JSON Web Belirteci oluşturur.

İstemci kanıtlama ilkesi belgesinin, kanıtlama hizmetinin kapanım tarafından alınmadan önce değiştirilmediğinden emin olmak isterse, ilke belgesinin hizmet tarafından alındığını doğrulamak için kullanılabilecek PolicyResult objct içinde döndürülen özellikleri kullanabilir:

  • policySigner- çağrıda bir certificatevarsasetPolicy, bu değer çağrı sırasında setPolicy sağlanan sertifika olacaktır. İlke imzalayan ayarlanmadıysa, bu null olur.
  • policyTokenHash - bu, setPolicy API'sinin hizmetine gönderilen JSON Web İmzasının karmasıdır.

Karmayı doğrulamak için istemciler bir kanıtlama ilkesi belirteci (kanıtlama ilkesini ayarlamak için kullanılan belirteci temsil eden bir yardımcı sınıfı) oluşturabilir ve bu belirteçten oluşturulan karmayı doğrulayabilir:

const expectedPolicy = createAttestationPolicyToken(
  `<Policy Document>`,
  privateKey,
  certificate);

// Use your favorite SHA256 hash generator function to create a hash of the
// stringized JWS.
const expectedHash = generateSha256Hash(expectedPolicy.serialize());

// The hash returned in expectedHash should match the value in
// `setResult.body.policyTokenHash`.

Attest SGX ve Open Enclave

attestSgxEnclave SGX kapanımını test etmek için yöntemini kullanın.

Müşterilerin şifrelenmiş ortamlarla etkileşim kurması gereken temel zorluklardan biri, ortamda çalışan kodla güvenli bir şekilde iletişim kurabilmenizi sağlamaktır ("kod kapanı") .

Bu sorunun bir çözümü, kapanım koduyla güvenli iletişim sağlayan bir desen olan "Güvenli Anahtar Sürümü" olarak bilinir.

"Güvenli Anahtar Yayını" desenini uygulamak için, kapanım kodu kısa ömürlü bir asimetrik anahtar oluşturur. Daha sonra anahtarın ortak bölümünü bir biçime (JSON Web Anahtarı veya PEM ya da başka bir serileştirme biçimi) serileştirir.

Kapanım kodu daha sonra ortak anahtarın SHA256 değerini hesaplar ve bunu bir SGX Alıntısı oluşturan koda giriş olarak geçirir (OpenEnclave için oe_get_evidence veya oe_get_report olabilir).

İstemci daha sonra SGX teklifini ve seri hale getirilmiş anahtarı kanıtlama hizmetine gönderir. Kanıtlama hizmeti teklifi doğrular ve anahtarın karmasının teklifte mevcut olduğundan emin olur ve bir "Kanıtlama Belirteci" yayınlar.

İstemci daha sonra bu Kanıtlama Belirtecini (serileştirilmiş anahtarı içeren) 3. taraf bir "bağlı olan tarafa" gönderebilir. Bağlı olan taraf daha sonra kanıtlama belirtecinin kanıtlama hizmeti tarafından oluşturulduğunu doğrular ve böylece seri hale getirilmiş anahtar hizmete göndermek üzere "bağlı olan taraf" tarafından tutulan bazı verileri şifrelemek için kullanılabilir.

Bu örnekte, bir istekle ilişkilendirilmiş bir kanıtlama belirtecini almak için kanıtlama hizmetine çağrı yapılan yaygın desenlerden biri gösterilmektedir.

Bu örnekte, uç noktanız için Test URI'siyle yapılandırılmış mevcut AttestationClient bir nesneniz olduğu varsayılır. Ayrıca, test ettiğiniz SGX kapanım içinde oluşturulmuş bir OpenEnclave raporunuz (report) ve SGX Teklifinde başvurulan "Çalışma Zamanı Verileri" (binaryRuntimeData) olduğunu varsayar.

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeData: binaryRuntimeData
});

Kanıtlama hizmetine gönderilenin binaryRuntimeData JSON verileri olarak yorumlanması da mümkündür. Bu durumda, istemcinin test API çağrısında belirtmesi runTimeJson gerekir:

const attestationResult = await client.attestOpenEnclave(report, {
  runTimeJson: binaryRuntimeData
});

Benzer şekilde, "teklif" oluşturmak için Intel SDK'sını kullanıyorsanız, şu komutu kullanarak teklifi doğrulayabilirsiniz:

const attestationResult = await client.attestSgxEnclave(quote, {
  runTimeData: binaryRuntimeData
});

Kanıtlama belirteci doğrulamasını gerçekleştirme hakkında ek bilgiler MAA Hizmet Kanıtlama Örneği'nde bulunabilir.

Belirteç Sertifikalarını Alma

Kanıtlama hizmetinden döndürülen belirteci doğrulamak için kullanılabilecek sertifikaları almak için kullanın getSigningCertificates . Bu çağrının Azure kimlik bilgilerine sahip bir istemci oluşturduğunu unutmayın; veya API'lerini çağırıyorsanız attestSgxEnclaveattestOpenEnclave bu gerekli değildir

const credentials = new DefaultAzureCredential();
const client = new AttestationClient(endpoint, {credentials: credentials});

const attestationSigners = await client.getAttestationSigners();

console.log(`There are ${attestationSigners.length} signers`);

Sorun giderme

Çoğu Kanıtlama hizmeti işlemi , Azure Core'da tanımlanan özel durumları tetikler. Kanıtlama hizmeti API'leri yararlı hata kodlarıyla bir RestError hata oluşturur. Bu hataların çoğu kurtarılabilir.

try {
  await client.attestSgxEnclave(openEnclaveReport);
} catch (error) {
  console.log(`Exception thrown for invalid request: ${error.message}`);
}

Günlüğe Kaydetme

Günlüğün etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

MAA hizmeti için ek sorun giderme bilgilerine buradan ulaşabilirsiniz

Sonraki adımlar

Microsoft Azure Doğrulama hizmeti hakkında daha fazla bilgi için lütfen belge sayfamıza bakın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için Katkıda Bulunan Lisans Sözleşmesi sitesini ziyaret edin.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Code of Conduct FAQ (Kullanım Kuralları Hakkında SSS) konusuna bakın veya sorularınızı ya da görüşlerinizi bildirmek için opencode@microsoft.com adresinden bize ulaşın.

Bu kitaplıkları oluşturma, test etme ve bunlara katkıda bulunma hakkında ayrıntılı bilgi için bkz. CONTRIBUTING.md .

Geri Bildirim Sağlama

Herhangi bir hatayla karşılaşırsanız veya önerileriniz varsa, lütfen projenin Sorunlar bölümünde bir sorun oluşturun.

İzlenimler

  • Last updated on