외부 복호화 서비스를 통한 암호화 파일 수집

Automation Anywhere Enterprise Knowledge Base (AAEKB / EKB) — 관리자 및 통합 가이드

이 기능이 하는 일

AAEKB는 업로드된 파일을 호스팅하고 통제하는 외부 복호화 서비스에 전달하여 복호화된 바이트를 돌려받은 다음, 복호화된 내용에 대해 정상적인 지식 베이스 수집 파이프라인(텍스트 추출, OCR, 청킹, 임베딩, 색인)을 실행합니다.

이것은 저장 중인 문서에 엔터프라이즈 DRM 또는 봉투 암호화(envelope encryption)를 적용하며 복호화 키를 제3자 애플리케이션으로 보낼 수 없는 조직을 위해 존재합니다. 키, 복호화 로직, 평문 경계는 모두 네트워크 안에 유지됩니다. AAEKB는 HTTP 엔드포인트를 호출하고 바이트 스트림을 읽는 방법만 알 뿐입니다.

통합은 의도적으로 범용이며 구성 주도적입니다. AAEKB 내부에 벤더 특정 DRM SDK는 없습니다. 파일을 받아 파일을 반환하는 모든 HTTP 서비스 — 동기 또는 작업/폴링 패턴 — 는 복호화 서비스가 구현해야 할 계약의 계약에 맞기만 하면 연결될 수 있습니다.

주요 특성:

업로드별 옵트인. 사용자가 토글을 명시적으로 체크할 때만 파일이 복호화 서비스로 전송됩니다. 일반 업로드는 완전히 영향을 받지 않습니다.
단일 전역 구성. 슈퍼 관리자가 AAEKB 배포당 하나의 복호화 서비스를 구성합니다.
메모리 전용. 암호화된 바이트, 서비스에 대한 요청, 복호화된 응답은 모두 메모리에서 처리됩니다. AAEKB는 서비스를 호출하기 전에 암호문을 임시 파일로 디스크에 쓰지 않습니다.
AAEKB에 키 자료 없음. AAEKB는 엔드포인트 URL과 선택적으로 서비스 호출용 API 자격 증명을 저장합니다. 문서 암호화 키는 절대 저장하거나 다루지 않습니다.

처음부터 끝까지의 동작 방식

 User (browser)                AAEKB backend                 Your decryption service
      |                              |                                  |
      |  1. Upload file +            |                                  |
      |     "Requires Decryption"    |                                  |
      |----------------------------->|                                  |
      |                              |                                  |
      |            2. File security validation                          |
      |               (runs on the ENCRYPTED bytes)                     |
      |                              |                                  |
      |                              |  3. POST encrypted file          |
      |                              |--------------------------------->|
      |                              |                                  |
      |                              |  4a. sync: 200 + decrypted bytes |
      |                              |<---------------------------------|
      |                              |                                  |
      |                              |  4b. async: 202 + { job_id }     |
      |                              |<---------------------------------|
      |                              |  5b. GET poll/{job_id}  (repeat) |
      |                              |--------------------------------->|
      |                              |  6b. 200 + decrypted bytes       |
      |                              |<---------------------------------|
      |                              |                                  |
      |            7. MIME type re-detected on decrypted bytes          |
      |            8. Decrypted file stored in KB raw storage           |
      |            9. Normal ingestion: extract, chunk, embed, index    |
      |                              |                                  |
      |  10. Resource appears in KB  |                                  |
      |<-----------------------------|                                  |

단계별로:

업로드. 사용자는 지식 베이스 업로드 모달에서 파일을 선택하고 Requires Decryption 토글을 켭니다. 프론트엔드는 파일과 함께 추가 폼 필드로 needs_decryption=true를 보냅니다.
파일 보안 검증. AAEKB의 표준 업로드 보안 미들웨어는 복호화 이전에, 암호화된 바이트와 원래 파일명에 대해 실행됩니다. 이것이 가장 중요한 단일 호환성 제약입니다 — 호환성 참조.
서비스에 제출. AAEKB가 파일을 메모리로 읽어 구성된 복호화 엔드포인트로 보냅니다.
평문 수신. 즉시(sync 모드) 또는 결과 엔드포인트를 폴링한 후(async 모드).
파일 타입 재감지. AAEKB가 복호화된 바이트에서 MIME 타입을 다시 도출합니다: 먼저 파일명 확장자에서, 그것이 아무것도 내주지 않으면 복호화된 내용의 첫 2 KB를 스니핑하여.
저장 및 수집. 복호화된 파일은 지식 베이스 원시 파일 스토리지에 기록된 다음 일반 수집 파이프라인으로 처리됩니다. 복호화 메타데이터는 문서의 메타데이터 레코드에 병합됩니다.

두 개의 업로드 경로가 있으며 둘 다 이 기능을 동일하게 지원합니다:

경로	엔드포인트	복호화 실행 위치
동기 업로드 (레거시 / Quick Upload)	`POST /v3/project/knowledge/add/file`	웹 요청 내부
백그라운드 업로드 (기본값)	`POST /v5/project/knowledge/add/file`	백그라운드 워커 프로세스 내부

실질적 의미: 웹/API 컨테이너와 백그라운드 워커 컨테이너 모두 복호화 서비스에 도달할 수 있어야 합니다.

서비스 구성 (슈퍼 관리자)

슈퍼 관리자로 로그인합니다.
Super Admin → Platform & integrations → KB Decryption Service를 엽니다.
전체 구성 레퍼런스에 설명된 구성을 입력합니다.
Enabled를 켭니다.
Save Changes를 클릭합니다.

관리자 화면에 관한 참고:

Async Polling Configuration 카드는 Response Mode가 Asynchronous로 설정된 경우에만 표시됩니다.
인증 자격 증명 필드는 구성이 읽힐 때 마스킹됩니다. 처음 네 문자만 표시되고 나머지는 불릿 문자로 대체됩니다. 필드를 건드리지 않고 다시 저장하면 저장된 자격 증명이 유지됩니다. 자격 증명을 교체하려면 필드를 지우고 새 값을 온전히 입력하세요.
저장은 전체 폼에 걸쳐 원자적입니다 — 필드별 저장은 없습니다.
Enabled를 끄면 즉시 최종 사용자 토글이 숨겨지고, 여전히 needs_decryption=true를 주장하는 모든 업로드는 명확한 오류로 거부됩니다.

자동 프로비저닝을 위해 동일한 구성을 REST API로도 사용할 수 있습니다:

메서드	경로	접근	목적
`GET`	`/admin/kb-decryption-service`	Super Admin	구성 읽기 (자격 증명 마스킹됨)
`PUT`	`/admin/kb-decryption-service`	Super Admin	부분 업데이트; 보낸 필드만 변경
`GET`	`/kb-decryption-service/status`	인증된 모든 사용자	`{"available": true}` 반환

프로비저닝 호출 예제:

curl -X PUT "https://ekb.example.com/admin/kb-decryption-service" \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
        "enabled": true,
        "display_name": "Corporate DRM Gateway",
        "description": "Intranet decryption service for classified documents",
        "decrypt_endpoint": "https://drm.corp.internal/api/v1/async/decrypt/stream",
        "decrypt_http_method": "POST",
        "decrypt_content_type": "multipart/form-data",
        "decrypt_file_field_name": "file",
        "decrypt_extra_headers": {"X-Tenant": "aa-ekb"},
        "decrypt_extra_body_fields": {"purpose": "ingestion"},
        "response_mode": "async",
        "poll_endpoint_template": "https://drm.corp.internal/api/v1/async/download/stream/{job_id}",
        "poll_interval_seconds": 5,
        "poll_max_attempts": 120,
        "poll_job_id_json_path": "job_id",
        "poll_status_json_path": "status",
        "poll_completed_status": "COMPLETED",
        "poll_failed_statuses": "FAILED,ERROR",
        "auth_type": "api_key_header",
        "auth_token": "s3cr3t-api-key",
        "auth_header_name": "X-API-Key"
      }'

전체 구성 레퍼런스

일반

필드	타입	기본값	의미
`enabled`	boolean	`false`	마스터 스위치. 꺼져 있으면 최종 사용자 토글이 숨겨지고 복호화 요청이 거부됩니다.
`display_name`	string	`Default Decryption Service`	친숙한 이름. 각 복호화된 문서의 메타데이터에 기록됩니다.
`description`	string	(빈 값)	관리자를 위한 자유 텍스트 메모. 런타임에 사용되지 않습니다.

복호화 요청

필드	타입	기본값	의미
`decrypt_endpoint`	URL	(빈 값)	AAEKB가 암호화된 파일을 POST할 절대 URL. API와 워커 컨테이너 모두에서 도달 가능해야 합니다.
`decrypt_http_method`	`POST` \| `PUT`	`POST`	제출 요청에 사용되는 HTTP 동사.
`decrypt_content_type`	`multipart/form-data` \| `application/octet-stream`	`multipart/form-data`	파일 전송 방식. 아래 참고 사항 참조.
`decrypt_file_field_name`	string	`file`	파일을 담는 멀티파트 폼 필드 이름. 멀티파트 모드에서만 사용됩니다.
`decrypt_extra_headers`	JSON 객체	`{}`	제출 요청과 모든 폴링 요청 모두에 병합되는 추가 헤더.
`decrypt_extra_body_fields`	JSON 객체	`{}`	파일과 함께 전송되는 추가 폼 필드. 멀티파트 모드에서만 사용됩니다.
`response_mode`	`sync` \| `async`	`async`	복호화된 바이트가 제출 호출에서 돌아오는지 폴링을 통하는지.

경고

application/octet-stream 모드. 콘텐츠 타입이 application/octet-stream일 때 AAEKB는 원시 파일 바이트를 요청 본문 전체로 전송합니다. 이 모드에서는 파일명이 전송되지 않으며 decrypt_extra_body_fields는 무시됩니다. 이를 담을 멀티파트 봉투가 없기 때문입니다. 서비스에 파일명이나 추가 컨텍스트가 필요하면 multipart/form-data를 사용하거나 decrypt_extra_headers로 컨텍스트를 전달하세요.

비동기 폴링 (`response_mode = async`일 때만 사용)

필드	타입	기본값	의미
`poll_endpoint_template`	URL 템플릿	(빈 값)	결과 URL. 리터럴 자리 표시자 `{job_id}`를 포함해야 하며, 이는 추출된 작업 식별자로 대체됩니다.
`poll_interval_seconds`	정수	`5`	폴링 사이 대기 초. AAEKB는 첫 폴링 전에 대기하므로 최소 복호화 지연은 하나의 간격입니다.
`poll_max_attempts`	정수	`120`	최대 폴링 횟수. 총 예산 = `poll_interval_seconds × poll_max_attempts` (기본값 600초 / 10분).
`poll_job_id_json_path`	점 경로	`job_id`	제출 응답에서 작업 식별자를 찾을 위치, 예: `data.jobId`.
`poll_status_json_path`	점 경로	`status`	JSON 폴링 응답에서 작업 상태를 찾을 위치, 예: `result.state`.
`poll_completed_status`	string	`COMPLETED`	"완료"를 의미하는 상태 값. 대소문자를 무시하고 비교합니다.
`poll_failed_statuses`	쉼표 구분	`FAILED,ERROR`	작업을 즉시 중단시키는 상태 값. 대소문자를 무시하고 비교합니다.

점 경로는 단순한 중첩 사전 조회입니다. data.job.id는 response["data"]["job"]["id"]를 해석합니다. 배열 인덱싱은 지원되지 않습니다 — 경로 세그먼트는 리스트 인덱스가 될 수 없습니다.

인증

필드	타입	기본값	의미
`auth_type`	`none` \| `bearer` \| `api_key_header` \| `custom_headers`	`none`	인증 방식. 인증 옵션 참조.
`auth_token`	비밀 문자열	(빈 값)	베어러 토큰 또는 API 키 값. 읽을 때 마스킹됩니다.
`auth_header_name`	string	`Authorization`	`auth_type = api_key_header`일 때 사용되는 헤더 이름.

복호화 서비스가 구현해야 할 계약

이것은 복호화 서비스를 구축하거나 운영하는 사람에게 전달해야 하는 규격입니다.

타협 불가 요건

HTTP(S)로 대화합니다. 파일을 받는 하나의 엔드포인트; async 모드에서는 작업의 결과를 반환하는 두 번째 엔드포인트.
복호화된 파일을 원시 바이트로 반환합니다. base64로, JSON으로 감싸서, 다운로드 URL로의 리다이렉트가 아니라. AAEKB는 응답 본문을 그대로 수집 파이프라인으로 스트리밍합니다.
파일의 원래 형식을 보존합니다. 암호문이 PDF로 복호화되면 올바른 구조의 PDF를 반환합니다. AAEKB는 형식 변환을 하지 않습니다.
성공 시 비어 있지 않은 본문을 반환합니다. 빈 응답은 실패로 취급됩니다.
AAEKB의 API 및 워커 컨테이너에서 도달 가능하며, 그 컨테이너들이 신뢰하는 TLS 인증서를 가집니다.
폴링 엔드포인트에서 반복된 GET을 견딜 만큼 멱등해야 합니다. 이중 GET 동작 참조.

제출 엔드포인트

멀티파트 모드 (권장). AAEKB가 전송:

메서드: 구성대로 (POST 또는 PUT)
Content-Type: 생성된 boundary가 있는 multipart/form-data
decrypt_file_field_name으로 명명된 하나의 파일 파트, filename은 원래 업로드 파일명
decrypt_extra_body_fields의 추가 폼 필드 0개 이상
구성된 인증 및 추가 헤더

옥텟 스트림 모드. AAEKB는 Content-Type: application/octet-stream으로 원시 바이트를 요청 본문으로 전송합니다. 파일명 없음, 추가 본문 필드 없음.

기대되는 응답:

모드	허용되는 상태	본문
`sync`	`200`만	복호화된 파일 바이트
`async`	`202` (일반적) 또는 `200`	작업 식별자를 담은 JSON, 또는 — 바이너리 콘텐츠 타입의 `200`이면 — 복호화된 바이트 그대로

async 모드에서 AAEKB는 폴링 여부를 결정하기 전에 제출 응답을 검사합니다:

200 그리고 바이너리로 보이는 Content-Type → 바이트를 직접 사용, 폴링 없음. (이를 통해 서비스는 작은 파일에 대해 단축할 수 있습니다.)
그 외 → 본문을 JSON으로 파싱하고 poll_job_id_json_path를 사용해 작업 식별자를 추출합니다.

"바이너리로 보이는" 콘텐츠 타입은 octet-stream을 포함하거나, application/으로 시작하면서 json을 포함하지 않는 것입니다. 따라서 application/octet-stream과 application/pdf는 바이너리로, application/json은 아닙니다. text/plain은 바이너리로 취급되지 않습니다 — Content-Type 지침 참조.

폴링 엔드포인트 (async 모드)

AAEKB는 {job_id}가 대체된 poll_endpoint_template에 제출 요청과 동일한 인증 및 추가 헤더를 실어 GET을 발행합니다. poll_interval_seconds마다 poll_max_attempts회까지 이를 반복합니다.

서비스는 다음 중 하나로 응답해야 합니다:

상황	상태	본문	AAEKB 동작
아직 작업 중	`202`	아무것나 (무시)	대기 후 다시 폴링
아직 작업 중	`200`	상태 필드가 완료 값도 실패 값도 아닌 JSON	대기 후 다시 폴링
완료	`200`	바이너리 `Content-Type`의 원시 복호화 바이트	권장. 바이트 사용; 폴링 중지
완료	`200`	상태 필드가 `poll_completed_status`와 같은 JSON	바이너리를 기대하며 같은 URL에 `GET`을 하나 더 발행; 바이너리가 아니면 업로드 실패
실패	`200`	상태 필드가 `poll_failed_statuses`에 있는 JSON	상태를 명명한 오류로 즉시 중단
오류	`>= 400`	아무것나	즉시 중단. 재시도하지 않음

경고

아직 준비되지 않은 작업에 404를 반환하지 마세요. 400 이상의 어떤 상태 코드든 작업을 하드 실패로 끝냅니다. "준비 안 됨"에는 202를 사용하세요.

이중 GET 동작 (async 모드)

폴링 엔드포인트가 작업이 완료되었음을 말하는 JSON 본문으로 200에 응답하면, AAEKB는 파일을 별도로 가져와야 한다고 가정하고 바로 그 URL에 이번에는 바이너리 스트림을 기대하며 두 번째 GET을 즉시 발행합니다. 두 번째 호출도 JSON을 반환하면 업로드가 *"Decryption job completed but no file stream was returned."*로 실패합니다.

이를 충족하는 두 가지 방법:

권장: 작업이 완료되는 즉시 폴링 엔드포인트가 Content-Type: application/octet-stream으로 원시 바이트를 직접 반환하게 합니다. AAEKB는 첫 폴링에서 이를 감지하고 두 번째 요청을 절대 발행하지 않습니다. 가장 단순하고 빠른 설계입니다.
허용: 엔드포인트가 보류/완료 중에는 JSON 상태를 반환하고, 이후 호출에서 바이트 스트림을 반환하도록 전환합니다. 작업은 최초 완료 보고 후 최소 하나의 추가 GET 동안 검색 가능해야 합니다.

지원되지 않는 것은 완료 JSON이 다른 다운로드 URL을 포함하는 설계입니다. AAEKB는 그것을 따르지 않습니다.

Content-Type 지침

응답	권장 `Content-Type`
복호화된 파일 바이트	`application/octet-stream`
작업 수락 / 작업 상태	`application/json`

async 모드에서 복호화된 페이로드를 text/plain이나 text/csv로 반환하면 AAEKB가 작업 상태 JSON 문서로 파싱하려다 실패합니다. sync 모드에서는 응답의 콘텐츠 타입이 아예 검사되지 않습니다 — 어떤 200이든 복호화된 바이트로 취급됩니다 — 하지만 일관성을 위해 여전히 application/octet-stream이 권장됩니다.

AAEKB가 절대 하지 않는 일

복호화 키, 사용자 자격 증명, 최종 사용자의 신원을 서비스에 전송하지 않습니다. 서비스가 문서별/사용자별 인가가 필요하면 그 컨텍스트는 정적이고 배포 전역인 decrypt_extra_headers / decrypt_extra_body_fields에서 와야 합니다.
실패한 제출이나 실패한 폴링을 재시도하지 않습니다. 한 번의 실패로 업로드가 끝납니다.
완료 핸드셰이크의 일환으로 대체 다운로드 호스트로의 리다이렉트를 따르지 않습니다.
큰 파일을 청크하거나 범위 요청하지 않습니다. 전체 파일이 한 요청으로 들어가 한 응답으로 돌아옵니다.

실제 예제: 동기 모드

구성:

{
  "enabled": true,
  "decrypt_endpoint": "https://drm.corp.internal/api/v1/decrypt",
  "decrypt_http_method": "POST",
  "decrypt_content_type": "multipart/form-data",
  "decrypt_file_field_name": "file",
  "decrypt_extra_body_fields": { "purpose": "ingestion" },
  "decrypt_extra_headers": { "X-Tenant": "aa-ekb" },
  "response_mode": "sync",
  "auth_type": "bearer",
  "auth_token": "eyJhbGciOi..."
}

AAEKB가 전송하는 요청:

POST /api/v1/decrypt HTTP/1.1
Host: drm.corp.internal
Authorization: Bearer eyJhbGciOi...
X-Tenant: aa-ekb
Content-Type: multipart/form-data; boundary=----AAEKBBoundary7MA4YWxk
Content-Length: 2481037

------AAEKBBoundary7MA4YWxk
Content-Disposition: form-data; name="purpose"

ingestion
------AAEKBBoundary7MA4YWxk
Content-Disposition: form-data; name="file"; filename="Q3-Financials.pdf"
Content-Type: application/octet-stream

<...encrypted bytes...>
------AAEKBBoundary7MA4YWxk--

서비스가 반환해야 하는 성공 응답:

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 2394112
Content-Disposition: attachment; filename="Q3-Financials.pdf"

%PDF-1.7
<...decrypted bytes...>

Content-Disposition은 선택 사항이며 무시됩니다. AAEKB는 원래 업로드 파일명을 유지합니다.

실패 응답 — 200이 아닌 어떤 것이든 업로드를 끝냅니다. 짧고 읽기 쉬운 본문을 포함하세요. AAEKB는 그 처음 500자를 최종 사용자에게 표시합니다.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error": "Document policy forbids export for this identity"}

사용자가 보는 것: Decryption service returned HTTP 403: {"error": "Document policy forbids export for this identity"}

실제 예제: 비동기 (폴링) 모드

구성:

{
  "enabled": true,
  "decrypt_endpoint": "https://drm.corp.internal/api/v1/async/decrypt/stream",
  "decrypt_content_type": "multipart/form-data",
  "decrypt_file_field_name": "file",
  "response_mode": "async",
  "poll_endpoint_template": "https://drm.corp.internal/api/v1/async/download/stream/{job_id}",
  "poll_interval_seconds": 5,
  "poll_max_attempts": 120,
  "poll_job_id_json_path": "job_id",
  "poll_status_json_path": "status",
  "poll_completed_status": "COMPLETED",
  "poll_failed_statuses": "FAILED,ERROR",
  "auth_type": "api_key_header",
  "auth_token": "s3cr3t-api-key",
  "auth_header_name": "X-API-Key"
}

1단계 — 제출

POST /api/v1/async/decrypt/stream HTTP/1.1
Host: drm.corp.internal
X-API-Key: s3cr3t-api-key
Content-Type: multipart/form-data; boundary=----AAEKBBoundary7MA4YWxk

------AAEKBBoundary7MA4YWxk
Content-Disposition: form-data; name="file"; filename="Q3-Financials.pdf"
Content-Type: application/octet-stream

<...encrypted bytes...>
------AAEKBBoundary7MA4YWxk--

응답:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "job_id": "8f14e45f-ceea-467a-9f7a-2a1d4b0c9e33",
  "status": "PENDING"
}

중첩된 식별자의 경우 대신 poll_job_id_json_path를 data.job.id로 설정하고 다음과 같이 반환합니다:

{ "data": { "job": { "id": "8f14e45f-ceea-467a-9f7a-2a1d4b0c9e33" } } }

2단계 — 보류 중 폴링

AAEKB는 5초를 기다린 후:

GET /api/v1/async/download/stream/8f14e45f-ceea-467a-9f7a-2a1d4b0c9e33 HTTP/1.1
Host: drm.corp.internal
X-API-Key: s3cr3t-api-key

다음 중 어느 것이든 AAEKB를 대기 상태로 유지합니다:

HTTP/1.1 202 Accepted
Content-Type: application/json

{"status": "PROCESSING", "message": "File is still being processed."}

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "PROCESSING", "progress": 42}

3단계 — 완료 시 폴링 (권장 패턴)

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 2394112
Content-Disposition: attachment; filename="Q3-Financials.pdf"

%PDF-1.7
<...decrypted bytes...>

AAEKB는 폴링을 중지하고 수집으로 진행합니다.

3단계 (대안) — JSON으로 완료 후 스트리밍

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "COMPLETED"}

AAEKB는 즉시 동일한 GET을 다시 발행하며, 그때 서비스는 위에 표시된 바이너리 스트림으로 응답해야 합니다. 다시 JSON으로 응답하면 업로드가 실패합니다.

3단계 (실패)

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "FAILED", "reason": "Key not available for principal"}

사용자가 보는 것: External decryption job failed with status: FAILED

상태 값만 표시되며 reason 필드는 표시되지 않는다는 점에 유의하세요. 사용자 대면 메시지에 세부 정보를 담고 싶으면 상태 문자열에 인코딩하거나 대신 설명적인 본문의 4xx/5xx를 반환하세요.

레퍼런스 목업 서비스

실제 서비스가 준비되기 전 배관을 검증하는 데 유용한 최소한의 에코백 목업:

# Minimal AAEKB-compatible async decryption mock (FastAPI).
# Returns the uploaded bytes unchanged.
import io, uuid
from fastapi import FastAPI, UploadFile, File
from fastapi.responses import JSONResponse, StreamingResponse

app = FastAPI()
JOBS: dict[str, tuple[bytes, str]] = {}


@app.post("/api/v1/async/decrypt/stream")
async def submit(file: UploadFile = File(...)):
    job_id = str(uuid.uuid4())
    JOBS[job_id] = (await file.read(), file.filename or "file")
    return JSONResponse(status_code=202, content={"job_id": job_id, "status": "PENDING"})


@app.get("/api/v1/async/download/stream/{job_id}")
async def download(job_id: str):
    entry = JOBS.pop(job_id, None)
    if entry is None:
        # Not ready (or unknown). Must NOT be a 4xx — that would abort the job.
        return JSONResponse(status_code=202, content={"status": "PROCESSING"})
    data, filename = entry
    return StreamingResponse(
        io.BytesIO(data),
        media_type="application/octet-stream",
        headers={
            "Content-Disposition": f'attachment; filename="{filename}"',
            "Content-Length": str(len(data)),
        },
    )

인증 옵션

`auth_type`	AAEKB가 전송하는 것	참고
`none`	`decrypt_extra_headers`만	네트워크 수준 통제(프록시에서 종료되는 mTLS, IP 허용 목록, 서비스 메시)와 함께 사용.
`bearer`	`Authorization: Bearer <auth_token>`	더하기 `decrypt_extra_headers`.
`api_key_header`	`<auth_header_name>: <auth_token>`	더하기 `decrypt_extra_headers`. 전형적: `X-API-Key`.
`custom_headers`	`decrypt_extra_headers`만	자격 증명을 포함한 전체 헤더 세트를 추가 헤더 JSON에 넣으세요. 서명 방식 또는 다중 헤더 인증에 사용.

어떤 모드에서든 decrypt_extra_headers가 병합되며, 결과 헤더 세트는 제출 요청과 모든 폴링 요청 모두에 적용됩니다.

네이티브로 지원되지 않음: 토큰 갱신이 있는 OAuth 2.0 클라이언트 자격 증명 흐름, HMAC 요청 서명, AAEKB가 클라이언트 인증서를 제시하는 상호 TLS. 세 가지 모두 AAEKB와 복호화 서비스 사이에 작은 인증 리버스 프록시 또는 사이드카를 두고 decrypt_endpoint를 프록시로 가리키면 처리할 수 있습니다. 여기서 구성한 정적 토큰은 자동 갱신되지 않습니다. 순환 자격 증명은 관리자 화면에서 다시 저장하거나 PUT API로 푸시해야 합니다.

최종 사용자 경험

가시성. 지식 베이스 업로드 모달은 열릴 때 GET /kb-decryption-service/status를 호출합니다. Requires Decryption 토글은 그것이 {"available": true}를 반환할 때만 렌더링되며, 이는 구성 행이 존재하고 enabled가 true여야 합니다. 구성된 서비스가 없는 배포의 사용자는 절대 보지 못합니다. 상태 결과는 브라우저에 잠시(약 30초) 캐시되므로, 이미 열려 있는 세션에서 이 기능을 켜거나 끄면 나타나거나 사라지는데 최대 그만큼 걸릴 수 있습니다.

어디에 나타나는지. 두 KB 업로드 진입점 모두 토글을 노출합니다:

Add Resources 모달 (지식 베이스 내 드래그 앤 드롭 / 파일 선택기)
Selected Files 모달 (파일을 KB 뷰에 놓을 때 사용)

범위. 토글은 파일별이 아니라 업로드 배치별입니다. 켜져 있으면 그 배치의 모든 파일 — 선택한 폴더 내의 모든 파일 포함 — 이 복호화 서비스로 전송됩니다. 암호화 및 비암호화 파일의 혼합 배치는 지원되지 않습니다. 따로 업로드하세요.

기본 상태. 꺼짐. 모달이 닫힐 때마다 다시 열 때마다 꺼짐으로 초기화됩니다.

실패 동작. 복호화에 실패하면 그 파일의 업로드가 실패하고 오류가 업로드 진행 목록 / 토스트에 표시됩니다. 배치의 다른 파일은 영향을 받지 않습니다. 부분적인 것도 색인되지 않습니다.

진행률. 브라우저의 진행 표시줄은 AAEKB로의 바이트 업로드만 추적합니다. 복호화 서비스에서 소요되는 시간은 그 이후 서버 측에서 일어나며 업로드 진행이 아닌 처리 시간으로 표시됩니다. 기본 폴링 설정에서는 즉시 복호화라도 파일당 최소 5초의 추가 지연을 예상하세요.

호환성: 작동하는 것과 작동하지 않는 것

경고

이 섹션을 주의 깊게 읽으세요. 거의 모든 통합 실패의 원천입니다.

핵심 제약: 검증은 복호화보다 먼저 일어납니다

AAEKB의 표준 업로드 보안 검증은 파일이 복호화 서비스로 보내지기 전에 암호화된 바이트와 원래 파일명에 대해 실행됩니다. needs_decryption을 위한 우회는 없습니다. 즉, 암호화된 파일도 업로드 시점에 정당하고 허용된 파일 타입으로 보여야 합니다.

검증은 순서대로 다음을 수행합니다:

파일명 검사 — 경로 탐색 없음, null 바이트 없음, Windows 불법 문자 없음, 최대 255자, 의심스러운 이중 확장자 없음.
확장자 허용 목록 — 파일은 확장자를 가져야 하며 지원되는 타입 중 하나여야 합니다.
크기 제한 — 4096 MB (4 GB) 상한.
콘텐츠 스니핑 (libmagic) — 첫 2 KB를 검사하여 주장된 확장자와 비교합니다. 실행 파일 시그니처(PE / ELF / Mach-O)는 그대로 거부됩니다.
타입별 콘텐츠 검사 — 예: 이미지는 열고 검증하며, 텍스트 파일은 텍스트로 깔끔하게 디코딩되어야 합니다.

지원되는 파일 확장자

다음 확장자만 허용됩니다(스크립트 타입은 배포가 스크립트 업로드를 명시적으로 활성화한 경우에만):

문서: pdf, doc, docx, xls, xlsx, pptx
텍스트 및 데이터: txt, md, csv, tsv, json, xml, dita, yaml, yml, html, htm
메일: eml, msg
압축: zip
이미지: png, jpg, jpeg, gif, webp
오디오: mp3, wav, m4a, ogg
비디오: mp4, mov, avi, wmv, webm
스크립트 (옵트인 전용): py, sh, bash, js, php, rb, pl, bat, cmd, ps1

배포의 라이브 목록은 GET /upload-capabilities에서 확인할 수 있습니다.

파일명 및 래퍼 호환성

업로드된 파일명	결과
`Report.pdf` (내부에 암호문)	암호문 봉투에 따름 — 아래 참조
`Report.pdf.enc`	거부. `.enc`는 허용되는 확장자가 아님
`Report.enc`, `Report.drm`, `Report.aes`	거부. 허용되지 않는 확장자
`Report` (확장자 없음)	거부. "File must have an extension"
`Report.pdf.gpg`	거부. `.gpg`는 허용되지 않음

암호화 방식이 원래 파일 확장자를 보존해야 합니다. .enc, .drm, .p7m 등을 덧붙이는 래퍼 형식은 입구에서 거부됩니다. DRM 시스템이 그런 파일명을 생성하면 업로드 전에 원래 확장자로 이름을 바꾸거나, 클라이언트 측 내보내기가 그것을 유지하도록 구성하세요.

암호문 봉투 호환성

이것이 두 번째 관문입니다. 암호화된 바이트는 원래 확장을 주장하면서 콘텐츠 스니핑을 통과해야 합니다.

암호화 형식	호환?	이유
Microsoft Information Protection / OOXML 암호 암호화로 암호화된 Office 문서(`.docx`, `.xlsx`, `.pptx`)	예	이것들은 OLE2 / CDF 복합 컨테이너로 감싸집니다. AAEKB는 확장자가 Office 타입일 때 OLE2, CDFV2, `application/vnd.ms-office`, `application/octet-stream`을 명시적으로 허용합니다. 가장 지원이 잘 되는 경우입니다.
제자리로 암호화된 레거시 Office(`.doc`, `.xls`)	예	동일한 OLE2 허용.
표준 PDF 암호화(`/Encrypt` 딕셔너리, 비밀번호 보호)가 된 PDF	예	파일은 구조적으로 유효한 PDF로 유지되며, `%PDF-`가 여전히 선두 시그니처입니다.
불투명 봉투로 감싸였지만 첫 1024 바이트 안에 `%PDF-`가 있는 PDF	예	AAEKB는 첫 1 KB에서 `%PDF-` 마커를 검색하고 그 근거로 허용합니다. PDF 프리앰블/헤더를 유지하는 DRM 봉투는 통과합니다.
첫 1 KB에 `%PDF-`가 전혀 없는 완전히 암호화된 불투명 암호문 PDF	아니오	`.pdf` 확장자에 대해 스니핑이 `application/octet-stream`(또는 무관한 것)을 반환 → "File content does not match extension" 또는 "File detected as generic binary type."로 거부.
바이너리 암호문으로 암호화된 일반 텍스트 형식(`.txt`, `.csv`, `.json`, `.md`, `.xml`, `.html`)	아니오	스니핑이 `text/*` 타입을 반환하지 않아 확장자/콘텐츠 검사 실패.
전체가 암호화된 ZIP 압축 파일	아니오	외부 압축 파일은 읽을 수 있는 ZIP이어야 하며 AAEKB가 항목을 검사합니다. 추가로, 암호화된 멤버를 포함한 ZIP 파일은 압축 파일 검증기에서 거부됩니다.
불투명 암호문으로 암호화된 이미지, 오디오, 비디오	아니오	동일한 스니핑 불일치.

경험 규칙: 이 통합은 인식 가능한 헤더를 유지하는 암호화 Office 문서와 암호화/DRM 보호 PDF를 위해 설계되었으며 안정적으로 작동합니다. 암호화가 모든 구조적 마커를 파괴하는 형식은 서비스가 호출되기도 전에 차단됩니다.

DRM 시스템이 완전히 불투명한 암호문을 생성하면, 지원되는 우회법은 내보내는 시스템이 페이로드를 적절한 헤더 바이트를 유지하는 OOXML 또는 PDF 컨테이너로 감싸 전송 중에도 파일이 인식 가능하게 유지하도록 하는 것입니다. 또는 AAEKB 담당자에게 문의하세요 — 콘텐츠 검증 레이어는 배포 수준에서 구성 가능하며 온프레미스 설치를 위해 조정될 수 있습니다.

복호화 이후

복호화된 바이트가 돌아오면 AAEKB는 타입을 다음과 같이 결정합니다:

원래 파일명에 대한 mimetypes.guess_type() — 따라서 거의 모든 경우 업로드에 사용한 확장자가 수집 경로를 결정합니다.
그것이 아무것도 내주지 않으면, libmagic가 복호화된 내용의 첫 2 KB를 스니핑합니다.

복호화된 내용은 적절한 핸들러로 라우팅됩니다: PDF, Word, Excel, PowerPoint, HTML, XML/DITA, 일반 텍스트, JSON, CSV/TSV, EML, MSG, 오디오(전사), 비디오(전사), 또는 ZIP(멤버 추출 및 수집).

타입을 결정할 수 없으면 파일은 최선의 텍스트 추출을 시도하는 범용 핸들러로 떨어집니다. 업로드는 여전히 성공하고 파일은 저장되어 다운로드 가능하지만, 빈 텍스트 내용으로 색인될 수 있습니다 — 즉 의미 검색으로 검색할 수 없다는 뜻입니다. 이는 복호화 서비스가 예상된 형식이 아닌 것(예: 원시 바이트 대신 base64 텍스트)을 반환할 때의 전형적인 증상입니다.

기능 상호작용

기능	상호작용
Quick Upload 토글	호환. 복호화는 요청 내에 인라인으로 실행되며, 사용자는 모달이 완료되기 전 전체 복호화 왕복을 기다립니다.
폴더 업로드	호환; 토글은 폴더의 모든 파일에 적용됩니다.
암호화 파일의 컨테이너로서의 암호화 ZIP	미지원. 복호화는 압축 파일 추출 전에 업로드된 파일 전체에 적용됩니다. ZIP 내부 멤버는 개별적으로 복호화되지 않습니다.
URL / 커넥터 수집 (SharePoint, Confluence, 웹 크롤, Google Drive 등)	미지원. 복호화는 지식 베이스 업로드 모달과 `add/file` API 엔드포인트를 통한 직접 파일 업로드에만 적용됩니다.
채팅 첨부 업로드	UI에 노출되지 않음.
기존 문서의 재동기화 / 재처리	저장된 파일은 이미 복호화되어 있으므로 재처리는 정상적으로 작동하며 서비스를 다시 호출하지 않습니다.

타임아웃, 제한 및 크기 산정

작업	제한	구성 가능
복호화 엔드포인트로의 제출 요청	300초	아니오
개별 폴링 요청 각각	60초	아니오
JSON "완료" 후의 후속 바이너리 가져오기	120초	아니오
총 폴링 윈도	`poll_interval_seconds × poll_max_attempts` — 기본값 600초 (10분)	예
최대 업로드 크기	4096 MB (4 GB)	배포 수준
실패 시 재시도	없음	아니오

크기 산정 지침:

복호화는 완전히 메모리에서 이루어집니다. 동시 복호화당 피크 메모리는 정상 요청 오버헤드에 더해 대략 파일 크기의 2배(암호문 플러스 평문)입니다. API와 워커 컨테이너를 그에 맞게 크기 산정하거나, 암호화 업로드의 실질적 업로드 크기를 4GB 상한보다 충분히 아래로 제한하세요.
서비스가 제출을 수락하는 데 5분 이상 걸릴 수 있다면 async 모드를 사용해야 합니다 — 300초 제출 타임아웃은 조정할 수 없습니다.
복호화 자체가 10분 이상 걸릴 수 있다면 poll_max_attempts(또는 poll_interval_seconds)를 그에 맞게 올리세요.
각 진행 중인 복호화는 폴링 대기 시간을 포함한 전체 기간 동안 워커 스레드를 점유합니다. 긴 복호화 시간의 대량 암호화 파일 벌크 수집은 워커 용량을 소모할 것입니다. 이를 감안해 동시성을 계획하세요.

스토리지, 보안 및 감사 동작

무엇이 저장되는가

AAEKB는 복호화된 파일을 지식 베이스 원시 파일 스토리지에 저장하며, 암호문은 저장하지 않습니다.

이는 수집 후 원시 저장 파일을 제품의 여러 부분이 다시 읽기 때문입니다: 인앱 문서 미리보기, 다운로드, 인용 렌더링, 테이블 및 스프레드시트 추출, 그리고 문서의 이후 재처리 또는 재색인. 평문을 저장하면 이것들이 모두 직접 작동하며, 복호화 서비스가 문서당 정확히 한 번 — 업로드 시 — 호출되고 모든 읽기마다 호출되지 않게 됩니다. 또한 일상적 사용자 활동의 크리티컬 경로에서 복호화 서비스를 제거하므로, 그 서비스의 장애가 지식 베이스에 이미 있는 문서의 접근에 절대 영향을 주지 않습니다.

수집 후에는 문서가 AAEKB 자체 통제로 보호됩니다: 기반 객체 스토리지가 제공하는 저장 시 암호화, 그리고 누가 볼 수 있고 검색하고 다운로드할 수 있는지를 관장하는 AAEKB의 프로젝트·팀·역할 수준 접근 통제.

각 복호화된 문서에 기록되는 메타데이터

{
  "originally_encrypted": true,
  "decryption_service": "Corporate DRM Gateway",
  "decrypted_at": 1774000000.123
}

decryption_service는 구성된 Display Name입니다.
decrypted_at는 Unix 에포크 타임스탬프(초, float)입니다.
originally_encrypted는 정보용 마커로, 관리자와 최종 사용자가 어떤 문서가 암호화된 채 왔는지 식별할 수 있게 합니다. 처리에는 영향을 주지 않습니다: 저장된 파일이 이미 복호화되어 있으므로 문서를 재처리해도 복호화 서비스가 다시 관여하지 않습니다.

자격 증명 처리

auth_token은 AAEKB 애플리케이션 데이터베이스에 저장됩니다.
관리자 API나 UI를 통해 구성이 읽힐 때마다 마스킹됩니다: 처음 네 문자만 반환되고 나머지는 불릿 문자로 대체됩니다. 마스킹된 값의 저장은 감지되어 무시되므로, 폼을 다시 저장해도 저장된 자격 증명이 손상되지 않습니다.
구성의 모든 변경은 슈퍼 관리자 감사 로그에 이벤트 kb_decryption_service_updated로 기록되며, 자격 증명을 제외한 모든 필드의 전/후 값을 기록합니다(자격 증명은 auth_token_rotated: true로만 기록됨). 토큰 값은 절대 감사 기록이나 로그에 나타나지 않습니다.

접근 통제

구성의 읽기와 쓰기는 슈퍼 관리자 권한이 필요합니다.
가용 상태 엔드포인트는 인증된 세션을 요구하지만 특별한 역할은 필요 없으며, 불리언만 반환합니다.
관리자가 아닌 사용자는 엔드포인트 URL, 헤더, 자격 증명을 절대 볼 수 없습니다.

로깅

AAEKB는 복호화 중 파일명, 바이트 수, 작업 식별자를 INFO 수준으로 로그합니다. 파일 내용이나 자격 증명은 로그하지 않습니다. 사용자에게 반환되는 오류 메시지는 서비스의 오류 응답 본문의 처음 500자를 포함할 수 있습니다 — 오류 본문에 민감한 자료를 반환하지 마세요.

오류 레퍼런스 및 문제 해결

사용자가 보는 메시지	HTTP	원인	해결
`File type '.enc' not allowed. Allowed types include: ...`	400	허용 목록에 없는 확장자	내보내기 시 원래 확장자 유지
`File must have an extension`	400	파일명에 확장자 없음	올바른 확장자 추가
`File content does not match extension`	400	암호문이 주장된 타입으로 스니핑되지 않음	암호문 봉투 호환성 참조
`File detected as generic binary type. Cannot verify file safety.`	400	비Office 확장자의 불투명 암호문	암호문 봉투 호환성 참조
`Encrypted ZIP files are not allowed`	400	비밀번호 보호 멤버가 있는 ZIP	문서를 개별적으로 업로드하거나 비암호화 압축 사용
`File too large (max 4096MB)`	400	크기 상한 초과	문서 분할
`File was marked as needing decryption, but no external decryption service is currently enabled...`	400	서비스가 비활성인데 `needs_decryption=true` 전송	서비스를 활성화하거나, 페이지를 새로 고쳐 토글이 사라지게 하세요
`Failed to reach the external decryption service: ...`	502	DNS, TLS, 연결 거부 또는 타임아웃	API와 워커 컨테이너 모두에서 네트워크 경로, 방화벽, TLS 신뢰 확인
`Decryption service returned HTTP 4xx/5xx: ...`	502	서비스가 제출을 거부	인용된 본문 검사; 인증 헤더 확인
`Decryption service returned a non-JSON response without file content.`	502	async 제출이 바이너리 본문도 파싱 가능한 JSON도 반환하지 않음	JSON 작업 객체의 `202` 또는 `application/octet-stream`의 `200` 반환
`Could not extract job_id from decryption response using path 'job_id'.`	502	`poll_job_id_json_path`가 응답 형태와 불일치	점 경로 수정, 예: `data.jobId`
`Decryption poll returned HTTP 404: ...`	502	폴링 엔드포인트가 아직 준비 안 된 작업에 `4xx` 반환	보류 중에는 `202` 반환
`External decryption job failed with status: FAILED`	502	서비스가 실패 상태 보고	서비스 로그에서 조사
`Decryption job completed but no file stream was returned.`	502	JSON으로 완료를 보고했지만 후속 GET이 바이너리를 반환하지 않음	완료 시 바이트 스트림 반환 — 이중 GET 동작 참조
`Decryption service returned empty content.`	502	길이 0의 응답 본문	실제 복호화 바이트 반환
`Decryption service timed out after 600s of polling.`	504	`interval × max_attempts` 초과	`poll_max_attempts`를 올리거나 복호화를 가속
`Decryption service config not found. Run the migration first.`	404	데이터베이스 마이그레이션 미적용	AAEKB 데이터베이스 마이그레이션 실행

진단 팁

토글이 나타나지 않음 → GET /kb-decryption-service/status 확인; {"available": false}를 반환하면 구성 행이 없거나 enabled가 false입니다. 브라우저 캐시 만료까지 약 30초도 허용하세요.
Quick Upload에서는 되는데 일반 업로드에서는 안 됨(또는 그 반대) → 거의 항상 API 컨테이너와 백그라운드 워커 컨테이너 간의 네트워크 도달 가능성 차이입니다.
업로드는 성공하는데 문서에 검색 가능한 내용이 없음 → 서비스가 원래 형식의 원시 바이트가 아닌 것을 반환하고 있을 가능성(흔히 base64나 JSON 래퍼). curl로 응답 본문이 예상된 매직 바이트로 시작하는지 검증하세요.

배포 및 네트워킹 요건

두 곳에서의 도달 가능성. AAEKB API 컨테이너와 AAEKB 백그라운드 워커 컨테이너 모두 decrypt_endpoint와 poll_endpoint_template을 해석하고 도달할 수 있어야 합니다. Kubernetes 배포에서는 네트워크 정책이 두 워크로드의 아웃바운드를 허용하는지 확인하세요.
TLS 신뢰. AAEKB는 컨테이너 이미지의 표준 신뢰 CA 번들로 TLS 인증서를 검증합니다. 비공개/내부 CA의 인증서를 제시하는 복호화 서비스는 배포의 일환으로 그 CA를 AAEKB 컨테이너 신뢰 저장소에 추가하지 않는 한 연결에 실패합니다. 이를 계획하세요 — 인트라넷 배포에서 흔한 첫 실행 차단 요소입니다. 인증서 검증은 관리자 UI에서 비활성화할 수 없습니다.
평문 HTTP. http:// 엔드포인트는 작동하지만 강력히 권장되지 않습니다. 응답 다리에서 평문 문서가 보호 없이 네트워크를 지나가기 때문입니다.
안정적인 호스트명. 엔드포인트는 리터럴 URL로 저장됩니다. 파드 IP 대신 안정적인 내부 DNS 이름이나 서비스 주소를 사용하세요.
지연 예산. 제출 호출은 최대 300초 동안 연결을 유지합니다. 중간의 로드 밸런서, 인그레스 컨트롤러, 프록시가 최소 그만큼의 유휴/읽기 타임아웃을 갖도록 하세요. 그렇지 않으면 AAEKB가 포기하기 전에 연결을 끊을 것입니다.
데이터베이스 마이그레이션. 이 기능은 비활성 기본 행 하나를 시드하는 표준 AAEKB 마이그레이션이 생성하는 kb_decryption_service_config 테이블이 필요합니다. 슈퍼 관리자가 활성화하기 전까지 이 기능은 무효입니다.

롤아웃 및 검증 체크리스트

프로덕션 활성화 전

복호화 서비스가 배포되어 AAEKB 네임스페이스의 테스트 파드에서 도달 가능(API 파드 그리고 워커 파드 둘 다에서 curl)
AAEKB 컨테이너가 신뢰하는 TLS 인증서 체인
AAEKB 데이터베이스 마이그레이션 적용; KB Decryption Service 탭이 "table not found" 오류 없이 로드됨
대표 샘플로 암호화된 파일이 업로드 검증을 통과하는지 확인 — 수집하려는 각 형식의 실제 암호화 문서 세 개를 가져와 업로드하세요. 이것이 가장 흔한 실패 지점인 암호문 봉투 호환성을 검증합니다

구성

decrypt_endpoint 설정, 메서드와 콘텐츠 타입이 서비스와 일치
decrypt_file_field_name이 서비스가 기대하는 폼 필드와 일치 (멀티파트 모드)
response_mode가 서비스의 동작과 일치
async의 경우: poll_endpoint_template에 {job_id} 포함; 서비스에서 캡처한 실제 응답으로 JSON 경로 검증
poll_interval_seconds × poll_max_attempts가 최악의 복호화 시간을 넉넉히 초과
AAEKB가 보낼 것과 정확히 동일한 헤더로 인증 구성 및 curl 검증
Display Name을 의미 있는 것으로 설정 — 각 복호화된 문서의 메타데이터에 기록됩니다

기능 테스트

토글 켬으로 암호화 파일 업로드 → 문서 수집, 내용 검색 가능
토글 꺼짐으로 비암호화 파일 업로드 → 영향 없음
토글 켬으로 비암호화 파일 업로드 → 서비스가 명확한 오류를 반환해야 함; 메시지가 사용자에게 타당하게 표시되는지 검증
서비스 실패 강제 (서비스 중지) → 사용자가 502급 오류를 보며, 부분 문서가 색인되지 않음
예상되는 최대 파일로 테스트하고 타이밍이 폴링 예산 안에 있는지 확인
다중 파일 배치와 폴더 업로드로 테스트
복호화된 문서가 지식 베이스에서 올바르게 다운로드되고 메타데이터가 originally_encrypted: true를 보여주는지 검증

운영

자격 증명 교체 절차 문서화 (관리자 UI 또는 PUT API로 재저장)
복호화 서비스에 대한 모니터링/알림, 자체 오류율과 지연 포함
구성 변경이 포착되고 있는지 슈퍼 관리자 감사 로그 검토

알려진 제한

배포당 하나의 서비스. 프로젝트별, 팀별, 파일 타입별로 다른 복호화 서비스로의 라우팅이 없습니다.
배치 수준 토글만. 암호화 및 비암호화 파일을 단일 업로드 배치에 혼합할 수 없습니다.
직접 업로드만. 커넥터 기반 수집(SharePoint, Confluence, Google Drive, 웹 크롤 등)은 복호화를 호출하지 않습니다.
재시도 없음. 일시적 네트워크 요인 하나가 업로드를 실패시킵니다. 사용자가 수동으로 재시도해야 합니다.
정적 자격 증명. AAEKB 자체의 OAuth 토큰 갱신, HMAC 서명, 클라이언트 인증서 mTLS 없음. 그런 방식에는 인증 프록시를 사용하세요.
사용자별 또는 문서별 인가 컨텍스트가 복호화 서비스로 전달되지 않습니다. AAEKB가 보내는 정보에 기반한 주체별 DRM 정책을 강제할 수 없습니다.
파일은 수집 후 복호화된 채 저장됩니다. AAEKB 자체의 접근 통제와 스토리지 암호화 아래에서. 스토리지, 보안 및 감사 동작 참조.
"연결 테스트" 버튼 없음. 검증은 실제 업로드를 수행하여 이루어집니다.
완전히 불투명한 암호문은 대부분의 형식에서 사전 복호화 콘텐츠 검증에 의해 차단됩니다. 암호문 봉투 호환성 참조.
중첩 복호화는 미지원. ZIP 내부 멤버는 개별적으로 복호화되지 않습니다.

FAQ

AAEKB가 우리 암호화 키를 보게 됩니까? 아니요. AAEKB는 통제하는 엔드포인트로 암호문을 보내고 평문을 돌려받습니다. 키 자료, 알고리즘, DRM 정책 엔진에 대한 지식이 없습니다.

복호화 서비스를 완전히 우리 인트라넷에서 실행할 수 있습니까? 네 — 그것이 주 용도입니다. 엔드포인트는 AAEKB API 및 워커 컨테이너에서 도달 가능하기만 하면 됩니다. 온프레미스 AAEKB 배포에서는 아무것도 네트워크 밖으로 나갈 필요가 없습니다.

어떤 응답 모드를 사용해야 합니까? 복호화가 몇 초 안에 안정적으로 완료되고 서비스가 연결을 유지할 수 있다면 sync를 사용하세요. 더 느리거나 배치 처리되거나 큐 기반이면 async를 사용하세요. 폴링 엔드포인트가 완료 시 바이트 스트림을 직접 반환하는 async가 가장 견고한 구성입니다.

복호화 서비스가 다운되면 어떻게 됩니까? 토글이 켜진 업로드는 명확한 오류로 실패합니다. 일반 업로드는 영향을 받지 않습니다. 이미 수집된 문서도 영향을 받지 않습니다 — 복호화된 채 저장되며 다시는 서비스가 필요 없습니다.

기능을 일시적으로 끌 수 있습니까? 네. Enabled를 끄세요. 최종 사용자 토글은 약 30초 안에 사라지고, 여전히 needs_decryption=true를 주장하는 어떤 업로드든 설명 메시지와 함께 거부됩니다.

사용자가 어떤 문서가 원래 암호화되었는지 알 수 있습니까? 네 — 복호화된 문서는 메타데이터에 originally_encrypted: true, 복호화 서비스의 표시 이름, 복호화 타임스탬프를 담고 있습니다.

우리의 암호화 파일은 DRM 시스템에서 document.pdf.encrypted라는 이름으로 나옵니다. 작동합니까? 아니요. 업로드 전에 document.pdf로 이름을 바꾸세요. AAEKB는 복호화 전에 확장자를 검증하며 래퍼 확장자를 인식하지 않습니다. 파일명 및 래퍼 호환성 참조.

우리의 암호문은 완전히 불투명합니다 — 인식 가능한 헤더가 전혀 없습니다. 옵션이 무엇입니까? 업로드는 서비스에 도달하기 전에 거부됩니다. 옵션: (a) 내보내는 시스템이 원래 형식 헤더를 유지하거나 앞에 붙이게 하고, (b) 명시적으로 지원되는 Office 문서용 OOXML/OLE2 기반 봉투 암호화를 사용하거나, (c) 온프레미스 설치를 위해 AAEKB 담당자와 콘텐츠 검증의 배포 수준 조정을 논의하세요.

복호화 서비스가 바이트 대신 다운로드 URL을 반환할 수 있습니까? 아니요. AAEKB는 응답 본문에서 복호화된 내용을 읽으며 JSON에 반환된 URL을 따르지 않습니다.

Quick Upload에서 작동합니까? 네. 사용자가 업로드 모달이 완료되기 전 전체 복호화 왕복을 기다립니다.

문서 버전 1.0. 기능 레퍼런스: EN-3043.

이 기능이 하는 일​

처음부터 끝까지의 동작 방식​

서비스 구성 (슈퍼 관리자)​

전체 구성 레퍼런스​

일반​

복호화 요청​

비동기 폴링 (response_mode = async일 때만 사용)​

인증​

복호화 서비스가 구현해야 할 계약​

타협 불가 요건​

제출 엔드포인트​

폴링 엔드포인트 (async 모드)​

이중 GET 동작 (async 모드)​

Content-Type 지침​

AAEKB가 절대 하지 않는 일​

실제 예제: 동기 모드​

실제 예제: 비동기 (폴링) 모드​

인증 옵션​

최종 사용자 경험​

호환성: 작동하는 것과 작동하지 않는 것​

핵심 제약: 검증은 복호화보다 먼저 일어납니다​

지원되는 파일 확장자​

파일명 및 래퍼 호환성​

암호문 봉투 호환성​

복호화 이후​

기능 상호작용​

타임아웃, 제한 및 크기 산정​

스토리지, 보안 및 감사 동작​

무엇이 저장되는가​

각 복호화된 문서에 기록되는 메타데이터​

자격 증명 처리​

접근 통제​

로깅​

오류 레퍼런스 및 문제 해결​

배포 및 네트워킹 요건​

롤아웃 및 검증 체크리스트​

알려진 제한​

FAQ​