클라우드 다운로드 문서변환 기능

備考

클라우드 저장소(OneDrive, SharePoint, Teams)에서 다운로드 받은 문서에 대한 변환 기능을 수행합니다.

변환 방식에 대한 정의는 Ztcap 정책에 따릅니다.

1.개요

클라우드 저장소(OneDrive, SharePoint, Teams)에서 다운로드 받은 문서에 대한 변환 기능을 제공합니다.
변환에 대한 정책은 Ztcap 정책에 따릅니다.

2. 관련 모듈

파일명	경로	버전	설명	빌드 경로
SCRA_DS365Shell.dll	C:\Windows\Softcamp\sdk	6.0.0.17	탐색기, 브라우저, TeamsApp 훅모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS6.0_VS2019(ZTCA_AIP)\|
SCRA_DS365Shell64.dll	C:\Windows\Softcamp\sdk	6.0.0.17	탐색기, 브라우저, TeamsApp 훅모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS6.0_VS2019(ZTCA_AIP)\|
SCPD_DS365.dll	C:\Windows\Softcamp\sdk\scsa	6.0.3.0	문서보안 이벤트 모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS6.0_VS2019(ZTCA_AIP)\|
SCPD_DS36564.dll	C:\Windows\Softcamp\sdk\scsa	6.0.3.0	문서보안 이벤트 모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS6.0_VS2019(ZTCA_AIP)\|
DS365Lib64.dll	C:\Windows\Softcamp\Security365\DS365\x64	6.1.16.8	Mip 관련 DS모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS6.0_VS2019(ZTCA_AIP)\|
DSEDCon.dll	C:\Windows\Softcamp\SDS	6.0.0.7	문서보안 전역모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSEDCon64.dll	C:\Windows\Softcamp\SDS\x64	6.0.0.7	문서보안 전역모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
SCTL_ZipMngr.dll	C:\Windows\Softcamp\SDS	6.0.0.4	문서보안 Zip압축 유틸모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
SCTL_ZipMngr64.dll	C:\Windows\Softcamp\SDS	6.0.0.4	문서보안 Zip압축 유틸모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
SDSEnc.exe	C:\Windows\Softcamp\SDS	6.0.0.3	문서보안 보안문서 모듈	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSResChn.ini	C:\Windows\Softcamp\SDS	6.0.0.3	다국어 리소스	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSResCht.ini	C:\Windows\Softcamp\SDS	6.0.0.3	다국어 리소스	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSResCze.ini	C:\Windows\Softcamp\SDS	6.0.0.3	다국어 리소스	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSResDeu.ini	C:\Windows\Softcamp\SDS	6.0.0.3	다국어 리소스	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSResEng.ini	C:\Windows\Softcamp\SDS	6.0.0.4	다국어 리소스	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSResFra.ini	C:\Windows\Softcamp\SDS	6.0.0.3	다국어 리소스	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSResJpn.ini	C:\Windows\Softcamp\SDS	6.0.0.4	다국어 리소스	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSResKor.ini	C:\Windows\Softcamp\SDS	6.0.0.6	다국어 리소스	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|
DSResRus.ini	C:\Windows\Softcamp\SDS	6.0.0.4	다국어 리소스	\sctfsbuild.softcamp.co.kr\AzureBuild\2025\DS_vs2019\|

3. 관련 커스텀 정책

ID	HOOK_LOAD_DYNAMIC 정책설명링크
TYPE	EDIT
정책값 형식	모듈명1;x64(0) or x86(1);로드할프로세스명
설명	DSEDCon을 통해 로드할 모듈 설정 이 기능에서는 TeamsApp에 SCRA_DS365Shell 훅모듈을 로드하기위해 사용
정책 값	SCRA_DS365Shell.dll;1;msedgewebview2.exe

4. Ztcap 정책 관련

4-1 기능 동작시 Endpoint에서 ztcap으로 질의되는 decisionFactors 예시

// 단일 문서(docx Aip문서) 다운로드시 문서에 대한 질의 json
{
    "decisionFactors": [
  {
    "category": "document",
    "target": {
      "info": {
        "ext": "docx",
        "zoneIdentifier": "https://softcamp-my.sharepoint.com/personal/jaekwon_lee_softcamp_co_kr/_layouts/15/download.aspx?UniqueId=ed4e27ad%2Dda48%2D476b%2Da99a%2Dd517a54ad6db"
      },
      "type": "mip"
    }
  },
  {
    "category": "storage",
    "target": {
      "info": {
        "folder": "%USERS%\\Downloads"
      },
      "type": "local"
    }
  },
  {
    "category": "fileEvent",
    "target": {
      "info": {
        "event": "DownloadFile_FromCloud"
      },
      "type": "local"
    }
  }
]
}

// 여러문서 선택시 Zip파일에 대한 질의 json
{
    "decisionFactors": [
        {
        "category": "document",
        "target": {
            "info": {
                "ext": "zip",
                ...
                "zoneIdentifier": "https://japaneast1-mediap.svc.ms/transform/zip?cs=fFNQTw"
            },
            "type": "zipArchive"
        }
        },
        {
        "category": "storage",
        "target": {
            "info": {
                "folder": "%USERS%\\Downloads"
            },
            "type": "local"
        }
        },
        {
        "category": "fileEvent",
        "target": {
            "info": {
                "event": "DownloadFile_FromCloud"
            },
            "type": "local"
        }
        }
    ]
}

4-2 ztcap 정책 설정시 주의 사항

⚠️정책 설정시 아래사항이 반드시 고려되어 Ztcap 정책이 설정되어야 기능이 동작합니다.

decisionFactors중 category가 document인 json객체의 target.info.zoneIdentifier의 정책 설정이 필요합니다.
- decisionFactors중 category가 document인 json객체의 target.info.zoneIdentifier 의 정책값은 다운로드시 다운로드문서에 입력되는 ZoneIdentifier Url을 포함 할 수 있는 값이 설정되어야함.
- 예시 ) 다운로드 받은 문서의 Url이 https://japaneast1-mediap.svc.ms/transform/zip?cs=fFNQTw 라 가정할때 Ztcap 정책에 설정 되어야 하는 decisionFactors중 category가 document인 json객체의 target.info.zoneIdentifier 의 정책값은 "*mediap.svc.ms/transform/zip*" 과 같이 Url의 일부분 앞뒤로 와일드카드(*)를 붙여 설정함.
decisionFactors중 category가 document인 json객체의 target.type 의 정책값은 "ds"가 들어가는 것을 권장하지 않음 ( 클라우드에 DRM 문서가 있다는 가정인데 이 기능은 기본적으로 클라우드의 일반 문서 및 mip문서를 DRM 문서로 변환하기 위한 기능 )

decisionFactors중 category가 fileEvent인 json객체의 target.info.event는 반드시 "DownloadFile_FromCloud" 값으로 설정 ( Ztcap 콘솔 정책에는 현재 미지원 )

//Ztcap 정책 예시
"category": "document",
  "targets": [
    {
      "type": "normal",
      "use": true,
      "operation": "AND",
      "info": {
        "ext": [
          "pptx",
          "zip",
          "xlsx",
          "pdf",
          "ppt",
          "doc",
          "xls",
          "docx"
        ],
        "zoneIdentifier": [ // 다운로드 받은 문서의 zoneidentifier url이 정책에 포함되어야함
          "*microsoftonline.com*",        
          "*sharepoint.com*",
          "*mediap.svc.ms/transform/zip*"
        ]
      }
    }

    ....
    {
      "category": "fileEvent",
      "targets": [
        {
          "type": "local",
          "use": true,
          "operation": "OR",
          "info": {
            "event": [
              "DownloadFile_FromCloud" // 파일 이벤트는 DownloadFile_FromCloud가 설정되어야함함
            ]
          }
        }
      ]
    }

4-3 ztcap 정책 설정시 기본 포함 정책

備考

클라우드 저장소(OneDrive, SharePoint, Teams)에서 문서 다운로드 시 문서 Zone.identifier에 들어간 URL 정보가 기본적으로 ztcap 정책에 포함되어야하며, 차후 고객사나 클라우드쪽 변경사항에 따라 URL 정책의 추가가 필요할 수 있습니다.

ztcap 정책의 아래의 URL 값이 정책으로 포함되어야합니다.
- *mediap.svc.ms/transform/zip*
- *sharepoint.com*
- *microsoftonline.com*

클라우드 저장소 URL 정책 추가 방법

다운로드한 파일의 Zone.Identifier 파일 확인

# 명령 프롬프트(cmd)에서 확인
more < "filename:Zone.Identifier"

Zone.Identifier 파일에서 확인된 URL 정보를 바탕으로 정책 추가
- ReferrerUrl 또는 HostUrl 필드의 값을 확인
- URL의 도메인 부분을 정책에 추가
  - 정책 추가 시 자동으로 도메인 앞,뒤에 와일드카드(*)가 붙어 등록됩니다.
- 예시
  - https://example-cloud.com/download → example-cloud.com 입력 → *example-cloud.com* 적용 후 추가 완료

5. 적용 방법

모듈 패치
Ztcap 정책 설정 ( 4. Ztcap 정책 관련 항목 적용 필수 )
커스텀 정책 설정

6. 제약사항

OneDrive, SharePoint, Teams 이외의 클라우드 스토리지는 현재 미지원
훅 방식으로 다운로드 시점을 잡아 개발된 기능이라 아래 지원 버전 외의 브라우저나 그 이상의 브라우저에서 zoneidentifier 정보를 write하는 로직이 변경시 기능 동작이 되지 않을 수 있습니다.

프로그램	버전
Msedge
Chrome
TeamsApp

윈도우 및 문서보안 커스텀 정책 설정

ZoneIdentifier 사용 On/Off 윈도우 설정(레지스트리)은 다음과 같이 설정되어야 합니다.
- 레지스트리 경로 : HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Policies\Attachments
- 레지스트리 값 : SaveZoneInformation : 2 (또는 해당 항목이 없어야 다운로드 시 문서변환 기능 동작 함)

SaveZoneInformation 값	Zone Identifier (MoTW) 저장 여부	보안 경고 표시 여부 (일반적으로)
1 (Enabled)	저장하지 않음	표시되지 않음
2 (Disabled/Not Configured)	저장함	표시됨

문서보안 커스텀 정책
- DS_NOT_USE_SENDLOG_ZONE_IDF 커스텀 정책 0 또는 정책 미사용(제거)
  - 위 커스텀 정책이 1로 설정되어 있을 경우 다운로드 되는 문서 파일에 ZoneIdentifier 등록되지 않습니다. (SaveZoneInformation : 1 설정함)
  - 클라우드 다운로드 문서변환 기능은 ZoneIdentifier 등록 시점의 hooking 으로 동작합니다.

7. Troubleshooting

⚠️기능 미 동작시 아래와 같은 사항을 확인하여 어떤 사항에 해당하는지 확인필요

TeamsApp에서 미동작시
- Process Explorer등의 툴로 TeamsApp 하위 프로세스 msedgewebview2.exe에 SCRA_DS365Shell.dll이나 SCRA_DS365Shell64.dll 모듈이 로드되어있는지 확인
- 로드가 되어 있지 않은 경우 DSEDCon 버전 확인 및 커스텀 정책 적용 여부 확인
브라우저에서 미동작시
- Process Explorer등의 툴로 브라우저 프로세스 msedgewebview2.exe에 SCRA_DS365Shell.dll이나 SCRA_DS365Shell64.dll 모듈이 로드되어있는지 확인
- 로드가 되어 있지 않은 경우 SCRA_DS365Shell.dll 과 SCRA_DS365Shell64.dll 의 심플애드인 등록이 누락되어있는지 여부 확인 필요함.
공통
- SCRA_DS365Shell.dll가 정상적으로 로드되어있는 경우 다운로드 동작시 SDSMonitor 로그에 '[SCRA_DS365Shell64] Hooked_WritePrivateProfileStringW:526 L"[INFO] 조건 충족"' 이 수집되는지 확인
- SDSMonitor 로그 수집 시 로그에 [SCPD_DS365] GetZtcaPolicy:888 strLog.c_str() : '{"code":1621,"message":"Conditional policies does not exist that match the conditions"}' 와 같은 로그가 수집되는 경우 ztcap 정책 설정 오류이므로 ztcap 정책을 다시 확인필요
- 해당 로그가 없거나 수집이 되어도 동작이 안될 경우 SDSMonitor 로그를 수집하여 개발자에게 전달

1.개요​

2. 관련 모듈​

3. 관련 커스텀 정책​

4. Ztcap 정책 관련​

4-1 기능 동작시 Endpoint에서 ztcap으로 질의되는 decisionFactors 예시​

4-2 ztcap 정책 설정시 주의 사항​

4-3 ztcap 정책 설정시 기본 포함 정책​

5. 적용 방법​

6. 제약사항​

7. Troubleshooting​