이 가이드는 개인 키를 저장하고 처리하기 위해 하드웨어 보안 모듈(HSM)을 사용하도록 Teleport Auth Service를 설정하는 방법을 보여줍니다.

작동 방식#

Teleport Auth Service는 사용자가 Teleport로 보호된 리소스에 인증하기 위한 인증서 발급과 같은 중요한 클러스터 작업에 사용하는 여러 인증 기관을 유지합니다. 각 인증 기관은 개인 키를 사용하여 인증서에 서명합니다. 자체 호스팅 클러스터에서 Teleport Auth Service가 HSM에서 얻은 개인 키로 인증서에 서명하도록 지시할 수 있습니다.

사전 요구사항#

• Teleport Enterprise (자체 호스팅).
• Teleport Auth Service에서 접근 가능한 HSM.
• HSM용 PKCS#11 모듈.

대부분의 PKCS#11 HSM이 지원되어야 하지만 Teleport 팀은 AWS CloudHSM, YubiHSM2, SoftHSM2로 테스트합니다.

1단계/5. HSM 설정#

HSM을 설정하고 Teleport Auth Service에서 접근 가능한지 확인해야 합니다. Teleport가 사용할 고유한 HSM 사용자 또는 토큰을 생성해야 합니다.

AWS CloudHSM:

1. Teleport Auth Service를 실행할 VPC에서 CloudHSM 클러스터를 생성합니다. https://docs.aws.amazon.com/cloudhsm/latest/userguide/create-cluster.html

2. 새로 생성된 클러스터가 "Uninitialized" 상태가 될 때까지 기다립니다.

3. AWS 콘솔 또는 AWS CLI를 사용하여 새 클러스터에 HSM을 추가합니다. 을 AWS 리전으로, 을 가용성 영역으로 지정합니다:

   $ aws --region  cloudhsmv2 create-hsm --cluster-id  --availability-zone 
   {
       "Hsm": {
           "AvailabilityZone": "ca-central-1a",
           "ClusterId": "cluster-6uysmebmutd",
           "SubnetId": "subnet-0c535b67a117f7186",
           "HsmId": "hsm-ppzzfxbleki",
           "State": "CREATE_IN_PROGRESS"
       }
   }
   

4. 선택적으로 새 HSM의 신원 및 진위를 확인합니다. https://docs.aws.amazon.com/cloudhsm/latest/userguide/verify-hsm-identity.html

5. HSM의 상태가 ACTIVE가 될 때까지 기다립니다:

   $ aws --region  cloudhsmv2 describe-clusters --filters clusterIds= \
         --query 'Clusters[].Hsms[].State'
   

6. 클러스터를 초기화하려면 클러스터의 첫 번째 HSM에서 생성된 인증서 서명 요청(CSR)을 다운로드하고 서명해야 합니다. AWS 콘솔에서 또는 AWS CLI를 통해 CSR을 다운로드합니다:

   $ aws --region  cloudhsmv2 describe-clusters --filters clusterIds= \
         --query 'Clusters[].Certificates.ClusterCsr' --output text \
         > ClusterCsr.csr
   

7. HSM CSR에 서명할 적절한 RSA 2048 또는 RSA 4096 키와 자체 서명 인증서를 선택합니다. 프로덕션 클러스터의 경우 AWS는 보안이 확보된 오프사이트 오프라인 HSM을 권장합니다. 데모 또는 테스트 클러스터의 경우 다음 openssl 명령으로 키와 자체 서명 인증서를 생성할 수 있습니다:

   $ openssl genrsa -aes256 -out customerCA.key 2048
   $ openssl req -new -x509 -days 3652 -key customerCA.key -out customerCA.crt
   

8. 이전 단계의 키와 자체 서명 인증서를 사용하여 클러스터 CSR에 서명합니다. CSR에 서명하는 데모 openssl 명령은 다음과 같습니다:

   $ openssl x509 -req -days 3652 -in ClusterCsr.csr \
         -CA customerCA.crt \
         -CAkey customerCA.key \
         -CAcreateserial \
         -out CustomerHsmCertificate.crt
   

9. AWS 콘솔에 서명된 인증서를 업로드하거나 다음 AWS CLI 명령을 사용하여 CloudHSM 클러스터를 초기화합니다:

   $ aws --region  cloudhsmv2 initialize-cluster --cluster-id  \
         --signed-cert file://CustomerHsmCertificate.crt \
         --trust-anchor file://customerCA.crt
   {
       "State": "INITIALIZE_IN_PROGRESS",
       "StateMessage": "Cluster is initializing. State will change to INITIALIZED upon completion."
   }
   

10. 클러스터를 생성할 때 CloudHSM 클러스터와 동일한 이름의 보안 그룹이 자동으로 생성됩니다. Teleport Auth Service를 실행할 EC2 인스턴스에 이 보안 그룹을 연결하여 Auth Service와 HSM 간의 트래픽을 허용합니다.

11. Auth Service EC2 인스턴스에서 CloudHSM Client SDK 5용 CloudHSM CLI를 설치합니다. https://docs.aws.amazon.com/cloudhsm/latest/userguide/gs_cloudhsm_cli-install.html

    새 HSM의 IP 주소를 구성하여 CLI를 부트스트랩합니다:

    $ sudo /opt/cloudhsm/bin/configure-cli -a 
    

12. 6단계의 자체 서명 인증서(customerCA.crt)를 EC2 인스턴스에 복사하고 /opt/cloudhsm/etc/customerCA.crt에 저장합니다.

13. 새 비밀번호로 관리자 사용자를 생성하여 CloudHSM CLI로 CloudHSM 클러스터를 활성화합니다:

    $ sudo /opt/cloudhsm/bin/cloudhsm-cli interactive
    aws-cloudhsm > cluster activate
    Enter password:
    Confirm password:
    {
      "error_code": 0,
      "data": "Cluster activation successful"
    }
    

14. 새 관리자 사용자로 CloudHSM CLI에 로그인하고 Teleport에서 사용할 Crypto User를 생성합니다. 나중에 Teleport가 PKCS#11 라이브러리에 인증하는 데 사용하므로 이 새 비밀번호를 기억하세요.

    aws-cloudhsm > login --username admin --role admin
    Enter password:
    {
      "error_code": 0,
      "data": {
        "username": "admin",
        "role": "admin"
      }
    }
    aws-cloudhsm > user create --username teleport --role crypto-user
    Enter password:
    Confirm password:
    {
      "error_code": 0,
      "data": {
        "username": "teleport",
        "role": "crypto-user"
      }
    }
    aws-cloudhsm > quit
    

15. 동일한 Auth Service EC2 인스턴스에 Client SDK 5용 PKCS#11 라이브러리를 설치합니다. https://docs.aws.amazon.com/cloudhsm/latest/userguide/pkcs11-library-install.html

    HSM IP 주소를 구성하여 PKCS#11 라이브러리를 부트스트랩합니다. 클러스터에 HSM이 하나만 있는 경우 --disable-key-availability-check 플래그를 포함해야 합니다.

    $ sudo /opt/cloudhsm/bin/configure-pkcs11 --disable-key-availability-check -a 
    

YubiHSM2:

1. YubiHSM2 SDK를 설치합니다.

2. 디버그 로깅이 활성화된 상태로 yubihsm-connector를 시작합니다. 이것은 YubiHSM2에 대한 연결을 용이하게 하기 위해 계속 실행해야 하는 백그라운드 프로세스입니다.

   $ yubihsm-connector -d
   DEBU[0000] preflight complete                            cert= config= key= pid=73502 seccomp=false serial= syslog=false timeout=0s version=3.0.3
   DEBU[0000] takeoff                                       TLS=false listen="localhost:12345" pid=73502
   

3. yubihsm-shell을 사용하여 필요한 기능을 갖춘 Teleport에서 사용할 새 인증 키를 생성합니다.

   YubiHSM2는 비밀번호 password를 가진 슬롯 1에 공장 기본 인증 키와 함께 제공됩니다. 가능한 한 빨리 이를 교체하거나 비밀번호를 변경하는 것을 권장합니다.

   Teleport에서 사용할 인증 키를 생성할 때 비밀번호는 최소 8자여야 합니다.

   $ yubihsm-shell
   Using default connector URL: http://localhost:12345
   yubihsm> connect
   Session keepalive set up to run every 15 seconds
   yubihsm> session open 1
   Enter password:
   Created session 0
   
   # Create an Authentication Key for Teleport
   yubihsm> put authkey 0 0 "Teleport Auth Key" 1 generate-asymmetric-key:sign-pkcs:sign-pss:sign-ecdsa:delete-asymmetric-key:decrypt-oaep sign-pkcs:sign-pss:decrypt-pkcs:decrypt-oaep:sign-ecdsa
   Enter password:
   Stored Authentication key 0x85cf
   
   # Make sure you can open a session with the new authentication key and password
   yubihsm> session open 0x85cf
   Enter password:
   Created session 1
   
   # Change the password for the factory default authentication key.
   # Remember to securely store this password somewhere.
   yubihsm> change authkey 0 1 authentication-key
   Enter password:
   

   새 인증 키의 슬롯 번호를 기록해 두세요. 위 예시에서는 16진수 값 0x85cf입니다. 나중에 Teleport 구성 파일에 포함해야 합니다.

4. yubihsm-connector가 수신 대기하는 주소와 포트를 구성하고 디버그 로깅을 활성화하는 yubihsm_pkcs11.conf 파일을 생성합니다:

   # /etc/yubihsm_pkcs11.conf
   connector = https://127.0.0.1:12345
   debug
   

5. 환경 변수 YUBIHSM_PKCS11_CONF를 구성 파일의 경로로 설정합니다. 이것은 PKCS#11 모듈에서 읽히며 Teleport Auth Service 환경에서 설정해야 합니다.

   $ export YUBIHSM_PKCS11_CONF=/etc/yubihsm_pkcs11.conf
   

2단계/5. Teleport 구성#

모든 CA 개인 키 생성, 저장 및 서명에 HSM을 사용하도록 Teleport를 구성하려면 Auth Service의 /etc/teleport.yaml에 ca_key_params 섹션을 포함합니다.

AWS CloudHSM:

# /etc/teleport.yaml
teleport:
  ...

auth_service:
  enabled: true
  ...

  ca_key_params:
    pkcs11:
      # this is the default install location of the PKCS#11 module for the
      # CloudHSM Client SDK 5
      module_path: /opt/cloudhsm/lib/libcloudhsm_pkcs11.so

      # token_label should always be "hsm1" for the CloudHSM SDK 5
      # if you prefer to use SDK version 3, replace this with "cavium"
      token_label: "hsm1"

      # pin should be set to the username and password of the Crypto User
      # created earlier in the guide
      pin: ":"
      # pin_path can optionally be used to read the pin from a file
      # pin_path: /path/to/pin_file

      # max_sessions configures the maximum number of open sessions for the HSM.
      # If not set, it will default to the minimum of 1024 or the MaxRWSessionCount
      # reported by the PKCS#11 module for the token. If set, must be greater than 1.
      max_sessions: 10

YubiHSM2:

# /etc/teleport.yaml
teleport:
  ...

auth_service:
  enabled: true
  ...

  ca_key_params:
    pkcs11:
      # this is the default installation path for Yubico's PKCS#11 module
      module_path: /usr/local/lib/pkcs11/yubihsm_pkcs11.dylib
      # slot_number should always be set to 0 for YubiHSM2
      slot_number: 0
      # pin should be the (hex) slot number of your authentication key,
      # concatenated with your chosen password
      pin: "85cfpassword"
      # pin_path can optionally be used to read the pin from a file
      # pin_path: /path/to/pin_file

      # Optionally specify the maximum number of open sessions for the HSM.
      # If not set, it will default to 1024. If set, must be greater than 1.
      max_sessions: 10

3단계/5. Teleport Auth 재시작#

아직 시작하지 않은 새 Teleport Auth Service이고 빈 백엔드로 완전히 새로운 클러스터를 시작하는 경우 HSM 키가 시작 시 자동으로 생성되며 추가 작업이 필요하지 않습니다. 5단계로 건너뛰세요. 그렇지 않으면 계속 읽으세요.

기존 Teleport 클러스터에 HSM을 연결하는 경우 구성 변경 사항이 적용되도록 Auth 서버를 재시작합니다. 다음 CA 로테이션 중에 HSM에서 새 CA 키가 자동으로 생성됩니다. CA 로테이션이 완료될 때까지 Auth Service는 기존 소프트웨어 키로 새 인증서에 서명합니다.

4단계/5. HSM으로 인증서 로테이션#

기존 Teleport 클러스터에 새 HSM을 추가하거나 HA Teleport 클러스터에 새 HSM 연결 Auth Service를 추가할 때 새 인증서가 발급되고 신뢰받으려면 모든 인증 기관을 로테이션해야 합니다.

teleport start는 CA 로테이션이 필요한 경우 시작 시 경고를 출력합니다. Teleport 역할에서 cert_authority 리소스에 대해 update 동사가 허용된 사용자는 CA를 로테이션하도록 상기시키는 클러스터 알림도 볼 수 있습니다.

CA 로테이션은 수동 또는 반자동으로 수행할 수 있습니다. 인증서 로테이션에 관한 관리자 가이드를 참조하세요. tctl status 출력에 나열된 모든 CA를 로테이션해야 합니다.

5단계/5. Teleport가 HSM을 사용하는지 확인#

설정 완료! HSM 키가 사용되고 있는지 몇 가지 방법으로 확인할 수 있습니다:

1. tctl status는 모든 인증 기관 키에 대해 storage 방법으로 PKCS#11 HSM을 표시합니다.
2. Teleport Auth 서비스 로그에 Creating new HSM key pair가 포함됩니다.
3. HSM의 관리 도구에 새로 생성된 키가 표시됩니다.