chrome.certificateProvider

설명

이 API를 사용하여 TLS 인증에 이러한 인증서를 사용할 수 있는 플랫폼에 인증서를 노출합니다.

권한

certificateProvider

가용성

Chrome 46 이상 에서 확인하세요. ChromeOS만 해당

개념 및 사용법

ChromeOS에 클라이언트 인증서를 노출하기 위해 이 API를 일반적으로 사용하는 방법은 다음과 같습니다.

  • 확장 프로그램은 onCertificatesUpdateRequested 및 onSignatureRequested 이벤트에 등록합니다.
  • 확장 프로그램은 setCertificates()를 호출하여 초기화 후 초기 인증서 목록을 제공합니다.
  • 확장 프로그램은 사용 가능한 인증서 목록의 변경사항을 모니터링하고 setCertificates()를 호출하여 이러한 모든 변경사항을 브라우저에 알립니다.
  • TLS 핸드셰이크 중에 브라우저가 클라이언트 인증서 요청을 수신합니다. onCertificatesUpdateRequested 이벤트가 발생하면 브라우저에서 확장 프로그램에 현재 제공하는 모든 인증서를 보고하도록 요청합니다.
  • 확장 프로그램은 setCertificates() 메서드를 사용하여 현재 사용 가능한 인증서를 보고합니다.
  • 브라우저가 사용 가능한 모든 인증서를 원격 호스트의 클라이언트 인증서 요청과 일치시킵니다. 일치 항목이 선택 대화상자를 통해 사용자에게 표시됩니다.
  • 사용자는 인증서를 선택하고 인증을 승인하거나 취소할 수 있습니다.
를 통해 개인정보처리방침을 정의할 수 있습니다. <ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">인증서 선택 대화상자</ph>
인증서 선택 대화상자
  • 사용자가 인증을 중단하거나 요청과 일치하는 인증서가 없으면 TLS 클라이언트 인증이 중단됩니다.
  • 그렇지 않고 사용자가 이 확장 프로그램에서 제공하는 인증서로 인증을 승인하면 브라우저에서 확장 프로그램에 데이터에 서명하도록 요청하여 TLS 핸드셰이크를 계속합니다. 요청은 onSignatureRequested 이벤트로 전송됩니다.
  • 이 이벤트는 입력 데이터를 포함하고, 서명을 생성하는 데 사용해야 하는 알고리즘을 선언하고, 이 확장 프로그램에서 보고한 인증서 중 하나를 참조합니다. 확장 프로그램은 참조된 인증서와 연결된 비공개 키를 사용하여 지정된 데이터에 대한 서명을 만들어야 합니다. 서명을 만들려면 DigestInfo를 앞에 추가하고 실제 서명 전에 결과를 패딩해야 할 수 있습니다.
  • 확장 프로그램은 reportSignature() 메서드를 사용하여 브라우저에 서명을 다시 보냅니다. 서명을 계산할 수 없는 경우 서명 없이 메서드를 호출해야 합니다.
  • 서명이 제공되면 브라우저에서 TLS 핸드셰이크를 완료합니다.

실제 단계의 순서는 다를 수 있습니다. 예를 들어 인증서를 자동으로 선택하는 엔터프라이즈 정책이 사용되는 경우 사용자에게 인증서를 선택하라는 메시지가 표시되지 않습니다 (AutoSelectCertificateForUrls 및 사용자용 Chrome 정책 참고).

확장 프로그램에서 이 코드는 다음 스니펫과 비슷할 수 있습니다.

function collectAvailableCertificates() {
  // Return all certificates that this Extension can currently provide.
  // For example:
  return [{
    certificateChain: [new Uint8Array(...)],
    supportedAlgorithms: ['RSASSA_PKCS1_v1_5_SHA256']
  }];
}

// The Extension calls this function every time the currently available list of
// certificates changes, and also once after the Extension's initialization.
function onAvailableCertificatesChanged() {
  chrome.certificateProvider.setCertificates({
    clientCertificates: collectAvailableCertificates()
  });
}

function handleCertificatesUpdateRequest(request) {
  // Report the currently available certificates as a response to the request
  // event. This is important for supporting the case when the Extension is
  // unable to detect the changes proactively.
  chrome.certificateProvider.setCertificates({
    certificatesRequestId: request.certificatesRequestId,
    clientCertificates: collectAvailableCertificates()
  });
}

// Returns a private key handle for the given DER-encoded certificate.
// |certificate| is an ArrayBuffer.
function getPrivateKeyHandle(certificate) {...}

// Digests and signs |input| with the given private key. |input| is an
// ArrayBuffer. |algorithm| is an Algorithm.
// Returns the signature as ArrayBuffer.
function signUnhashedData(privateKey, input, algorithm) {...}

function handleSignatureRequest(request) {
  // Look up the handle to the private key of |request.certificate|.
  const key = getPrivateKeyHandle(request.certificate);
  if (!key) {
    // Handle if the key isn't available.
    console.error('Key for requested certificate no available.');

    // Abort the request by reporting the error to the API.
    chrome.certificateProvider.reportSignature({
      signRequestId: request.signRequestId,
      error: 'GENERAL_ERROR'
    });
    return;
  }

  const signature = signUnhashedData(key, request.input, request.algorithm);
  chrome.certificateProvider.reportSignature({
    signRequestId: request.signRequestId,
    signature: signature
  });
}

chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
    handleCertificatesUpdateRequest);
chrome.certificateProvider.onSignatureRequested.addListener(
    handleSignatureRequest);

유형

Algorithm

Chrome 86 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

지원되는 암호화 서명 알고리즘의 유형입니다.

열거형

&quot;RSASSA_PKCS1_v1_5_MD5_SHA1&quot;
MD5-SHA-1 해싱으로 RSASSA PKCS#1 v1.5 서명 알고리즘을 지정합니다. 확장 프로그램은 DigestInfo 접두사를 앞에 추가하지 말고 PKCS#1 패딩만 추가해야 합니다. 이 알고리즘은 지원 중단되었으며 버전 109부터는 Chrome에서 요청하지 않습니다.

&quot;RSASSA_PKCS1_v1_5_SHA1&quot;
SHA-1 해시 함수로 RSASSA PKCS#1 v1.5 서명 알고리즘을 지정합니다.

&quot;RSASSA_PKCS1_v1_5_SHA256&quot;
SHA-256 해싱 함수로 RSASSA PKCS#1 v1.5 서명 알고리즘을 지정합니다.

&quot;RSASSA_PKCS1_v1_5_SHA384&quot;
SHA-384 해싱 함수로 RSASSA PKCS#1 v1.5 서명 알고리즘을 지정합니다.

&quot;RSASSA_PKCS1_v1_5_SHA512&quot;
SHA-512 해싱 함수로 RSASSA PKCS#1 v1.5 서명 알고리즘을 지정합니다.

"RSASSA_PSS_SHA256"
SHA-256 해싱 함수, MGF1 마스크 생성 함수, 해시와 동일한 크기의 솔트를 사용하여 RSASSA PSS 서명 알고리즘을 지정합니다.

"RSASSA_PSS_SHA384"
SHA-384 해싱 함수, MGF1 마스크 생성 함수, 해시와 동일한 크기의 솔트를 사용하여 RSASSA PSS 서명 알고리즘을 지정합니다.

"RSASSA_PSS_SHA512"
SHA-512 해싱 함수, MGF1 마스크 생성 함수, 해시와 동일한 크기의 솔트를 사용하여 RSASSA PSS 서명 알고리즘을 지정합니다.

CertificateInfo

속성

  • 증명서

    배열 버퍼

    X.509 인증서의 DER 인코딩이어야 합니다. 현재 RSA 키의 인증서만 지원됩니다.

  • supportedHashes

    해시[]

    이 인증서에서 지원되는 모든 해시로 설정해야 합니다. 이 확장 프로그램에는 이러한 해시 알고리즘 중 하나로 계산된 다이제스트의 서명만 요청됩니다. 해시 선호도에서 내림차순으로 정렬해야 합니다.

CertificatesUpdateRequest

Chrome 86 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • certificatesRequestId

    숫자

    setCertificates에 전달할 요청 식별자입니다.

ClientCertificateInfo

Chrome 86 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • certificateChain

    ArrayBuffer[]

    배열에는 첫 번째 요소로 X.509 클라이언트 인증서의 DER 인코딩이 포함되어야 합니다.

    정확히 1개의 인증서가 포함되어야 합니다.

  • supportedAlgorithms

    알고리즘[]

    이 인증서에 지원되는 모든 알고리즘입니다. 확장 프로그램에는 이러한 알고리즘 중 하나를 사용하는 서명만 요청됩니다.

Error

Chrome 86 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

확장 프로그램이 보고할 수 있는 오류 유형입니다.

값

'GENERAL_ERROR'

Hash

지원 중단되었습니다. Algorithm로 대체되었습니다.

열거형

"MD5_SHA1"
MD5 및 SHA1 해싱 알고리즘을 지정합니다.

"SHA1"
SHA1 해싱 알고리즘을 지정합니다.

"SHA256"
SHA256 해싱 알고리즘을 지정합니다.

"SHA384"
SHA384 해싱 알고리즘을 지정합니다.

"SHA512"
SHA512 해싱 알고리즘을 지정합니다.

PinRequestErrorType

Chrome 57 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

requestPin 함수를 통해 사용자에게 표시될 수 있는 오류 유형입니다.

열거형

"INVALID_PIN"
PIN이 유효하지 않다고 지정합니다.

"INVALID_PUK"
PUK가 유효하지 않음을 지정합니다.

"MAX_ATTEMPTS_EXCEEDED"
최대 시도 횟수를 초과했음을 나타냅니다.

"UNKNOWN_ERROR"
위의 유형으로 오류를 표시할 수 없음을 지정합니다.

PinRequestType

Chrome 57 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

requestPin 함수를 사용하는 확장 프로그램에서 요청하는 코드 유형입니다.

열거형

'PIN'
요청된 코드가 PIN임을 명시합니다.

'PUK'
요청된 코드가 PUK임을 명시합니다.

PinResponseDetails

Chrome 57 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • userInput

    문자열(선택사항)

    사용자가 제공한 코드입니다. 사용자가 대화상자를 닫았거나 다른 오류가 발생한 경우 비어 있습니다.

ReportSignatureDetails

Chrome 86 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • 오류

    "GENERAL_ERROR"
     선택사항

    서명을 생성하는 동안 발생한 오류입니다(있는 경우).

  • signRequestId

    숫자

    onSignatureRequested 이벤트를 통해 수신된 요청 식별자입니다.

  • 서명

    ArrayBuffer 선택사항

    서명(성공적으로 생성된 경우)

RequestPinDetails

Chrome 57 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • attemptsLeft

    숫자 선택사항

    남은 시도 횟수입니다. 모든 UI에서 사용자에게 이 정보를 표시할 수 있도록 제공됩니다. Chrome은 이를 시행하지 않을 것으로 예상되며, 대신 PIN 요청 수를 초과하면 errorType = MAX_ATTEMPTS_EXCEEDED 확장 프로그램이 StopPinRequest를 호출해야 합니다.

  • errorType

    PinRequestErrorType optional

    사용자에게 표시되는 오류 템플릿입니다. 이전 요청이 실패한 경우 사용자에게 실패 이유를 알리기 위해 설정해야 합니다.

  • requestType

    PinRequestType 선택사항

    요청된 코드의 유형입니다. 기본값은 PIN입니다.

  • signRequestId

    숫자

    SignRequest에서 Chrome이 부여한 ID입니다.

SetCertificatesDetails

Chrome 86 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • certificatesRequestId

    숫자 선택사항

    onCertificatesUpdateRequested에 대한 응답으로 호출될 때는 수신된 certificatesRequestId 값을 포함해야 합니다. 그 외의 경우에는 설정을 해제해야 합니다.

  • clientCertificates

    ClientCertificateInfo[]

    현재 사용 가능한 클라이언트 인증서 목록입니다.

  • 오류

    "GENERAL_ERROR"
     선택사항

    인증서를 추출하는 중에 오류가 발생했습니다(있는 경우). 이 오류는 필요한 경우 사용자에게 표시됩니다.

SignatureRequest

Chrome 86 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • 알고리즘

    알고리즘

    사용할 서명 알고리즘입니다.

  • 증명서

    배열 버퍼

    X.509 인증서의 DER 인코딩입니다. 확장 프로그램은 연결된 비공개 키를 사용하여 input에 서명해야 합니다.

  • 입력

    배열 버퍼

    서명할 데이터입니다. 데이터는 해싱되지 않습니다.

  • signRequestId

    숫자

    reportSignature에 전달할 요청 식별자입니다.

SignRequest

속성

  • 증명서

    배열 버퍼

    X.509 인증서의 DER 인코딩입니다. 확장 프로그램은 연결된 비공개 키를 사용하여 digest에 서명해야 합니다.

  • 다이제스트

    배열 버퍼

    서명해야 하는 다이제스트입니다.

  • 해시

    해시

    digest를 만드는 데 사용된 해시 알고리즘을 나타냅니다.

  • signRequestId

    숫자

    Chrome 57 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    확장 프로그램이 이를 필요로 하는 메서드를 호출해야 하는 경우 확장 프로그램에서 사용할 고유 ID입니다. 예: requestPin입니다.

StopPinRequestDetails

Chrome 57 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

속성

  • errorType

    PinRequestErrorType optional

    오류 템플릿입니다. 있는 경우 사용자에게 표시됩니다. 오류 등으로 인해 흐름을 중지하는 이유를 포함하기 위한 용도입니다(예: MAX_ATTEMPTS_EXCEEDED개

  • signRequestId

    숫자

    SignRequest에서 Chrome이 부여한 ID입니다.

메서드

reportSignature()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 86 이상 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

onSignatureRequested에 대한 응답으로 호출되어야 합니다.

확장 프로그램은 결국 onSignatureRequested 이벤트마다 이 함수를 호출해야 합니다. 잠시 후 API 구현에서 이 호출에 대한 대기를 중지하고 이 함수가 호출되면 시간 제한 오류를 반환합니다.

매개변수

  • 세부정보

    ReportSignatureDetails

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 프로미스<void>

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

requestPin()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 57 이상 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

사용자에게 PIN을 요청합니다. 진행 중인 요청은 한 번에 하나만 허용됩니다. 다른 흐름이 진행되는 동안 발생한 요청은 거부됩니다. 다른 흐름이 진행 중인 경우 나중에 다시 시도하는 것은 확장 프로그램의 책임입니다.

매개변수

반환 값

  • Promise&lt;PinResponseDetails | 정의되지 않음>

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

setCertificates()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 86 이상 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

브라우저에서 사용할 인증서 목록을 설정합니다.

확장 프로그램은 초기화 후 그리고 현재 사용 가능한 인증서 세트가 변경될 때마다 이 함수를 호출해야 합니다. 또한 확장 프로그램은 이 이벤트가 수신될 때마다 onCertificatesUpdateRequested에 대한 응답으로 이 함수를 호출해야 합니다.

매개변수

  • 세부정보

    SetCertificatesDetails

    설정할 인증서입니다. 잘못된 인증서는 무시됩니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 프로미스<void>

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

stopPinRequest()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 57 이상 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

requestPin 함수에서 시작한 PIN 요청을 중지합니다.

매개변수

  • 세부정보

    StopPinRequestDetails

    요청 흐름을 중지하는 이유에 대한 세부정보가 포함되어 있습니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • 프로미스<void>

    Chrome 96 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

이벤트

onCertificatesRequested

Chrome 47 이상 에서 확인하세요. &amp;leq; MV2 Chrome 86 이후 지원 중단됨
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

대신 onCertificatesUpdateRequested를 사용하세요.

이 이벤트는 브라우저에서 이 확장 프로그램에서 제공하는 현재 인증서 목록을 요청할 때마다 실행됩니다. 확장 프로그램은 현재 인증서 목록으로 reportCallback를 정확히 한 번 호출해야 합니다.

매개변수

  • 콜백

    함수

    callback 매개변수는 다음과 같습니다. 

    (reportCallback: function) => void

    • reportCallback

      함수

      reportCallback 매개변수는 다음과 같습니다. 

      (certificates: CertificateInfo[], callback: function) => void

      • certificates

        CertificateInfo[]

      • 콜백

        함수

        callback 매개변수는 다음과 같습니다. 

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

이 이벤트는 setCertificates를 통해 설정된 인증서가 충분하지 않거나 브라우저에서 업데이트된 정보를 요청하는 경우 실행됩니다. 확장 프로그램은 업데이트된 인증서 목록과 수신된 certificatesRequestId로 setCertificates를 호출해야 합니다.

매개변수

onSignatureRequested

Chrome 86 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

이 이벤트는 브라우저에서 setCertificates를 통해 이 확장 프로그램에서 제공하는 인증서를 사용하여 메시지에 서명해야 할 때마다 실행됩니다.

확장 프로그램은 적절한 알고리즘과 비공개 키를 사용하여 request의 입력 데이터에 서명하고 수신된 signRequestId로 reportSignature를 호출하여 이를 반환해야 합니다.

매개변수

onSignDigestRequested

<ph type="x-smartling-placeholder"></ph> &amp;leq; MV2 Chrome 86 이후 지원 중단됨
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

대신 onSignatureRequested를 사용하세요.

이 이벤트는 브라우저가 onCertificatesRequested 이벤트에 대한 응답으로 이 확장 프로그램에서 제공하는 인증서를 사용하여 메시지에 서명해야 할 때마다 실행됩니다. 확장 프로그램은 적절한 알고리즘과 비공개 키를 사용하여 request의 데이터에 서명하고 reportCallback를 호출하여 반환해야 합니다. reportCallback는 정확히 한 번만 호출되어야 합니다.

매개변수

  • 콜백

    함수

    callback 매개변수는 다음과 같습니다. 

    (request: SignRequest, reportCallback: function) => void

    • 요청

      SignRequest

    • reportCallback

      함수

      Chrome 47 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

      reportCallback 매개변수는 다음과 같습니다. 

      (signature?: ArrayBuffer) => void

      • 서명

        ArrayBuffer 선택사항