사용자 이름과 이메일 데이터베이스에 암호화해 저장

매뉴얼웍스 6.0.17 버전부터 사용자 이름과 이메일을 데이터베이스에 암호화해서 저장하는 기능을 지원합니다.

매뉴얼웍스는 사용자(R_USER) 테이블의 이름과 이메일을 AES-256/GCM 알고리즘으로 암호화해 저장하는 기능을 제공합니다. 이 기능을 활성화하면 사용자를 저장할 때 이름과 이메일을 암호화하고, 조회할 때 자동으로 복호화합니다.

사용자 정보 암호화 활성화

사용자 정보 암호화 기능은 시작 시크립트 옵션으로 켜고 끕니다. 시작 스크립트 옵션에 다음 옵션을 추가합니다.

3rabbitz.enable_user_encryption=true

속성 값을 설정하지 않거나 true가 아닌 값을 설정하면 암호화 기능이 비활성화됩니다.

키 파일

암호화에 사용하는 키는 데이터 디렉터리의 .key.json 파일에 저장됩니다.

서버 이중화 환경에서는 모든 노드가 같은 키 파일을 사용해야 합니다. 키 파일을 데이터 디렉터리에 두지 않으면 노드별로 다른 키가 생성되어 서로 암호화한 데이터를 복호화할 수 없습니다.

키 파일은 다음과 같은 JSON 형식입니다.

{
    "active": "k1",
    "keys": {
        "k1": "Base64로 인코딩된 32바이트 키"
    }
}

키 ID 규칙

키 ID에는 다음 규칙을 적용합니다.

암호화한 값의 형식

암호화한 값은 다음 형식의 접두사를 가집니다.

{v:키ID}Base64로 인코딩된 IV+암호문

예를 들어 k1 키로 암호화한 값은 다음과 같이 시작합니다.

{v:k1}fI3YfyWSJ+...

접두사 덕분에 어떤 키로 암호화했는지 식별할 수 있어 키 회전이 가능합니다.

콘솔에서 generate-key 명령어로키를 만들 수 있습니다.

generate-key

평문 모드(plain mode)

암호화를 적용하지 않은 평문으로 사용자 정보를 저장하려면 키 파일의 active 값을 plain으로 설정합니다.

{
    "active": "plain",
    "keys": {
        "k1": "Base64로 인코딩된 32바이트 키"
    }
}

평문 모드에서는 다음과 같이 동작합니다.

키 회전

키를 교체하려면 새 키를 추가하고 active 값을 새 키 ID로 변경합니다.

{
    "active": "k2",
    "keys": {
        "k1": "이전 키",
        "k2": "새 키"
    }
}

마이그레이션을 마친 후에도 keys에서 k1을 바로 제거하지 않습니다. 백업이나 다른 노드에 남아 있는 데이터가 k1 키를 필요로 할 수 있기 때문입니다.

사용자 정보 마이그레이션

사용자 정보 암호화 기능을 처음 켜거나 키를 회전한 후에는 마이그레이션을 실행해 모든 사용자 정보를 현재 활성 키로 다시 저장해야 합니다.

마이그레이션은 다음 순서로 실행합니다.

  1. 관리자 권한으로 로그인합니다.

  2. 1사용자 암호화 마이그레이션 페이지(/#/r/user_encryption)로 이동합니다.

  3. 페이지 위쪽에 표시한 활성 키 ID(key: k1 등)를 확인합니다.

  1. 2 버튼을 클릭합니다.

  2. 진행 상태를 확인하면서 모든 사용자가 처리될 때까지 기다립니다.

  3. 완료되면 완료되었습니다. 메시지가 표시됩니다.

마이그레이션은 모든 사용자 레코드를 다시 저장하는 작업입니다. 사용자 수가 많으면 시간이 걸릴 수 있으므로 사용자가 적은 시간대에 실행하는 것을 권장합니다.

운영 시 주의 사항

사용자 정보 암호화 기능을 운영할 때는 다음 사항에 주의합니다.