chrome.enterprise.platformKeys

refresh date: 2026-09-25 robots: noindex

شرح

از chrome.enterprise.platformKeys API برای تولید کلیدها و نصب گواهینامه‌ها برای این کلیدها استفاده کنید. گواهینامه‌ها توسط پلاتفرم مدیریت خواهند شد و می‌توانند برای اصالت‌سنجی TLS، دسترسی به شبکه، یا توسط افزونه‌های دیگر ازطریق chrome.platformKeys استفاده شوند.

اجازه‌ها

enterprise.platformKeys

دردسترس بودن

کاربرد

استفاده معمول از این API برای ثبت گواهینامه کارخواه این مراحل را دنبال می‌کند:

  • بااستفاده از enterprise.platformKeys.getTokens، همه توکن‌های دردسترس را دریافت کنید.

  • توکن با id برابر با "user" را پیدا کنید. از این «نشان» متعاقباً استفاده کنید.

  • جفت کلید را بااستفاده از روش generateKey Token (تعریف‌شده در SubtleCrypto) تولید کنید. با این کار، دسته به کلید برمی‌گردد.

  • کلید عمومی را بااستفاده از روش exportKey Token (تعریف‌شده در SubtleCrypto) صادر کنید.

  • امضای داده‌های درخواست گواهی را بااستفاده از روش sign Token (تعریف‌شده در SubtleCrypto) ایجاد کنید.

  • درخواست گواهینامه را تکمیل کنید و آن را به مرجع صدور گواهینامه ارسال کنید.

  • اگر گواهینامه‌ای دریافت شد، آن را بااستفاده از enterprise.platformKeys.importCertificate وارد کنید

در اینجا مثالی آورده شده است که تعامل اصلی API را به‌جز ساختن و ارسال درخواست گواهینامه نشان می‌دهد:

function getUserToken(callback) {
  chrome.enterprise.platformKeys.getTokens(function(tokens) {
    for (var i = 0; i < tokens.length; i++) {
      if (tokens[i].id == "user") {
        callback(tokens[i]);
        return;
      }
    }
    callback(undefined);
  });
}

function generateAndSign(userToken) {
  var data = new Uint8Array([0, 5, 1, 2, 3, 4, 5, 6]);
  var algorithm = {
    name: "RSASSA-PKCS1-v1_5",
    // RsaHashedKeyGenParams
    modulusLength: 2048,
    publicExponent:
        new Uint8Array([0x01, 0x00, 0x01]),  // Equivalent to 65537
    hash: {
      name: "SHA-256",
    }
  };
  var cachedKeyPair;
  userToken.subtleCrypto.generateKey(algorithm, false, ["sign"])
    .then(function(keyPair) {
            cachedKeyPair = keyPair;
            return userToken.subtleCrypto.exportKey("spki", keyPair.publicKey);
          },
          console.log.bind(console))
    .then(function(publicKeySpki) {
            // Build the Certification Request using the public key.
            return userToken.subtleCrypto.sign(
                {name : "RSASSA-PKCS1-v1_5"}, cachedKeyPair.privateKey, data);
          },
          console.log.bind(console))
    .then(function(signature) {
              // Complete the Certification Request with |signature|.
              // Send out the request to the CA, calling back
              // onClientCertificateReceived.
          },
          console.log.bind(console));
}

function onClientCertificateReceived(userToken, certificate) {
  chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

انواع

Algorithm

Chrome نسخه ۱۱۰ به بالا

نوع کلید برای تولید.

شمارشی

«RSA»

«ECDSA»

ChallengeKeyOptions

Chrome نسخه ۱۱۰ به بالا

مشخصات

  • چالش

    ArrayBuffer

    چالشی که توسط Verified Access Web API صادر شده است.

  • registerKey

    RegisterKeyOptions اختیاری

    درصورت وجود، کلید چالش را با کد scope مشخص‌شده ثبت می‌کند. سپس می‌توان کلید را با گواهینامه‌ای مرتبط کرد و مانند هر کلید امضای دیگری از آن استفاده کرد. فراخوانی‌های بعدی این تابع سپس «کلید سازمانی» جدیدی در scope مشخص‌شده تولید خواهد کرد.

  • محدوده

    Scope

    کدام کلید سازمانی برای چالش.

RegisterKeyOptions

Chrome نسخه ۱۱۰ به بالا

مشخصات

  • الگوریتم

    الگوریتم

    کدام الگوریتم باید از کلید ثبت‌شده استفاده کند.

Scope

Chrome نسخه ۱۱۰ به بالا

اینکه از «کلید کاربر سازمانی» استفاده شود یا «کلید دستگاه سازمانی».

شمارشی

«USER»

«ماشین»

Token

مشخصات

  • id

    رشته

    این Token را به‌طور منحصربه‌فرد شناسایی می‌کند.

    شناسه‌های ایستا "user" و "system" هستند که به‌ترتیب به شناسه سخت‌افزاری مختص کاربر پلاتفرم و شناسه سخت‌افزاری سراسری سیستم اشاره دارند. ممکن است enterprise.platformKeys.getTokens هرگونه توکن دیگری (با شناسه‌های دیگر) را برگرداند.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome نسخه ۹۷ به بالا

    میانای SubtleCrypto مربوط به WebCrypto را پیاده‌سازی می‌کند. عملیات رمزنگاری، ازجمله تولید کلید، با پشتیبانی نرم‌افزاری انجام می‌شود. محافظت از کلیدها و درنتیجه پیاده‌سازی ویژگی غیرقابل‌استخراج در نرم‌افزار انجام می‌شود، بنابراین کلیدها نسبت‌به کلیدهای با پشتوانه سخت‌افزاری کمتر محافظت می‌شوند.

    فقط کلیدهای غیرقابل‌استخراج را می‌توان تولید کرد. تنها نوع کلید پشتیبانی‌شده RSASSA-PKCS1-V1_5 با modulusLength تا ۲۰۴۸ است. هر کلید را می‌توان حداکثر یک‌بار برای امضای داده‌ها استفاده کرد، مگراینکه افزونه ازطریق خط‌مشی KeyPermissions در فهرست مجاز قرار گرفته باشد که در این صورت می‌توان از کلید به‌طور نامحدود استفاده کرد.

    کلیدهای تولیدشده در یک Token خاص را نمی‌توان با هیچ «کد» دیگری استفاده کرد، همچنین نمی‌توان آن‌ها را با window.crypto.subtle استفاده کرد. به‌طور مشابه، از اشیای Key ایجادشده با window.crypto.subtle نمی‌توان در این میانای کاربری استفاده کرد.

  • subtleCrypto

    SubtleCrypto

    میانای SubtleCrypto مربوط به WebCrypto را پیاده‌سازی می‌کند. عملیات رمزنگاری، ازجمله تولید کلید، با پشتیبانی سخت‌افزاری انجام می‌شود.

    فقط کلیدهای غیرقابل‌استخراج را می‌توان تولید کرد. انواع کلیدهای پشتیبانی‌شده عبارت‌اند از RSASSA-PKCS1-V1_5 با modulusLength تا ۲۰۴۸ و ECDSA با namedCurve P-256. هر کلید را می‌توان حداکثر یک‌بار برای امضای داده‌ها استفاده کرد، مگراینکه افزونه توسط خط‌مشی KeyPermissions در فهرست مجاز قرار گرفته باشد که در این صورت می‌توان از کلید به‌طور نامحدود استفاده کرد.

    کلیدهای تولیدشده در یک Token خاص را نمی‌توان با هیچ «کد» دیگری استفاده کرد، همچنین نمی‌توان آن‌ها را با window.crypto.subtle استفاده کرد. به‌طور مشابه، از اشیای Key ایجادشده با window.crypto.subtle نمی‌توان در این میانای کاربری استفاده کرد.

روش‌ها

challengeKey()

Promise Chrome 110+ 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
): Promise<ArrayBuffer>

شبیه به challengeMachineKey و challengeUserKey، اما امکان مشخص کردن الگوریتم کلید ثبت‌شده را فراهم می‌کند. یک «کلید سازمانی سخت‌افزاری» را به‌چالش می‌کشد و پاسخ را به‌عنوان بخشی از پروتکل گواهی از راه دور صادر می‌کند. فقط در ChromeOS و در ارتباط با Verified Access Web API (میانای برنامه‌سازی کاربردی وب دسترسی درستی‌سنجی‌شده) مفید است که هم چالش‌ها را صادر می‌کند و هم پاسخ‌ها را درستی‌سنجی می‌کند.

درستی‌سنجی موفقیت‌آمیز توسط Verified Access Web API نشانه‌ای قوی است از اینکه دستگاه فعلی یک دستگاه ChromeOS قانونی است، دستگاه فعلی توسط دامنه‌ای که درطول درستی‌سنجی مشخص شده است مدیریت می‌شود، کاربر فعلی واردشده به سیستم توسط دامنه‌ای که درطول درستی‌سنجی مشخص شده است مدیریت می‌شود، و وضعیت دستگاه فعلی با خط‌مشی دستگاه سازمانی مطابقت دارد. برای مثال، خط‌مشی ممکن است مشخص کند که دستگاه نباید در حالت توسعه‌دهنده باشد. هر شناسه دستگاهی که از درستی‌سنجی صادر می‌شود، به‌طور محکم به سخت‌افزار دستگاه فعلی متصل است. اگر "user" Scope مشخص شده باشد، هویت نیز به‌طور محکم به کاربر واردشده فعلی متصل می‌شود.

این عملکرد بسیار محدود است و اگر دستگاه فعلی مدیریت نشود، کاربر فعلی مدیریت نشود، یا اگر این عملیات به‌طور صریح برای تماس‌گیرنده توسط خط‌مشی دستگاه سازمانی فعال نشده باشد، ناموفق خواهد بود. کلید چالش در توکن "system" یا "user" قرار ندارد و ازطریق هیچ میانای برنامه‌سازی کاربردی دیگری قابل‌دسترسی نیست.

پارامترها

  • گزینه‌ها

    ChallengeKeyOptions

    شیء حاوی فیلدهای تعریف‌شده در ChallengeKeyOptions.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (response: ArrayBuffer) => void

    • پاسخ

      ArrayBuffer

      پاسخ چالش.

بازگشتی‌ها

  • Promise<ArrayBuffer>

    Chrome نسخه ۱۳۱ و بالاتر

    یک Promise برمی‌گرداند که با پاسخ چالش حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

challengeMachineKey()

Promise Chrome 50+ از Chrome 110 منسوخ شده است
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
): Promise<ArrayBuffer>

درعوض از challengeKey استفاده کنید.

یک «کلید سازمانی سخت‌افزاری» را به‌چالش می‌کشد و پاسخ را به‌عنوان بخشی از پروتکل گواهی از راه دور صادر می‌کند. فقط در ChromeOS و در ارتباط با Verified Access Web API (میانای برنامه‌سازی کاربردی وب دسترسی درستی‌سنجی‌شده) مفید است که هم چالش‌ها را صادر می‌کند و هم پاسخ‌ها را درستی‌سنجی می‌کند. درستی‌سنجی موفقیت‌آمیز توسط Verified Access Web API نشانه‌ای قوی از همه موارد زیر است: * دستگاه فعلی یک دستگاه ChromeOS قانونی است. * دستگاه فعلی توسط دامنه‌ای که درطول درستی‌سنجی مشخص شده است مدیریت می‌شود. * کاربر فعلی واردشده به سیستم توسط دامنه‌ای که درطول درستی‌سنجی مشخص شده است مدیریت می‌شود. * وضعیت فعلی دستگاه با خط‌مشی دستگاه سازمانی مطابقت دارد. برای مثال، خط‌مشی ممکن است مشخص کند که دستگاه نباید در حالت توسعه‌دهنده باشد. * هر شناسه دستگاهی که از درستی‌سنجی صادر می‌شود، به‌طور محکم به سخت‌افزار دستگاه فعلی متصل است. این عملکرد بسیار محدود است و اگر دستگاه فعلی مدیریت نشود، کاربر فعلی مدیریت نشود، یا اگر این عملیات به‌طور صریح برای تماس‌گیرنده توسط خط‌مشی دستگاه سازمانی فعال نشده باشد، ناموفق خواهد بود. «کلید ماشین سازمانی» در کد امنیتی "system" قرار ندارد و هیچ میانای برنامه‌سازی کاربردی دیگری نمی‌تواند به آن دسترسی داشته باشد.

پارامترها

  • چالش

    ArrayBuffer

    چالشی که توسط Verified Access Web API صادر شده است.

  • registerKey

    بولی اختیاری

    Chrome نسخه ۵۹ و بالاتر

    اگر تنظیم شود، «کلید دستگاه سازمانی» فعلی با کد "system" ثبت می‌شود و نقش «کلید دستگاه سازمانی» را واگذار می‌کند. سپس می‌توان کلید را با گواهینامه‌ای مرتبط کرد و مانند هر کلید امضای دیگری از آن استفاده کرد. این کلید RSA‏ ۲۰۴۸ بیتی است. فراخوانی‌های بعدی این تابع، «کلید ماشین سازمانی» جدیدی تولید خواهد کرد.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (response: ArrayBuffer) => void

    • پاسخ

      ArrayBuffer

      پاسخ چالش.

بازگشتی‌ها

  • Promise<ArrayBuffer>

    Chrome نسخه ۱۳۱ و بالاتر

    یک Promise برمی‌گرداند که با پاسخ چالش حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

challengeUserKey()

Promise Chrome 50+ از Chrome 110 منسوخ شده است
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
): Promise<ArrayBuffer>

درعوض از challengeKey استفاده کنید.

یک «کلید کاربر سازمانی» با پشتیبانی سخت‌افزاری را به‌چالش می‌کشد و پاسخ را به‌عنوان بخشی از پروتکل گواهی از راه دور صادر می‌کند. فقط در ChromeOS و در ارتباط با Verified Access Web API (میانای برنامه‌سازی کاربردی وب دسترسی درستی‌سنجی‌شده) مفید است که هم چالش‌ها را صادر می‌کند و هم پاسخ‌ها را درستی‌سنجی می‌کند. درستی‌سنجی موفقیت‌آمیز توسط Verified Access Web API نشانه‌ای قوی از همه موارد زیر است: * دستگاه فعلی یک دستگاه ChromeOS قانونی است. * دستگاه فعلی توسط دامنه‌ای که درطول درستی‌سنجی مشخص شده است مدیریت می‌شود. * کاربر فعلی واردشده به سیستم توسط دامنه‌ای که درطول درستی‌سنجی مشخص شده است مدیریت می‌شود. * وضعیت فعلی دستگاه با خط‌مشی کاربر سازمانی مطابقت دارد. برای مثال، خط‌مشی ممکن است مشخص کند که دستگاه نباید در حالت توسعه‌دهنده باشد. * کلید عمومی صادرشده توسط درستی‌سنجی به‌طور محکم به سخت‌افزار دستگاه فعلی و کاربر واردشده به سیستم فعلی متصل است. این عملکرد بسیار محدود است و اگر دستگاه فعلی مدیریت نشود، کاربر فعلی مدیریت نشود، یا اگر این عملیات به‌طور صریح برای تماس‌گیرنده توسط خط‌مشی کاربر سازمانی فعال نشده باشد، ناموفق خواهد بود. «کلید کاربر سازمانی» در توکن "user" قرار ندارد و ازطریق هیچ میانای برنامه‌سازی کاربردی دیگری قابل‌دسترسی نیست.

پارامترها

  • چالش

    ArrayBuffer

    چالشی که توسط Verified Access Web API صادر شده است.

  • registerKey

    بولی

    اگر تنظیم شود، «کلید کاربر سازمانی» فعلی با کد "user" ثبت می‌شود و نقش «کلید کاربر سازمانی» را واگذار می‌کند. سپس می‌توان کلید را با گواهینامه‌ای مرتبط کرد و مانند هر کلید امضای دیگری از آن استفاده کرد. این کلید RSA‏ ۲۰۴۸ بیتی است. فراخوانی‌های بعدی این تابع سپس «کلید کاربر سازمانی» جدیدی تولید خواهد کرد.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (response: ArrayBuffer) => void

    • پاسخ

      ArrayBuffer

      پاسخ چالش.

بازگشتی‌ها

  • Promise<ArrayBuffer>

    Chrome نسخه ۱۳۱ و بالاتر

    یک Promise برمی‌گرداند که با پاسخ چالش حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getCertificates()

قول 
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
): Promise<ArrayBuffer[]>

فهرست همه گواهینامه‌های کارخواه دردسترس از کد داده‌شده را برمی‌گرداند. می‌تواند برای بررسی وجود و انقضای گواهینامه‌های کارخواه که برای اصالت‌سنجی خاصی قابل‌استفاده هستند استفاده شود.

پارامترها

  • tokenId

    رشته

    شناسه «کد» برگردانده‌شده توسط getTokens.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (certificates: ArrayBuffer[]) => void

    • گواهینامه‌ها

      ArrayBuffer[]

      فهرست گواهینامه‌ها، هرکدام در کدبندی DER گواهینامه X.509.

بازگشتی‌ها

  • Promise<ArrayBuffer[]>

    Chrome نسخه ۱۳۱ و بالاتر

    یک Promise برمی‌گرداند که با فهرست گواهینامه‌های دردسترس حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getTokens()

قول 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
): Promise<Token[]>

«نشان‌های» دردسترس را برمی‌گرداند. در جلسه کاربر عادی، این فهرست همیشه حاوی کد کاربر با id "user" خواهد بود. اگر یک کد TPM در سطح سیستم دردسترس باشد، فهرست برگردانده‌شده حاوی کد در سطح سیستم با id "system" نیز خواهد بود. نشان سراسری سیستم برای همه جلسه‌ها در این دستگاه (دستگاه به‌معنای مثلاً Chromebook) یکسان خواهد بود.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (tokens: Token[]) => void

    • داده‌واحدها

      کد[]

      فهرست کدهای دردسترس.

بازگشتی‌ها

  • Promise<Token[]>

    Chrome نسخه ۱۳۱ و بالاتر

    توسط getTokens با فهرست کدهای دردسترس فراخوانده شد.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

importCertificate()

قول 
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
): Promise<void>

اگر کلید گواهی‌شده قبلاً در این کد ذخیره شده باشد، certificate را به کد داده‌شده وارد می‌کند. پس‌از درخواست موفقیت‌آمیز گواهی، این عملکرد باید برای ذخیره گواهی دریافت‌شده و دردسترس قرار دادن آن برای سیستم‌عامل و مرورگر جهت اصالت‌سنجی استفاده شود.

پارامترها

  • tokenId

    رشته

    شناسه «کد» برگردانده‌شده توسط getTokens.

  • گواهی‌نامه

    ArrayBuffer

    کدگذاری DER گواهی X.509.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۳۱ و بالاتر

    یک Promise برمی‌گرداند که وقتی این عملیات تمام شد حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

removeCertificate()

قول 
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
): Promise<void>

‫certificate را از کد داده‌شده (درصورت وجود) برمی‌دارد. باید برای برداشتن گواهینامه‌های منسوخ استفاده شود تا درطول اصالت‌سنجی درنظر گرفته نشوند و انتخاب گواهینامه را به‌هم نریزند. باید برای آزاد کردن فضای ذخیره‌سازی در مخزن گواهی استفاده شود.

پارامترها

  • tokenId

    رشته

    شناسه «کد» برگردانده‌شده توسط getTokens.

  • گواهی‌نامه

    ArrayBuffer

    کدگذاری DER گواهی X.509.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    () => void

بازگشتی‌ها

  • Promise<void>

    Chrome نسخه ۱۳۱ و بالاتر

    یک Promise برمی‌گرداند که وقتی این عملیات تمام شد حل می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.