= D-KMS 암호화 적용

SDL(표준개발라이브러리)에 D-KMS 암호화를 적용하는 방법에 대해 설명한다.

== 사전 준비

=== KMS 포털에서 암호화 권한 신청

. KMS 포털에서 계정을 인증하고 암호화 권한 신청, 결재
. 암호화 권한 결재 완료되면 D-KMS SDK 및 가이드 전송됨
. 전달 받은 SDK 설치 및  코드  적용

== 코드 적용

=== Credential 생성 및 환경변수 추가

. D-KMS 가이드를 참고하여 Credential을 생성하고 시스템 환경변수에 추가한다.

=== SDL 수정

. D-KMS 암호화 라이브러리 추가
  - https://code.sec.samsung.net/confluence/pages/viewpage.action?pageId=343332410[D-KMS 가이드]를 참고하여 라이브러리를 추가한다.

. src/main/resources-{local|dev|prod} 에 dkms.properties 파일을 추가한다. (배포된 sdl-appendix 내 참조)

IMPORTANT: - dkms.task-id 프로퍼티 값을 D-KMS 신청시 부여받은 값으로 수정해야한다. +
  - 기타 다른 프로퍼티 값도 제대로 설정되었는지 확인한다.

[start=3]
. mybatis typehandler 추가
  - 암호화 대상이 되는 컬럼에 대해 typehandler 를 적용한다.
  - com.samsung.dkms.handler 패키지 생성
  - EncryptionTypeHandler.java, NameEncryptionTypeHandler.java, EmailEncryptionTypeHandler.java, PhoneEncryptionTypeHandler.java, AddressEncryptionTypeHandler.java, BirthdayEncryptionTypeHandler.java 파일을 복사/붙여넣기 한다. (배포된 sdl-appendix 내 참조)

. mybatis-config.xml 수정
  - mapper xml 에 적용이 용이하도록 typehandler의 type alias 를 추가한다.
+
image::dkms_typehandler_alias.png[]

[start=5]
. mapper xml 에 mybatis typehandler 적용
  - 암호화가 필요한 컬럼에 해당하는 핸들러를 선택 적용한다.
  - mapper xml에 typehandler 적용 방법은 샘플파일(mapper-mybatis-user.xml, 배포된 sdl-appendix 내 참조)을 참고한다. (`*""유무에 유의*`)
    * select resultMap 적용 예
+
image::dkms_typehandler_select_resultmap.png[]

    * insert, update 적용 예
+
image::dkms_typehandler_insert.png[]
image::dkms_typehandler_update.png[]

    * 수정대상 mapper xml (배포판 기준)
+
----
mapper-mybatis-common.xml
mapper-mybatis-sample-approval-internal.xml
mapper-mybatis-sample-approval-knox.xml
mapper-mybatis-sample.xml
mapper-mybatis-sys-resource.xml
mapper-mybatis-user-sync.xml
mapper-mybatis-approval.xml
mapper-mybatis-user-role.xml
mapper-mybatis-user.xml
mapper-mybatis-workgroup-role.xml
mapper-mybatis-comment.xml
mapper-mybatis-post.xml
mapper-mybatis-email.xml
mapper-mybatis-mail-group.xml
mapper-mybatis-history.xml
mapper-mybatis-access-log.xml
mapper-mybatis-admin-address.xml
mapper-mybatis-knox-department-sync.xml
mapper-mybatis-knox-department.xml
mapper-mybatis-terms-use.xml
----

=== 테이블 수정 및 데이터 마이그레이션
. 테이블 컬럼 사이즈 변경
  - 암호화 대상 컬럼의 사이즈를 최소 255byte 가 되도록 변경한다.
. 기존 데이터 암호화를 위한 마이그레이션은 D-KMS 가이드를 참고한다.

CAUTION: *SQL기반의 Database의 경우, 개인정보가 암호화됨으로써 아래와 같은 SQL문에 영향이 발생* (D-KMS 소개자료 중 발췌) +
  Nondeterministic Encryption으로 인해 Equality 비교 불가 +
  : WHERE, GROUP BY, JOIN (ON), DISTINCT, HAVING, ORDER BY +
  -> 일반적으로 Application Level에서 Filtering, Grouping, Joining 구현 필요 +
  +
  *대안: 별도 Column에 Hash 데이터를 추가 저장* +
  Hash로 인해 영향 받는 SQL문: WHERE (비교에 사용하는 데이터 역시 Hash 필요. Equality 비교는 가능하나 LIKE 또는 대소비교 불가), ORDER BY +
  -> 단, 모든 데이터가 Hash되어있지 않은 경우 GROUP BY에 영향을 줄 수 있음