chrome.certificateProvider

설명

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

권한

certificateProvider

지원 대상

Chrome 46 이상 ChromeOS만 해당

개념 및 사용법

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

  • 확장 프로그램은 onCertificatesUpdateRequested 및 onSignatureRequested 이벤트를 등록합니다.
  • 확장 프로그램은 setCertificates()를 호출하여 초기화 후 초기 인증서 목록을 제공합니다.
  • 확장 프로그램은 사용 가능한 인증서 목록의 변경사항을 모니터링하고 setCertificates()를 호출하여 이러한 모든 변경사항에 관해 브라우저에 알립니다.
  • TLS 핸드셰이크 중에 브라우저가 클라이언트 인증서 요청을 수신합니다. onCertificatesUpdateRequested 이벤트를 사용하면 브라우저에서 현재 제공하는 모든 인증서를 보고하도록 확장 프로그램에 요청합니다.
  • 확장 프로그램은 setCertificates() 메서드를 사용하여 현재 사용 가능한 인증서로 다시 보고합니다.
  • 브라우저는 사용 가능한 모든 인증서를 원격 호스트의 클라이언트 인증서 요청과 일치시킵니다. 일치하는 항목이 선택 대화상자에서 사용자에게 표시됩니다.
  • 사용자는 인증서를 선택하여 인증을 승인하거나 인증을 중단할 수 있습니다.
인증서 선택 대화상자
인증서 선택 대화상자
  • 사용자가 인증을 중단하거나 요청과 일치하는 인증서가 없으면 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 이상

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

열거형

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

"RSASSA_PKCS1_v1_5_SHA1"
SHA-1 해시 함수가 있는 RSASSA PKCS#1 v1.5 서명 알고리즘을 지정합니다.

"RSASSA_PKCS1_v1_5_SHA256"
SHA-256 해싱 함수가 있는 RSASSA PKCS#1 v1.5 서명 알고리즘을 지정합니다.

"RSASSA_PKCS1_v1_5_SHA384"
SHA-384 해싱 함수가 있는 RSASSA PKCS#1 v1.5 서명 알고리즘을 지정합니다.

"RSASSA_PKCS1_v1_5_SHA512"
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

속성

  • 증명서

    ArrayBuffer

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

  • supportedHashes

    해시[]

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

CertificatesUpdateRequest

Chrome 86 이상

속성

  • certificatesRequestId

    숫자

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

ClientCertificateInfo

Chrome 86 이상

속성

  • certificateChain

    배열 버퍼[]

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

    여기에는 정확히 하나의 인증서가 포함되어야 합니다.

  • supportedAlgorithms

    알고리즘[]

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

Error

Chrome 86 이상

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

값

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 이상

속성

  • error

     선택사항

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

  • signRequestId

    숫자

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

  • 서명

    ArrayBuffer 선택사항

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

RequestPinDetails

Chrome 57 이상

속성

  • attemptsLeft

    number 선택사항

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

  • errorType

    PinRequestErrorType 선택사항

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

  • requestType

    PinRequestType 선택사항

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

  • signRequestId

    숫자

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

SetCertificatesDetails

Chrome 86 이상

속성

  • certificatesRequestId

    number 선택사항

    onCertificatesUpdateRequested에 대한 응답으로 호출될 때 수신된 certificatesRequestId 값을 포함해야 합니다. 그렇지 않으면 설정을 해제해야 합니다.

  • clientCertificates

    ClientCertificateInfo[]

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

  • error

     선택사항

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

SignatureRequest

Chrome 86 이상

속성

  • 알고리즘

    알고리즘

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

  • 증명서

    ArrayBuffer

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

  • 입력

    ArrayBuffer

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

  • signRequestId

    숫자

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

SignRequest

속성

  • 증명서

    ArrayBuffer

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

  • 다이제스트

    ArrayBuffer

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

  • 해시

    해시

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

  • signRequestId

    숫자

    Chrome 57 이상

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

StopPinRequestDetails

Chrome 57 이상

속성

  • errorType

    PinRequestErrorType 선택사항

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

  • signRequestId

    숫자

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

방법

reportSignature()

Promise Chrome 86 이상 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

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

확장 프로그램은 결국 모든 onSignatureRequested 이벤트에 대해 이 함수를 호출해야 합니다. API 구현은 시간이 경과한 후 이 호출 대기를 중지하고 이 함수가 호출될 때 시간 초과 오류를 반환합니다.

매개변수

  • 세부정보

    ReportSignatureDetails

  • 콜백

    함수 선택사항

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

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

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

requestPin()

Promise Chrome 57 이상 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

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

매개변수

반환 값

  • 프로미스<PinResponseDetails|undefined>

    Chrome 96 이상

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

setCertificates()

Promise Chrome 86 이상 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

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

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

매개변수

  • 세부정보

    SetCertificatesDetails

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

  • 콜백

    함수 선택사항

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

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

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

stopPinRequest()

Promise Chrome 57 이상 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

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

매개변수

  • 세부정보

    StopPinRequestDetails

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

  • 콜백

    함수 선택사항

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

    ()=>void

반환 값

  • Promise<void>

    Chrome 96 이상

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

이벤트

onCertificatesRequested

Chrome 47 이상 &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

          배열 버퍼[]

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

&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 선택사항