클라이언트 측 암호화 (CSE)는 데이터가 Drive 서버에 도달하기 전에 암호화되도록 하여 데이터를 제어할 수 있도록 합니다. 이 가이드에서는 Drive API를 사용하여 CSE 파일을 프로그래매틱 방식으로 암호화 및 업로드하고 다운로드 및 복호화하는 과정을 안내합니다. 또한 구현을 테스트하고 검증하기 위한 권장 접근 방식을 다룹니다.
시작하기 전에
암호화된 파일을 관리하기 전에 다음 체크리스트를 사용하여 Google Workspace 도메인을 설정하세요.
도메인에 클라이언트 측 암호화 (CSE) 를 구성합니다.
ID 공급업체 (IdP)를 설정합니다.
키 액세스 제어 목록 서비스 (KACLS)가
/wrap,/unwrap,/privilegedwrap,/privilegedunwrap, 및/digest엔드포인트를 지원하는지 확인합니다.Google Cloud 콘솔에서 프로젝트를 만들고 Drive API를 사용 설정합니다.
인증 및 승인
Drive API 및 KACLS와 상호작용하려면 인증 방법을 선택해야 합니다. 이 선택은 두 서비스와 상호작용하는 방식에 영향을 미칩니다.
- 개인: 개인으로 인증하려면
OAuth 흐름을 사용하여 해당 사용자를 대신하여 작업을 수행합니다. 표준
/wrap및/unwrap엔드포인트를 사용하고 해당 사용자의 Google 승인 토큰을 제공합니다. - 관리자: 도메인의 다른 사용자를 가장하려면 도메인 전체 위임(DWD)이 있는 서비스 계정을 사용합니다. Google 승인 토큰 없이
/privilegedwrap및/privilegedunwrap엔드포인트를 사용합니다.
사용자 인증 정보 만들기에 관한 자세한 내용은 액세스 사용자 인증 정보 만들기 가이드를 참고하세요.
도메인 IdP 인증
IdP로 인증하려면 OAuth 클라이언트 ID를 구성하고 클라이언트 보안 비밀번호 파일을 다운로드해야 합니다. 애플리케이션은 IdP에서 인증 토큰을 가져와 KACLS에 대한 요청을 인증해야 합니다. 이 토큰은 애플리케이션이 데이터 암호화 키에 액세스할 수 있도록 하는 데 필요합니다.
사용자 인증 정보를 안전하게 처리
애플리케이션은 Drive API 및 IdP에 인증하기 위한 민감한 사용자 인증 정보를 처리합니다. 예를 들면 다음과 같습니다.
- 클라이언트 보안 비밀번호 파일과 같은 IdP의 보안 비밀 자료
- 서비스 계정 비공개 키 파일과 같은 Google의 보안 비밀 자료
- 저장된 사용자 인증 정보와 같이 앱에서 저장한 보안 비밀 자료
이러한 사용자 인증 정보는 모두 안전하게 저장해야 합니다.
한도 및 할당량
클라이언트 측에서 암호화된 파일에는 표준 Drive 한도 및 할당량이 적용됩니다. 공유 드라이브 한도, 일반 파일 및 폴더 한도, 할당량 관리 방법 을 숙지하세요. 또한 가져오기 도구는 키 액세스 제어 목록 서비스 (KACLS) 및 ID 공급업체 (IdP)의 비율 제한을 처리해야 합니다.
암호화된 파일 구조
Drive는 업로드 및 다운로드를 위해 다음과 같은 클라이언트 측에서 암호화된 파일 형식을 예상합니다.
+-------------------+
| Magic header |
+-------------------+
| Encrypted Chunk 1 |
+-------------------+
| Encrypted Chunk 2 |
+-------------------+
| ... |
+-------------------+
| Encrypted Chunk N |
+-------------------+
매직 헤더
매직 헤더 (파일 서명 또는 매직 넘버라고도 함)는 파일의 맨 처음에 배치되어 형식을 고유하게 식별하는 상수 바이트 시퀀스입니다. 파일은 0x99 0x5E 0xCC 0x5E 바이트로 시작해야 합니다.
암호화된 청크
파일은 2MiB 청크로 분할해야 합니다. 각 청크는 연결된 데이터로 청크 색인과 최종 청크 플래그를 사용하여 AES-GCM 키 유형으로 Google Tink 라이브러리의 연결된 데이터로 인증된 암호화 (AEAD) 기본 요소를 사용하여 암호화됩니다. Drive API를 사용하고 이 사양을 준수하는 코드 예는 오픈소스 데모를 참고하세요.
파일 암호화 및 업로드
CSE 파일을 업로드하려면 애플리케이션이 인증하고, CSE 토큰을 요청하고, 파일 콘텐츠를 로컬에서 암호화하고, 암호화 키를 래핑한 후 마지막으로 암호화된 콘텐츠와 메타데이터를 Google Drive에 업로드해야 합니다.
CSE 토큰 가져오기
Drive API
Files:generateCseToken
메서드를 호출하여 Google Drive에서 CSE 토큰을 요청합니다. 요청에 fileId 쿼리 매개변수를 포함하지 않도록 합니다. 특정 폴더에 파일을 만들려면 폴더 ID와 함께 parent 쿼리 매개변수를 포함합니다. parent가 생략되면 파일이 사용자의 루트 내 드라이브 폴더에 생성됩니다. 응답에는 업로드의 고유 파일 ID와 키 래핑 단계에 필요한 JWT 승인 토큰이 포함됩니다.
로컬에서 데이터 암호화
- Google Tink를 사용하여 파일의 고유한 데이터 암호화 키 (DEK)를 생성합니다.
- 암호화된 파일 구조에 따라 파일 콘텐츠를 암호화합니다.
컴퓨팅 리소스 키 해시
리소스 키 해시를 계산하려면 다음 안내를 따르세요.
generateCseToken에서 수신한jwt승인 토큰에서resource_name및perimeter_id를 추출합니다.perimeter_id가 누락된 경우 빈 문자열을 사용합니다.- 일반 텍스트 DEK를 키로 사용하고 문자열
ResourceKeyDigest:my_resource_name:my_perimeter_id를 서명할 데이터로 사용하여 HMAC-SHA256을 계산합니다. - 결과 해시를 Base64로 인코딩합니다.
자세한 내용은 리소스 키 해시를 참고하세요.
암호화 키 래핑
DEK를 보호하려면 외부 KACLS를 사용하여 암호화 (래핑)합니다.
- 적절한 엔드포인트를 호출합니다.
- 개인:
/wrap - 관리자:
/privilegedwrap
- 개인:
- 일반 텍스트 DEK, IdP 인증 토큰, Google 승인 토큰 (필요한 경우), JWT의
resource_name,reason을 전달합니다. - KACLS에서 래핑된 DEK (WDEK)를 수신합니다.
드라이브에 업로드
Drive API
files.create 엔드포인트를 사용하여
암호화된 파일 blob의
표준 파일 업로드를 실행합니다. 파일 메타데이터에서 다음 필드를 설정합니다.
id:generateCseToken응답에서 수신한 고유 파일 ID입니다.mimeType:application/vnd.google-gsuite.encrypted; content="application/octet-stream".content매개변수는 원본 파일의 MIME 유형으로 설정할 수 있습니다.
clientEncryptionDetails:encryptionState:"encrypted".decryptionMetadata:wrappedKey: KACLS에서 수신한 래핑된 DEK (WDEK)입니다.kaclsId:generateCseToken응답에서 수신한 KACLS ID입니다.keyFormat:"tinkAesGcmKey".aes256GcmChunkSize:"default".encryptionResourceKeyHash: 컴퓨팅 리소스 키 해시에서 계산된 해시입니다.
오픈소스 예시
암호화 및 업로드 프로세스의 실제 데모는 오픈소스 데모를 참고하세요. 이는 작동하는 솔루션을 제공하며 유용한 참고자료로 활용될 수 있습니다.
파일 다운로드 및 복호화
CSE 파일을 다운로드하려면 Google Drive에서 암호화된 콘텐츠와 메타데이터를 가져오고, KACLS에서 일반 텍스트 DEK를 요청하고, 파일을 로컬에서 복호화해야 합니다.
파일 메타데이터 및 암호화된 콘텐츠 가져오기
Drive API
Files:get 메서드를 호출하여
파일의 메타데이터와 콘텐츠를 가져옵니다. clientEncryptionDetails에는 래핑된 DEK (WDEK)와 KACLS 정보가 포함된 JWT가 포함된 DecryptionMetadata가 포함되어 있습니다.
암호화 키 래핑 해제
- 적절한 엔드포인트를 호출합니다.
- 개인:
/unwrap - 관리자:
/privilegedunwrap
- 개인:
- WDEK, IdP 인증 토큰, Google 승인 토큰(필요한 경우),
resource_name,reason을 전달합니다. - KACLS에서 일반 텍스트 DEK를 수신합니다.
로컬에서 데이터 복호화
- KACLS에서 수신한 일반 텍스트 DEK를 사용하여 암호를 초기화합니다.
- 초기 매직 바이트를 건너뛰고 암호화된 파일 구조에 따라 나머지 콘텐츠를 복호화합니다.
오픈소스 예시
다운로드 및 복호화 프로세스의 실제 데모는 오픈소스 데모를 참고하세요. 이는 작동하는 솔루션을 제공하며 유용한 참고자료로 활용될 수 있습니다.
가져온 파일 검증
Google은 암호화 키에 액세스할 수 없으므로 Google은 파일을 서버 측에서 복호화하고 검증할 수 없습니다. 로컬 암호화 또는 키 래핑 단계 중에 구현 오류가 발생하면 클라이언트 측에서 파일을 복호화할 때 오류가 발생합니다. 자체 구현을 활용하기 전에 철저한 검증이 중요합니다.
업로드된 Google Drive CSE 콘텐츠가 올바르게 작동하려면 올바르게 암호화되어야 하며 올바른 메타데이터가 포함되어야 합니다. 콘텐츠가 유효하고 복호화될 수 있는지 확인하는 것은 사용자의 책임입니다.
왕복 암호화 및 복호화 테스트 실행
구현을 검증하려면 엔드 투 엔드 흐름을 테스트하는 것이 중요합니다. 여기에는 테스트 파일 집합을 가져와 로컬 로직을 사용하여 암호화하고, API를 사용하여 Drive에 업로드한 후 다운로드하여 복호화하는 작업이 포함됩니다. 복호화 후 결과 콘텐츠를 원본 파일과 비교하여 동일한지 확인합니다. 이 프로세스는 암호화, 키 래핑 또는 메타데이터 처리의 문제를 파악하는 데 도움이 됩니다. 오픈소스 데모에서는 자체 애플리케이션 내에서 이러한 검증 프로세스를 구현하는 방법을 보여줍니다.
Google Drive를 사용한 스팟 체크
업로드된 파일에 Drive 웹 클라이언트에 잠금 아이콘이 포함되어 있는지 확인합니다. 업로드된 파일을 소량으로 수동으로 다운로드하여 예상대로 작동하는지 확인합니다. 이 검사는 Google의 CSE 구현을 사용하여 복호화를 시도하므로 암호화 또는 키 래핑 로직의 문제를 격리하는 데 도움이 됩니다. 내 드라이브 와 공유 드라이브 의 파일을 모두 포함합니다.
오픈소스 데모
오픈소스 Drive CSE 업로드 패키지는 이 가이드에 설명된 CSE 업로드 및 다운로드 흐름을 구현하는 완전하고 작동하는 Python 라이브러리 및 명령줄 예시를 제공합니다. 자체 CSE 통합을 빌드하기 전에 데모 코드를 검토하는 것이 좋습니다.