chrome.certificateProvider

설명

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

권한

certificateProvider

가용성

Chrome 46 이상 ChromeOS만 해당

사용

이 API를 사용하여 클라이언트 인증서를 ChromeOS에 노출하는 일반적인 단계는 다음과 같습니다.

  • 확장 프로그램은 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 패딩만 추가해야 합니다. 이 알고리즘은 지원 중단되었으며 Chrome 버전 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

    ArrayBuffer[]

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

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

  • 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에서는 이를 시행하지 않습니다. 대신 고정 요청 수가 초과되면 확장 프로그램에서 stopPinRequest를 errorType = MAX_ATTEMPTS_EXCEEDED로 호출해야 합니다.

  • errorType

    PinRequestErrorType 선택사항

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

  • requestType

    PinRequestType 선택사항

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

  • signRequestId

    숫자

    SignRequest에서 Chrome에 제공한 ID입니다.

SetCertificatesDetails

Chrome 86 이상

속성

  • certificatesRequestId

    번호 선택사항

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

  • clientCertificates

    ClientCertificateInfo[]

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

  • 오류

    "GENERAL_ERROR"
     선택사항

    인증서를 추출하는 중에 발생한 오류입니다(발생한 경우). 이 오류는 적절한 경우 사용자에게 표시됩니다.

SignatureRequest

Chrome 86 이상

속성

  • 알고리즘

    알고리즘

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

  • 증명서

    ArrayBuffer

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

  • 입력

    ArrayBuffer

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

  • signRequestId

    숫자

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

SignRequest

속성

  • 증명서

    ArrayBuffer

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

  • 다이제스트

    ArrayBuffer

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

  • 해시

    해시

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

  • signRequestId

    숫자

    Chrome 57 이상

    확장 프로그램에서 requestPin과 같이 고유 ID가 필요한 메서드를 호출해야 하는 경우 사용할 고유 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 이상

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

requestPin()

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

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

매개변수

반환 값

  • Promise<PinResponseDetails | undefined>

    Chrome 96 이상

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

setCertificates()

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

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

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

매개변수

  • 세부정보

    SetCertificatesDetails

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

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • Promise<void>

    Chrome 96 이상

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

stopPinRequest()

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

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

매개변수

  • 세부정보

    StopPinRequestDetails

    요청 흐름을 중지한 이유에 관한 세부정보를 포함합니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • Promise<void>

    Chrome 96 이상

    Promise는 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

          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

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