PKCS #11 API로 암호화 오퍼레이션 수행

IBM Cloud® Hyper Protect Crypto Services는 암호화 오퍼레이션을 위한 Hyper Protect Crypto Services 클라우드 HSM에 액세스할 수 있도록 표준 PKCS #11 API를 제공합니다.

전제조건

PKCS #11 API를 설정하고 사용하기 전에 PKCS #11 사용자 유형 설정에 대한 우수 사례에 따라 다양한 PKCS #11 사용자 유형에 대해 서로 다른 서비스 ID API 키를 작성하십시오.

1단계: PKCS #11 라이브러리 설정

애플리케이션이 표준 PKCS #11 기능을 사용할 수 있도록 하려면 워크스테이션에서 PKCS #11 라이브러리를 설정해야 합니다.

PKCS #11 라이브러리는 amd64 및 s390x 플랫폼 모두에 대해 Linux에서만 지원됩니다.

IBM Z (s390x) 플랫폼에서 SunPKCS11 제공자를 사용하여 Java PKCS #11 애플리케이션을 실행 중인 경우, 애플리케이션을 시작할 때 최신 IBM Semeru JVM을 사용하고 -Xjit:noResumableTrapHandler Java 옵션을 지정해야 합니다. IBM Semeru 런타임 다운로드 페이지에서 아키텍처 필터 필드를 s390x 로 변경하여 IBM Semeru JVM의 최신 s390x 버전을 다운로드할 수 있습니다.

최신 PKCS #11 라이브러리를 다운로드하십시오. 라이브러리 파일 이름은 pkcs11-grep11-<platform>.so.<version> 의 이름 지정 규칙을 사용합니다. 플랫폼은 amd64 또는 s390x이고 버전은 표준 major.minor.build 구문입니다.
애플리케이션에서 액세스할 수 있는 폴더로 라이브러리를 이동하십시오. 예를 들어 Linux에서 애플리케이션을 실행하는 경우 라이브러리를 /usr/local/lib, /usr/local/lib64 또는 /usr/lib로 이동할 수 있습니다.

2단계: (선택사항) PKCS #11 라이브러리의 무결성 및 인증 확인

강력한 보안을 위해 PKCS #11 애플리케이션을 실행하여 라이브러리를 사용하기 전에 PKCS #11 라이브러리의 무결성 및 인증을 확인하십시오.

Hyper Protect Crypto Services 는 서명된 코드 검증 을 사용하여 서명이 원래 코드와 일치하는지 확인합니다. 다운로드된 PKCS #11 라이브러리 파일이 변경되거나 손상된 경우 다른 서명이 생성되고 검증에 실패합니다. 다운로드 프로세스 중에 파일이 변경되거나 손상되지 않도록 하려면 OpenSSL 명령행 도구를 사용하여 다음 단계를 완료하십시오.

라이브러리 저장소 에서 PKCS #11 라이브러리를 저장하는 동일한 디렉토리로 다음 파일의 최신 버전을 다운로드하십시오.
- pkcs11-grep11-<platform>.so.<version>.sig: PKCS #11 라이브러리의 서명된 암호화 해시입니다. 여기서 플랫폼은 amd64 또는 s390x이며 버전은 서명 파일의 major.minor.build입니다. 플랫폼 및 버전은 각각 사용하는 PKCS #11 라이브러리의 플랫폼 및 버전과 일치해야 합니다.
- signing_cert.pem: Hyper Protect Crypto Services PKCS #11 클라이언트 파일의 서명 인증서입니다.
- digicert_cert.pem: Hyper Protect Crypto Services PKCS #11 클라이언트 파일의 서명 인증서를 증명하는 중간 코드 서명 인증서입니다.
다음 명령을 사용하여 서명 인증서 signing_cert.pem에서 sigkey.pub 파일로 공개 키를 추출하십시오.
```
openssl x509 -pubkey -noout -in signing_cert.pem -out sigkey.pub
```
다음 명령을 사용하여 PKCS #11 라이브러리 파일의 무결성을 확인하십시오.
```
openssl dgst -sha256 -verify sigkey.pub -signature pkcs11-grep11-<platform>.so.<version>.sig pkcs11-grep11-<platform>.so.<version>
```
플랫폼을 amd64 또는 s390x로 대체하거나 version을 라이브러리의 major.minor.build로 대체하십시오.

확인하면 Verified OK가 표시됩니다.
다음 명령으로 서명 인증서의 인증 및 무결성을 확인하십시오.
```
openssl ocsp -no_nonce -issuer digicert_cert.pem -cert signing_cert.pem -VAfile digicert_cert.pem -text -url http://ocsp.digicert.com -respout ocsptest
```
확인하면 출력에 Response verify OK 및 signing_cert.pem: good이 표시됩니다.
확인에 실패하면 설치를 취소하고 IBM에 지원을 문의하십시오.

3단계: PKCS #11 구성 파일 설정

암호화 기능을 수행하기 위해 PKCS #11 라이브러리를 Hyper Protect Crypto Services 클라우드 HSM에 연결하려면 다음 단계를 완료하여 구성 파일을 설정하십시오.

다음 예제에 따라 grep11client.yaml로 이름 지정된 구성 파일을 작성하십시오. 라이브러리 저장소 는 사용자가 적응할 수 있는 템플리트도 제공합니다. 코드의 주석을 참조하면 각 필드를 이해할 수 있습니다.

iamcredentialtemplate: &defaultiamcredential
  enabled: true
  endpoint: "https://iam.cloud.ibm.com"

sessionauthtemplate: &defaultsessionauth
  enabled: false
  tokenspaceIDPassword:  # Authenticated keystore password 6-8 characters in length

tokens:
  0:
    grep11connection:
      # The EP11 endpoint address starting from 'ep11'. For example: "<instance_ID>.ep11.us-south.hs-crypto.appdomain.cloud"
      address: "<EP11_endpoint_URL>"
      port: "<EP11_endpoint_port_number>" # The EP11 endpoint port number
      tls:
        enabled: true # EP11 requires TLS connection.
        # Set it 'true' if you want to enable mutual TLS connections.
        # By default, set it 'false' because EP11 requires server-only authentication.
        mutual: <enable_mtls>
        # 'cacert' is a full-path certificate file. In Linux with the 'ca-ca-certificates' package installed, this is normally not needed.
        cacert:
        # Specify the file path of the client certificate if you enable mutual TLS. Otherwise, keep it empty.
        certfile: <client_certificate>
        # Specify the file path of the client certificate private key if you enable mutual TLS. Otherwise, keep it empty.
        keyfile: <client_certificate_private_key>
    storage:
        # 'remotestore' needs to be enabled if you want to generate keys with the attribute CKA_TOKEN.
      remotestore:
        enabled: true
    users:
      0: # The index of the Security Officer (SO) user MUST be 0.
        # The name for the Security Officer (SO) user. For example: "Administrator".
        name: "<SO_user_name>"
        iamauth: *defaultiamcredential
      1: # The index of the normal user MUST be 1.
        # The name for the normal user. For example: "Normal user".
        name: "<normal_user_name>"
        # The 128-bit UUID of the private keystore. For example: "f00db2f1-4421-4032-a505-465bedfa845b".
        tokenspaceID: "<private_keystore_spaceid>"
        iamauth: *defaultiamcredential
        # Do not override the defaultsessionauth template
        # The same values must be used for both the private (normal user) and public (anonymous) keystores
        sessionauth: *defaultsessionauth
      2: # The index of the anonymous user MUST be 2.
        # The name for the anonymous user. For example: "Anonymous".
        name: "<anonymous_user_name>"
        # The 128-bit UUID of the public keystore. For example: "ca22be26-b798-4fdf-8c83-3e3a492dc215".
        tokenspaceID: "<public_keystore_spaceid>"
        iamauth:
          <<: *defaultiamcredential
          # The API key for the anonymous user. All other users can specify API key using the C_Login command.
          apikey: "<apikey_for_anonymous_user>"
        # Do not override the defaultsessionauth template
        # The same values must be used for both the private (normal user) and public (anonymous) keystores
        sessionauth: *defaultsessionauth

logging:
  # Set the logging level.
  # The supported levels, in an increasing order of verboseness: 'panic', 'fatal', 'error', 'warning'/'warn', 'info', 'debug', 'trace'. The Default value is 'warning'.
  loglevel: "<logging_level>"
  logpath: "<log_file_path>" # The full path of your logging file.

인증된 키 저장소가 사용되는 경우, sessionauth 구성 옵션은 키 저장소 둘 다에 대해 사용으로 설정되어야 하며 길이가 6-8자인 텍스트 비밀번호는 tokenspaceIDPassword 필드의 두 키 저장소 모두에 대해 동일해야 합니다.

다음 표에 따라 예제 변수를 대체하십시오.

특정 지역에서 2024년 4월 12일 이후에 인스턴스를 작성하는 경우 새 형식이 <instance_ID>.ep11.<REGION>.hs-crypto.appdomain.cloud 인 새 API 엔드포인트를 사용해야 할 수 있습니다. 가능한 날짜는 지역에 따라 다릅니다. 지원되는 지역, 가용성 날짜 및 새 엔드포인트 URL에 대한 자세한 정보는 새 엔드포인트 를 참조하십시오.

표 1. PKCS #11 구성 파일을 작성하는 데 필요한 변수를 설명합니다.
가변	설명
`EP11_endpoint_URL`	Hyper Protect Crypto Services Enterprise PKCS #11(EP11) API 엔드포인트입니다. UI에서 개요 > 연결 > EP11 엔드포인트 URL 을 통해 가져오거나 API를 사용하여 동적으로 엔드포인트 URL을 검색 할 수 있습니다. 공용 또는 사설 네트워크 사용 여부에 따라 공용 또는 사설 EP11 엔드포인트 URL을 사용하십시오.
`EP11_endpoint_port_number`	EP11 API 엔드포인트의 포트 번호입니다. 엔드포인트 URL의 콜론 뒤에 위치합니다.
`enable_mtls`	올바른 값은 상호 TLS를 사용하여 Hyper Protect Crypto Services 표준 플랜의 PKCS #11 API 액세스에 대한 두 번째 인증 계층을 추가할지 여부를 표시하는 `true` 또는 `false` 입니다. 기본적으로 EP11에는 서버 전용 인증이 필요하므로 `false`로 설정하십시오. 상호 TLS 연결에 대한 자세한 정보는 EP11 연결을 위해 두 번째 인증 계층 사용을 참조하십시오.
`client_certificate`	상호 TLS 연결을 사용으로 설정하는 경우 인증서 관리자가 인스턴스에 업로드하는 클라이언트 인증서의 파일 경로를 지정하십시오. 그렇지 않을 경우 이 필드를 비워 두십시오.
`client_certificate_private_key`	상호 TLS 연결을 사용으로 설정하는 경우 인증서에 서명하기 위해 사용되는 클라이언트 인증서 개인 키의 파일 경로를 지정하십시오. 그렇지 않을 경우 이 필드를 비워 두십시오.
`SO_user_name`	보안 담당자(SO) 사용자 유형의 이름입니다. PKCS #11 표준은 로그인의 두 가지 유형인 보안 담당자(SO)와 일반 사용자를 정의합니다. PKCS #11 사용자 유형에 대한 자세한 정보는 PKCS #11 암호화 토큰 인터페이스 사용 안내서 버전 2.40 - 사용자를 참조하십시오.
`normal_user_name`	일반 사용자 유형의 이름입니다. PKCS #11 표준은 로그인의 두 가지 유형인 보안 담당자(SO)와 일반 사용자를 정의합니다. PKCS #11 사용자 유형에 대한 자세한 정보는 PKCS #11 암호화 토큰 인터페이스 사용 안내서 버전 2.40 - 사용자를 참조하십시오.
`private_keystore_spaceid`	개인용 키 저장소의 128비트 UUID(Universally Unique IDentifier)입니다. UUID 생성기 와 같은 써드파티 도구를 사용하여 UUID를 생성할 수 있습니다. Hyper Protect Crypto Services 는 향상된 보안 및 향상된 사용자 액세스 관리를 위해 두 개의 데이터베이스 지원 EP11 키 저장소를 제공합니다. 일반 사용자 유형만 액세스할 수 있는 개인용 키 저장소와 모든 사용자 유형이 액세스할 수 있는 공용 키 저장소입니다. UUID는 `public_keystore_spaceid` 매개변수에 지정된 UUID와 달라야 합니다.
`private_keystore_password`	`sessionauth` 구성 옵션을 사용으로 설정하여 권한 부여된 세션을 사용할 수 있습니다. `sessionauth` 옵션이 사용으로 설정된 경우 두 키 저장소 모두에 대해 사용으로 설정되어야 합니다. 또한 길이가 6-8자인 텍스트 비밀번호가 `tokenspaceIDPassword` 필드에 필요하며 비밀번호는 두 키 저장소 모두에 대해 동일해야 합니다. 권한 부여된 세션은 HSM에 특정하고 PKCS #11 플로우에서 로그인 및 로그아웃하기 위해 사용되며 인증된 키 조작을 위해 필요합니다. 권한 부여된 세션을 사용하여 생성된 모든 키는 인증되고 암호화된 키 저장소에 저장됩니다. `tokenspaceIDPassword` 필드는 인증되고 암호화된 키 저장소에서 키를 보호하기 위해 사용됩니다. 서비스 인스턴스별로 최대 다섯 개의 인증된 키 저장소가 지원됩니다.
`anonymous_user_name`	익명 사용자의 이름입니다. PKCS #11 표준은 로그인의 두 가지 유형인 보안 담당자(SO)와 일반 사용자를 정의합니다. 사용자가 `C_Login` Cryptoki 함수를 사용하여 로그인하지 않을 경우 해당 사용자는 익명 사용자로 간주됩니다. PKCS #11 사용자 유형에 대한 자세한 정보는 PKCS #11 암호화 토큰 인터페이스 사용 안내서 버전 2.40 - 사용자를 참조하십시오.
`public_keystore_spaceid`	공용 키 저장소의 128비트 UUID(Universally Unique IDentifier)입니다. UUID 생성기 와 같은 써드파티 도구를 사용하여 UUID를 생성할 수 있습니다. Hyper Protect Crypto Services 는 향상된 보안 및 향상된 사용자 액세스 관리를 위해 두 개의 데이터베이스 지원 EP11 키 저장소를 제공합니다. 일반 사용자 유형만 액세스할 수 있는 개인용 키 저장소와 모든 사용자 유형이 액세스할 수 있는 공용 키 저장소입니다. UUID는 `private_keystore_spaceid` 매개변수에 지정된 UUID와 달라야 합니다. 중요: UUID 문자열 값은 익명 사용자에 대한 액세스 정책을 설정하는 데 사용되는 UUID 문자열과 일치해야 합니다. 익명 사용자 액세스 정책 작성 을 참조하십시오.
`apikey_for_anonymous_user`	이전 전제조건 단계에서 익명 사용자 유형을 위해 작성하는 서비스 ID API 키입니다.
`logging_level`	지원되는 로깅 레벨은 글자 수가 증가하는 순서에 따라 `panic`, `fatal`, `error`, `warning`/`warn`, `info`, `debug` 및 `trace`입니다. 기본값은 `warning`입니다.
`log_file_path`	로깅 파일의 전체 경로입니다. 여기에서는 애플리케이션이 PKCS #11 함수를 실행하도록 Hyper Protect Crypto Services 클라우드 HSM과 상호작용할 때 생성되는 모든 로그가 저장됩니다.

PKCS #11에서 사용되는 키 저장소를 암호화하고 인증하려면 sessionauth 매개변수를 사용으로 설정하고 키 저장소의 비밀번호를 구성하십시오. 서비스 인스턴스별로 최대 다섯 개의 인증된 키 저장소가 지원됩니다. 비밀번호는 6-8자가 될 수 있습니다. 키 저장소 비밀번호는 서비스 인스턴스에 저장되지 않습니다. 키 저장소 관리자는 비밀번호의 로컬 사본을 유지보수할 책임이 있습니다. 비밀번호가 유실되는 경우 IBM 지원 센터에 문의하여 키 저장소를 재설정해야 합니다. 이 경우 키 저장소의 모든 데이터가 지워집니다.

구성 파일을 /etc/ep11client 디렉토리로 이동하십시오. /etc/ep11client 디렉토리가 존재하지 않을 경우 작성하십시오. 또는 환경 변수 EP11CLIENT_CFG 를 구성 파일의 전체 경로 및 파일 이름으로 설정할 수 있습니다. 이를 수행하면 yaml 파일의 grep11client 이름으로 제한되지 않습니다. 예: export EP11CLIENT_CFG=/home/user/pkcs11-config.yaml

4단계: PKCS #11 API를 호출하기 위해 PKCS #11 라이브러리 사용

라이브러리 및 구성 파일을 설정한 후 키 저장소를 초기화해야 합니다. 키 저장소를 초기화하려면 보안 담당자(SO)인 사용자는 C_InitToken 오퍼레이션을 수행해야 합니다.

키 저장소가 초기화되면 PKCS #11 라이브러리를 사용하여 키를 생성, 저장 및 나열하는 표준 PKCS #11 함수를 호출하십시오. 지원되는 PKCS #11 함수의 세부 목록은 지원되는 PKCS #11 참조를 참조하십시오.

애플리케이션의 기능 및 보안 요구사항에 따라 애플리케이션에서 해당 조작을 수행할 수 있도록 이전 전제조건 단계에서 작성된 다른 서비스 ID API 키를 전달하십시오. 예를 들어 애플리케이션에서 키 저장소를 삭제해야 하는 경우 SO 사용자 API 키를 제공하십시오. 애플리케이션에서 새 키를 저장할 개인 키 저장소에 액세스해야 하는 경우 일반 사용자 API 키를 제공해야 합니다. PKCS #11 API에 대한 사용자 액세스 관리에 대한 자세한 정보는 PKCS #11 사용자 유형 설정에 대한 우수 사례를 참조하십시오.

다음에 수행할 작업

KCS #11 라이브러리 사용법을 더욱 잘 이해하려면 Oracle Database Transparent Database Encryption을 위한 Hyper Protect Crypto Services PKCS #11 라이브러리를 사용하는 방법을 보여주는 튜토리얼을 확인하십시오.
암호화 기능에 대한 자세한 정보는 PKCS #11 API 참조를 확인하십시오.