chrome.enterprise.platformKeys

توضیحات

از 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() «[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

Chrome 110+

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

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110+

خواص

  • چالش

    ArrayBuffer

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

  • registerKey

    RegisterKeyOptions اختیاری است

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

  • دامنه

    دامنه

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

RegisterKeyOptions

Chrome 110+

خواص

  • الگوریتم

    الگوریتم

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

Scope

Chrome 110+

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

Enum

"کاربر"

"ماشین"

Token

خواص

  • شناسه

    رشته

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

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97+

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

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

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

  • subtleCrypto

    SubtleCrypto

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

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

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

روش ها

challengeKey()

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

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

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

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

پارامترها

  • گزینه ها

    ChallengeKeyOptions

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (response: ArrayBuffer) => void

    • پاسخ

      ArrayBuffer

      پاسخ به چالش

برمی گرداند

  • Promise<ArrayBuffer>

    Chrome 131+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

challengeMachineKey()

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

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

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

پارامترها

  • چالش

    ArrayBuffer

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

  • registerKey

    بولی اختیاری

    Chrome 59+

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (response: ArrayBuffer) => void

    • پاسخ

      ArrayBuffer

      پاسخ به چالش

برمی گرداند

  • Promise<ArrayBuffer>

    Chrome 131+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

challengeUserKey()

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

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

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

پارامترها

  • چالش

    ArrayBuffer

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

  • registerKey

    بولی

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (response: ArrayBuffer) => void

    • پاسخ

      ArrayBuffer

      پاسخ چالش

برمی گرداند

  • Promise<ArrayBuffer>

    Chrome 131+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getCertificates()

قول بده
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
)

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

پارامترها

  • شناسه توکن

    رشته

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (certificates: ArrayBuffer[]) => void

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

      ArrayBuffer[]

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

برمی گرداند

  • Promise<ArrayBuffer[]>

    Chrome 131+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getTokens()

قول بده
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

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

پارامترها

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (tokens: Token[]) => void

    • توکن ها

      رمز []

      لیست توکن های موجود

برمی گرداند

  • وعده< نشانه []>

    Chrome 131+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

importCertificate()

قول بده
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

پارامترها

  • شناسه توکن

    رشته

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

  • گواهی

    ArrayBuffer

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 131+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

removeCertificate()

قول بده
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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

پارامترها

  • شناسه توکن

    رشته

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

  • گواهی

    ArrayBuffer

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    () => void

برمی گرداند

  • قول<باطل>

    Chrome 131+

    Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.