chrome.enterprise.platformKeys

توضیحات

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

مجوزها

enterprise.platformKeys

در دسترس بودن

مفاهیم و کاربردها

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

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

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

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

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

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

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

  • اگر گواهی دریافت شد، آن را با استفاده از [ enterprise.platformKeys.importCertificate() `[3] وارد کنید

در اینجا مثالی آورده شده است که تعامل اصلی 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

کروم ۱۱۰+

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

شمارشی

«آر اس ای»

"ای سی دی اس ای"

ChallengeKeyOptions

کروم ۱۱۰+

خواص

  • چالش

    آرایه بافر

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

  • کلید ثبت

    گزینه‌های کلید ثبت ( اختیاری)

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

  • محدوده

    محدوده

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

RegisterKeyOptions

کروم ۱۱۰+

خواص

  • الگوریتم

    الگوریتم

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

Scope

کروم ۱۱۰+

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

شمارشی

"کاربر"

"ماشین"

Token

خواص

  • شناسه

    رشته

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

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

  • نرم‌افزارپشتیبانی‌شدهSubtleCrypto

    سابتل کریپتو

    کروم ۹۷+

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

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

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

  • نامفهوم

    سابتل کریپتو

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

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

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

روش‌ها

challengeKey()

کروم ۱۱۰+
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

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

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

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

پارامترها

بازگشت‌ها

  • قول <ArrayBuffer>

    کروم ۱۳۱+

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

challengeMachineKey()

کروم ۵۰+ از کروم ۱۱۰ منسوخ شده است
 
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

به جای آن challengeKey استفاده کنید.

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

پارامترها

  • چالش

    آرایه بافر

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

  • کلید ثبت

    بولی اختیاری

    کروم ۵۹+

    در صورت تنظیم، کلید ماشین سازمانی فعلی با توکن "system" ثبت می‌شود و نقش کلید ماشین سازمانی را از دست می‌دهد. سپس می‌توان این کلید را با یک گواهی مرتبط کرد و مانند هر کلید امضای دیگری از آن استفاده کرد. این کلید، RSA 2048 بیتی است. فراخوانی‌های بعدی این تابع، یک کلید ماشین سازمانی جدید ایجاد می‌کند.

بازگشت‌ها

  • قول <ArrayBuffer>

    کروم ۱۳۱+

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

challengeUserKey()

کروم ۵۰+ از کروم ۱۱۰ منسوخ شده است
 
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

به جای آن challengeKey استفاده کنید.

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

پارامترها

  • چالش

    آرایه بافر

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

  • کلید ثبت

    بولی

    در صورت تنظیم، کلید کاربر سازمانی فعلی با توکن "user" ثبت می‌شود و نقش کلید کاربر سازمانی را از دست می‌دهد. سپس می‌توان این کلید را با یک گواهی مرتبط کرد و مانند هر کلید امضای دیگری از آن استفاده کرد. این کلید، RSA 2048 بیتی است. فراخوانی‌های بعدی این تابع، یک کلید کاربر سازمانی جدید ایجاد می‌کند.

بازگشت‌ها

  • قول <ArrayBuffer>

    کروم ۱۳۱+

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

getCertificates()

chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
): Promise<ArrayBuffer[]>

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

پارامترها

  • شناسه توکن

    رشته

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

بازگشت‌ها

  • قول <ArrayBuffer[]>

    کروم ۱۳۱+

    یک Promise برمی‌گرداند که با فهرست گواهی‌های موجود مطابقت دارد.

getTokens()

chrome.enterprise.platformKeys.getTokens(): Promise<Token[]>

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

بازگشت‌ها

  • قول< توکن []>

    کروم ۱۳۱+

    توسط getTokens با لیستی از توکن‌های موجود فراخوانی می‌شود.

importCertificate()

chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

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

پارامترها

  • شناسه توکن

    رشته

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

  • گواهی

    آرایه بافر

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

بازگشت‌ها

  • قول<void>

    کروم ۱۳۱+

    یک Promise برمی‌گرداند که پس از اتمام این عملیات، اجرا می‌شود.

removeCertificate()

chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

در صورت وجود، certificate از توکن داده شده حذف می‌کند. باید برای حذف گواهی‌های منسوخ شده استفاده شود تا در هنگام احراز هویت در نظر گرفته نشوند و انتخاب گواهی را شلوغ نکنند. باید برای آزاد کردن فضای ذخیره‌سازی در مخزن گواهی استفاده شود.

پارامترها

  • شناسه توکن

    رشته

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

  • گواهی

    آرایه بافر

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

بازگشت‌ها

  • قول<void>

    کروم ۱۳۱+

    یک Promise برمی‌گرداند که پس از اتمام این عملیات، اجرا می‌شود.