Documentation index for AI agents

GS2-Key

암호화 키 관리 기능

GS2-Key는 GS2 내에서 사용되는 암호화 키(대칭키)를 관리하고, AES를 이용한 암호화·복호화 API를 제공하는 서비스입니다.

기밀성이 높은 데이터를 서버 측에서 암호화·복호화하는 용도 외에도, GS2 자체가 내부적으로 사용하는 각종 서명·암호화 처리를 위한 키 관리 기반으로도 활용됩니다.

암호화 키 관리

GS2-Key에서는 암호화 키를 네임스페이스 하위에 생성하여 관리합니다.

키에는 다음과 같은 정보를 담을 수 있습니다.

  • 키 이름
  • 설명(description: 용도나 설명 등, 운용상의 식별에 사용)

실제 암호화에 사용되는 비밀키(시크릿)는 키 생성 시 GS2 측에서 안전하게 생성되어 GS2 내부에 보관됩니다. 비밀키 자체를 클라이언트 측에서 꺼내어 사용하는 설계가 아니라, 암호화·복호화 요청을 GS2-Key에 전송하고 결과만 받는 구조로 되어 있습니다.

graph TD
  App["애플리케이션"] -->|"Encrypt(평문)"| Key["GS2-Key"]
  Key -->|"암호문"| App
  App -->|"서버에 저장 또는 전송"| Storage["데이터 스토어"]
  Storage -->|"암호문"| App2["애플리케이션"]
  App2 -->|"Decrypt(암호문)"| Key
  Key -->|"평문"| App2

활용 사례

GS2 내부에서의 활용

GS2-Account의 비밀번호 서명이나 GS2-Auth의 토큰 발급 등, GS2 내부에서 기밀 데이터를 다루는 마이크로서비스는 GS2-Key가 관리하는 키를 사용합니다. 각 마이크로서비스의 네임스페이스를 생성할 때 키를 지정함으로써, 해당 네임스페이스 내에서 필요한 암호화 처리에 사용됩니다.

애플리케이션 자체 데이터의 암호화

애플리케이션 자체에서 기밀 정보를 다루는 경우에도, GS2-Key의 Encrypt / Decrypt API를 직접 호출해 암호화·복호화를 수행할 수 있습니다. 비밀키를 애플리케이션 내에 내장하지 않고도 서버 사이드에서의 암호화를 구현할 수 있습니다.

기밀성이 높은 설정값이나 외부 서비스에 대한 인증 정보 등을 GS2 측에서 안전하게 관리하고 싶은 상황에서 활용할 수 있습니다.

트랜잭션 액션

GS2-Key에서는 트랜잭션 액션을 제공하지 않습니다.

마스터 데이터 관리

GS2-Key에는 마스터 데이터 등록이 없습니다. 관리 콘솔, GS2-Deploy, API를 통해 키를 생성·관리합니다.

구현 예제

GS2-Key는 관리 API/서버 사이드 API 중심의 마이크로서비스입니다. 게임 엔진용 SDK(Unity / Unreal Engine / Godot)에는 전용 Domain 클래스가 제공되지 않습니다.

키 생성이나 Encrypt / Decrypt 호출은, 주로 GS2 내부의 각 마이크로서비스에서 참조하는 형태로 사용하거나, GS2-Script에서 서버 사이드로 호출하는 형태로 사용하는 것을 상정하고 있습니다. 직접 API를 호출하는 경우에는 다음 중 하나의 방법으로 조작하는 것을 권장합니다.

  • 관리 콘솔(키의 생성·관리)
  • GS2-Deploy를 통한 템플릿 관리(키를 코드화하여 관리)
  • GS2-Script에서의 호출(Encrypt / Decrypt를 서버 사이드 로직 내에서 사용)
  • 각종 언어용 일반 SDK(C# / Go / Python / TypeScript / PHP / Java)를 통한 백엔드 서버에서의 호출
  • GS2 CLI

각 SDK의 자세한 내용은 해당 레퍼런스 페이지를 참조해 주세요.

보다 실전적인 정보

키 로테이션

보안 정책에 따라 암호화 키를 정기적으로 교체(로테이션)하고 싶은 경우, 새 키를 생성하고 이후의 암호화 처리를 새 키로 전환하는 운용이 가능합니다. 기존 키는 복호화 용도를 위해 바로 삭제하지 않고, 암호문 이전이 완료될 때까지 보관하는 설계를 권장합니다.

GitHub API 키 관리

GS2-Key에서는 암호화 키 외에도, GitHub에서 마스터 데이터를 가져올 때 사용하는 API 키를 보관할 수 있습니다. 마스터 데이터 가져오기에 사용되는 GS2-Deploy나 각종 마이크로서비스는, 여기에 등록한 API 키를 참조함으로써 프라이빗 저장소에 접근할 수 있습니다.

상세 레퍼런스

GS2-Key API 레퍼런스