설명
이 API를 사용하여 TLS 인증에 이러한 인증서를 사용할 수 있는 플랫폼에 인증서를 노출합니다.
권한
certificateProvider가용성
개념 및 사용
이 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
지원되는 암호화 서명 알고리즘 유형
열거형
"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
속성
-
certificatesRequestId
숫자
setCertificates에 전달할 요청 식별자입니다.
ClientCertificateInfo
속성
-
certificateChain
ArrayBuffer[]
배열은 X.509 클라이언트 인증서의 DER 인코딩을 첫 번째 요소로 포함해야 합니다.
여기에는 인증서가 정확히 하나 포함되어야 합니다.
-
supportedAlgorithms
알고리즘[]
이 인증서에 지원되는 모든 알고리즘입니다. 확장 프로그램에는 이러한 알고리즘 중 하나를 사용하여 서명하도록 요청됩니다.
Error
확장 프로그램에서 보고할 수 있는 오류 유형입니다.
값
'GENERAL_ERROR'
Hash
지원 중단되었습니다. Algorithm로 대체되었습니다.
열거형
"MD5_SHA1"
MD5 및 SHA1 해싱 알고리즘을 지정합니다.
'SHA1'
SHA1 해싱 알고리즘을 지정합니다.
'SHA256'
SHA256 해싱 알고리즘을 지정합니다.
"SHA384"
SHA384 해싱 알고리즘을 지정합니다.
'SHA512'
SHA512 해싱 알고리즘을 지정합니다.
PinRequestErrorType
requestPin 함수를 통해 사용자에게 표시할 수 있는 오류 유형입니다.
열거형
"INVALID_PIN"
PIN이 잘못되었음을 지정합니다.
"INVALID_PUK"
PUK가 잘못되었음을 지정합니다.
"MAX_ATTEMPTS_EXCEEDED"
최대 시도 횟수를 초과했음을 나타냅니다.
"UNKNOWN_ERROR"
위 유형으로 오류를 나타낼 수 없음을 지정합니다.
PinRequestType
requestPin 함수로 확장 프로그램에서 요청하는 코드 유형입니다.
열거형
'PIN'
요청된 코드가 PIN임을 지정합니다.
'PUK'
요청된 코드가 PUK임을 지정합니다.
PinResponseDetails
속성
-
userInput
문자열 선택사항
사용자가 제공한 코드입니다. 사용자가 대화상자를 닫았거나 다른 오류가 발생한 경우 비어 있습니다.
ReportSignatureDetails
속성
-
오류
"GENERAL_ERROR"
선택사항서명을 생성하는 중에 발생한 오류입니다(발생한 경우).
-
signRequestId
숫자
onSignatureRequested이벤트를 통해 수신된 요청 식별자입니다. -
서명
ArrayBuffer 선택사항
서명(생성된 경우)
RequestPinDetails
속성
-
attemptsLeft
번호 선택사항
남은 시도 횟수입니다. 이는 모든 UI가 이 정보를 사용자에게 표시할 수 있도록 제공됩니다. Chrome에서는 이를 시행하지 않습니다. 대신 고정 요청 수가 초과되면 확장 프로그램에서 stopPinRequest를 errorType = MAX_ATTEMPTS_EXCEEDED로 호출해야 합니다.
-
errorType
PinRequestErrorType 선택사항
사용자에게 표시되는 오류 템플릿입니다. 이전 요청이 실패한 경우 사용자에게 실패 이유를 알리기 위해 설정해야 합니다.
-
requestType
PinRequestType 선택사항
요청된 코드 유형입니다. 기본값은 PIN입니다.
-
signRequestId
숫자
SignRequest에서 Chrome에 제공한 ID입니다.
SetCertificatesDetails
속성
-
certificatesRequestId
번호 선택사항
onCertificatesUpdateRequested에 대한 응답으로 호출되면 수신된certificatesRequestId값을 포함해야 합니다. 그렇지 않으면 설정 해제해야 합니다. -
clientCertificates
현재 사용 가능한 클라이언트 인증서 목록입니다.
-
오류
"GENERAL_ERROR"
선택사항인증서를 추출하는 중에 발생한 오류입니다(발생한 경우). 이 오류는 적절한 경우 사용자에게 표시됩니다.
SignatureRequest
속성
-
알고리즘
사용할 서명 알고리즘입니다.
-
증명서
ArrayBuffer
X.509 인증서의 DER 인코딩입니다. 확장 프로그램은 연결된 비공개 키를 사용하여
input에 서명해야 합니다. -
입력
ArrayBuffer
서명할 데이터입니다. 데이터는 해싱되지 않습니다.
-
signRequestId
숫자
reportSignature에 전달할 요청 식별자입니다.
SignRequest
속성
-
증명서
ArrayBuffer
X.509 인증서의 DER 인코딩입니다. 확장 프로그램은 연결된 비공개 키를 사용하여
digest에 서명해야 합니다. -
다이제스트
ArrayBuffer
서명해야 하는 다이제스트입니다.
-
해시
digest를 만드는 데 사용된 해시 알고리즘을 나타냅니다. -
signRequestId
숫자
Chrome 57 이상확장 프로그램에서 requestPin과 같이 고유 ID가 필요한 메서드를 호출해야 하는 경우 사용할 고유 ID입니다.
StopPinRequestDetails
속성
-
errorType
PinRequestErrorType 선택사항
오류 템플릿 있는 경우 사용자에게 표시됩니다. 오류(예: MAX_ATTEMPTS_EXCEEDED)로 인해 흐름이 중지된 경우 중지 이유를 포함하기 위한 것입니다.
-
signRequestId
숫자
SignRequest에서 Chrome에 제공한 ID입니다.
메서드
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
onSignatureRequested에 대한 응답으로 호출해야 합니다.
확장 프로그램은 결국 모든 onSignatureRequested 이벤트에 대해 이 함수를 호출해야 합니다. API 구현은 일정 시간이 지나면 이 호출을 기다리는 것을 중지하고 이 함수가 호출되면 시간 초과 오류로 응답합니다.
매개변수
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
Chrome 96 이상Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
사용자에게 PIN을 요청합니다. 한 번에 진행 중인 요청은 하나만 허용됩니다. 다른 흐름이 진행되는 동안 발행된 요청은 거부됩니다. 다른 흐름이 진행 중인 경우 나중에 다시 시도하는 것은 확장 프로그램의 책임입니다.
매개변수
-
세부정보
요청된 대화상자에 관한 세부정보를 포함합니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(details?: PinResponseDetails) => void
-
세부정보
PinResponseDetails 선택사항
-
반환 값
-
Promise<PinResponseDetails | undefined>
Chrome 96 이상Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
브라우저에서 사용할 인증서 목록을 설정합니다.
확장 프로그램은 초기화 후 및 현재 사용 가능한 인증서 집합이 변경될 때마다 이 함수를 호출해야 합니다. 또한 확장 프로그램은 이 이벤트가 수신될 때마다 onCertificatesUpdateRequested에 대한 응답으로 이 함수를 호출해야 합니다.
매개변수
-
설정할 인증서입니다. 잘못된 인증서는 무시됩니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
Chrome 96 이상Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
requestPin 함수에서 시작한 고정 요청을 중지합니다.
매개변수
-
요청 흐름을 중지한 이유에 관한 세부정보를 포함합니다.
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
반환 값
-
Promise<void>
Chrome 96 이상Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
이벤트
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
이 이벤트는 setCertificates를 통해 설정된 인증서가 충분하지 않거나 브라우저에서 업데이트된 정보를 요청하는 경우 발생합니다. 확장 프로그램은 업데이트된 인증서 목록과 수신된 certificatesRequestId를 사용하여 setCertificates를 호출해야 합니다.
매개변수
-
콜백
함수
callback매개변수는 다음과 같습니다.(request: CertificatesUpdateRequest) => void
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
이 이벤트는 브라우저가 setCertificates를 통해 이 확장 프로그램에서 제공한 인증서를 사용하여 메시지에 서명해야 할 때마다 발생합니다.
확장 프로그램은 적절한 알고리즘과 비공개 키를 사용하여 request의 입력 데이터에 서명하고 수신된 signRequestId를 사용하여 reportSignature를 호출하여 반환해야 합니다.
매개변수
-
콜백
함수
callback매개변수는 다음과 같습니다.(request: SignatureRequest) => void