chrome.enterprise.platformKeys

توضیحات

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

مجوزها

enterprise.platformKeys

در دسترس بودن

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

Typical usage of this API to enroll a client certificate follows these steps:

  • Get all available tokens using enterprise.platformKeys.getTokens() .

  • Find the Token with id equal to "user" . Use this Token subsequently.

  • Generate a key pair using the generateKey() Token method (defined in SubtleCrypto). This will return handle to the key.

  • Export the public key using the exportKey() Token method (defined in SubtleCrypto).

  • Create the signature of the certification request's data using the sign() Token method (defined in SubtleCrypto).

  • Complete the certification request and send it to the certification authority.

  • If a certificate is received, import it using [ enterprise.platformKeys.importCertificate() `[3]

Here's an example that shows the major API interaction except the building and sending of the certification request:

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

کروم ۱۱۰+

خواص

  • چالش

    آرایه بافر

    A challenge as emitted by the Verified Access Web API.

  • کلید ثبت

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

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

  • محدوده

    محدوده

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

RegisterKeyOptions

کروم ۱۱۰+

خواص

  • الگوریتم

    الگوریتم

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

Scope

کروم ۱۱۰+

Whether to use the Enterprise User Key or the Enterprise Machine Key.

شمارشی

"کاربر"

"ماشین"

Token

خواص

  • شناسه

    رشته

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

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

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

    سابتل کریپتو

    کروم ۹۷+

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

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

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

  • نامفهوم

    سابتل کریپتو

    Implements the WebCrypto's SubtleCrypto interface. The cryptographic operations, including key generation, are hardware-backed.

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

    کلیدهای تولید شده روی یک 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>

    کروم ۱۳۱+

    Returns a Promise which resolves with the challenge response.

challengeMachineKey()

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

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

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

پارامترها

  • چالش

    آرایه بافر

    A challenge as emitted by the Verified Access Web API.

  • کلید ثبت

    بولی اختیاری

    کروم ۵۹+

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

بازگشت‌ها

  • قول <ArrayBuffer>

    کروم ۱۳۱+

    Returns a Promise which resolves with the challenge response.

challengeUserKey()

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

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

Challenges a hardware-backed Enterprise User Key and emits the response as part of a remote attestation protocol. Only useful on ChromeOS and in conjunction with the Verified Access Web API which both issues challenges and verifies responses. A successful verification by the Verified Access Web API is a strong signal of all of the following: * The current device is a legitimate ChromeOS device. * The current device is managed by the domain specified during verification. * The current signed-in user is managed by the domain specified during verification. * The current device state complies with enterprise user policy. For example, a policy may specify that the device must not be in developer mode. * The public key emitted by the verification is tightly bound to the hardware of the current device and to the current signed-in user. This function is highly restricted and will fail if the current device is not managed, the current user is not managed, or if this operation has not explicitly been enabled for the caller by enterprise user policy. The Enterprise User Key does not reside in the "user" token and is not accessible by any other API.

پارامترها

  • چالش

    آرایه بافر

    A challenge as emitted by the Verified Access Web API.

  • کلید ثبت

    بولی

    If set, the current Enterprise User Key is registered with the "user" token and relinquishes the Enterprise User Key role. The key can then be associated with a certificate and used like any other signing key. This key is 2048-bit RSA. Subsequent calls to this function will then generate a new Enterprise User Key.

بازگشت‌ها

  • قول <ArrayBuffer>

    کروم ۱۳۱+

    Returns a Promise which resolves with the challenge response.

getCertificates()

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

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

پارامترها

  • شناسه توکن

    رشته

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

بازگشت‌ها

  • قول <ArrayBuffer[]>

    کروم ۱۳۱+

    Returns a Promise which resolves with the list of the available certificates.

getTokens()

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

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

بازگشت‌ها

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

    کروم ۱۳۱+

    Invoked by getTokens with the list of available Tokens.

importCertificate()

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

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

پارامترها

  • شناسه توکن

    رشته

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

  • گواهی

    آرایه بافر

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

بازگشت‌ها

  • قول<void>

    کروم ۱۳۱+

    Returns a Promise which resolves when this operation is finished.

removeCertificate()

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

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

پارامترها

  • شناسه توکن

    رشته

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

  • گواهی

    آرایه بافر

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

بازگشت‌ها

  • قول<void>

    کروم ۱۳۱+

    Returns a Promise which resolves when this operation is finished.