KMFCryptoOperation - 범위가 지정됨, 전역

  • 릴리스 버전: Yokohama
  • 업데이트 날짜 2025년 01월 30일
  • 읽기19분

    • KMFCryptoOperation 클래스는 ()KMF 암호화 모듈 또는 필드 암호화 암호화 모듈을 사용하여 핵심 관리 프레임워크 암호화 작업을 수행하기 위한 메서드를 제공합니다.

    이 API를 사용하려면 KMF 암호화 모듈 또는 CLE 암호화 모듈을 이미 작성하고 구성해야 합니다. 모듈에는 하나 이상의 암호화 스펙이 있어야 하며 연관된 키를 작성하거나 가져와야 합니다. 자세한 내용은 암호화 모듈을 참조하세요.

    이 API를 사용하여 생성된 KMFCryptoOperation 개체는 대칭 암호화와 같은 암호화 작업을 나타냅니다. KMFCryptoOperations() 메서드를 사용하여 이 개체를 만들고, 빌더 메서드를 사용하여 개체의 속성을 설정하고, doOperation() 메서드를 사용하여 작업을 실행합니다.

    이 API는 범위가 지정된 애플리케이션과 전역 애플리케이션 모두에서 사용할 수 있습니다. 이 API를 호출할 때는 항상 sn_kmf_ns 네임스페이스를 지정해야 합니다.

    KMFCryptoOperation - KMFCryptoOperation(String cryptoModuleName, String operationName)

    지정된 모듈 및 작업에 대해 KMFCryptoOperation 개체를 만듭니다.

    이 API는 작성기 메서드를 활용합니다. 작성기 메서드는 데이터의 원하는 출력 형식 변경과 같이 KMFCryptoOperation 개체의 속성을 업데이트합니다. 모든 작성기 메서드가 모든 작업에 유효한 것은 아닙니다. 각 작업에 사용할 수 있는 작성기 메서드는 아래 매개변수 테이블에 나와 있습니다.

    다음 작성기 메서드는 모든 운영 유형에 유효합니다.
    표 1. 매개변수
    이름 유형 설명
    cryptoModuleName 문자열 사용할 키 관리 프레임워크(KMF) 암호화 모듈 또는 필드 암호화 암호화 모듈의 이름입니다. 이 메서드를 호출하기 전에 모듈을 만들어야 합니다. 자세한 내용은 암호화 모듈 개요를 참조하세요.
    작업 이름 문자열 수행할 작업의 이름입니다.
    유효한 값(대/소문자 구분 안 함):
    • ASYMMETRIC_DECRYPTION: 비대칭 키 알고리즘을 사용한 데이터 암호 해독. 비대칭 데이터 암호 해독 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: withAdditionalInput()
      • 기본 입력 형식: 형식화 - KMF 사양에 맞게 형식이 지정됨
      • 기본 출력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 유형: 문자열
    • ASYMMETRIC_ENCRYPTION: 비대칭 키 알고리즘을 사용한 데이터 암호화. 비대칭 데이터 암호화 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: withAdditionalInput()
      • 기본 입력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 형식: 포맷됨 - KMF 사양에 맞게 포맷됨
      • 기본 출력 유형: 문자열 . 출력은 KMFEncryptionPayload 개체일 수도 있습니다. RSA와 EC-IES는 둘 다와 호환됩니다. KMFEncryptionPayload 개체에 대한 자세한 내용은 withAdditionalInput()을 참조하세요.
    • ASYMMETRIC_UNWRAPPING: 비대칭 키 알고리즘을 사용하여 키 래핑 해제. 비대칭 키 래핑 해제 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: withAlgorithm()
      • 기본 입력 형식: 형식화 - KMF 사양에 맞게 형식이 지정됨
      • 기본 출력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 유형: 문자열
    • ASYMMETRIC_WRAPPING: 비대칭 키 알고리즘을 사용한 키 래핑. 비대칭 키 래핑 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: withAlgorithm(),withSysId()
      • 기본 입력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 형식: 포맷됨 - KMF 사양에 맞게 포맷됨
      • 기본 출력 유형: 문자열
    • MAC_GENERATION: MAC(메시지 인증 코드) 생성 대칭 키 알고리즘 기반으로 데이터 무결성 및 인증을 제공합니다. 대칭 정품 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: 없음
      • 기본 입력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 형식: 포맷됨 - KMF 사양에 맞게 포맷됨
      • 기본 출력 유형: 문자열
    • MAC_VERIFICATION: MAC 확인. 데이터 무결성 및 인증을 제공하기 위한 대칭 키 알고리즘 기반입니다. 대칭 정품 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: withAdditionalInput()
      • 기본 입력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 형식: KMFNone - 디코딩 없음
      • 기본 출력 유형: 부울
    • SIGNATURE_GENERATION: 디지털 서명 생성 데이터 무결성 및 인증을 제공하기 위한 비대칭 키 알고리즘 기반입니다. 서명 생성 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: 없음
      • 기본 입력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 형식: 포맷됨 - KMF 사양에 맞게 포맷됨
      • 기본 출력 유형: 문자열
    • SIGNATURE_VERIFICATION: 디지털 서명 확인. 데이터 무결성 및 인증을 제공하기 위한 비대칭 키 알고리즘 기반입니다. 서명 검증 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: withAdditionalInput()
      • 기본 입력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 형식: KMFNone - 디코딩 없음
      • 기본 출력 유형: 부울
    • SYMMETRIC_ENCRYPTION: 대칭 키 알고리즘을 사용한 데이터 암호화. 알고리즘이 같음 유지가 아닌 경우 형식이 지정된 출력만 허용됩니다. 대칭 데이터 암호화/암호 해독 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: 없음
      • 기본 입력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 형식: 포맷됨 - KMF 사양에 맞게 포맷됨
      • 기본 출력 유형: 문자열
    • SYMMETRIC_DECRYPTION: 대칭 키 알고리즘을 사용한 데이터 암호 해독. 알고리즘이 같음을 유지하지 않으면 KMFBase64 입력이 허용됩니다. 대칭 데이터 암호화/암호 해독 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: 없음
      • 기본 입력 형식: 형식화 - KMF 사양에 맞게 형식이 지정됨
      • 기본 출력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 유형: 문자열
    • SYMMETRIC_WRAPPING: 대칭 키 알고리즘을 사용한 키 래핑. 알고리즘이 같음 유지가 아닌 경우 형식이 지정된 출력만 허용됩니다. 대칭 키 래핑/래핑 해제 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: withAlgorithm() 및 withSysId()
      • 기본 입력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 형식: 포맷됨 - KMF 사양에 맞게 포맷됨
      • 기본 출력 유형: 문자열
    • SYMMETRIC_UNWRAPPING: 대칭 키 알고리즘을 사용하여 키 래핑 해제. 알고리즘이 같음을 유지하지 않으면 KMFBase64 입력이 허용됩니다. 대칭 키 래핑/래핑 해제 암호화 목적을 가진 KMF 암호화 모듈이 필요합니다.
      • 추가 빌더 메서드: withAlgorithm()
      • 기본 입력 형식: 형식화 - KMF 사양에 맞게 형식이 지정됨
      • 기본 출력 형식: KMFBase64 - Base64 인코딩
      • 기본 출력 유형: 문자열

    이 예제에서는 대칭 암호화 작업을 수행하기 위해 모듈 global.sj_cm에 대한 KMFCryptoOperation 개체를 인스턴스화합니다. 전역 및 범위가 지정된 애플리케이션 모두에 대한 네임스페이스를 포함해야 합니다.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION");

    이 예제에서는 디폴트 출력 형식과 출력 형식을 업데이트하는 옵션을 지정하는 방법을 보여줍니다.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION")
  .withOutputType("STRING").withOutputFormat("FORMATTED");

var cipherText=op.doOperation("hi");

    이 예에서는 통합 암호화 체계(EC-IES)를 사용하여 비대칭 암호화 작업을 수행하는 방법을 보여줍니다. 와 같은 signature긴 값은 가독성을 위해 잘리고 타원으로 대체되었습니다.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_ENCRYPTION")
.withInputFormat("KMFNONE")
.withOutputType("PAYLOAD");

var cipherText = op.doOperation("hi");

/*
cipherText contains an object similar to this JSON: {
  "signature": "pkg…",
  "ephemeral_key": "BDi…",
  "ciphertext": "afFS…"
}
*/

    이 예제에서는 EC-IES를 사용하여 비대칭 암호 해독 작업을 수행하는 방법을 보여 줍니다.

    var op = new 
sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_DECRYPTION")
  .withAdditionalInput({
  "signature": "pkg… ",
  "ephemeral_key": "BDi…"
})
.withOutputFormat("KMFNONE");

var clearText = op.doOperation("afFS…");

    KMFCryptoOperation - doOperation(객체 데이터)

    제공된 데이터에 대해 현재 KMFCryptoOperation 개체로 정의된 암호화 작업을 수행하고 결과를 반환합니다.

    표 2. 매개변수
    이름 유형 설명
    데이터 객체 withSysId() 빌더 메서드가 연결된 KMFCryptoOperation 객체에서 이전에 호출된 경우를 제외하고는 필수입니다. 암호화 작업을 수행할 입력 데이터입니다.
    표 3. 반환
    유형 설명
    운영 유형에 따라 다릅니다.
    • MAC_VERIFICATION 및 SIGNATURE_VERIFICATION: 부울
    • 기타: 문자열
    		 연결된 KMFCryptoOperation 개체에 지정된 작업을 수행한 후의 데이터 결과입니다.

    이 예제에서는 doOperation() 을 사용하여 MAC을 만듭니다.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","MAC_GENERATION"); 
var data = "aGk="; 
var mac = op.doOperation(data);

    KMFCryptoOperation - withAdditionalInput(객체 additionalInput)

    암호화 작업을 수행하는 데 필요한 추가 입력을 설정합니다.

    예를 들어 MAC(메시지 인증 코드) 확인 중에 이 메서드를 사용하여 생성된 MAC 태그를 전달합니다. 마찬가지로 서명 확인 중에 이를 사용하여 서명을 전달합니다. EC-IES(Elliptic Curve Integrated Encryption Scheme)와 같은 통합 암호로 비대칭 작업을 수행할 때 이 메서드를 사용하여 추가 데이터인 KMFEncryptionPayload 개체를 전달할 수도 있습니다.

    주:
    추가 입력은 현재 KMFCryptoOperation 개체에 설정된 형식과 같을 필요가 없습니다.
    표 4. 매개변수
    이름 유형 설명
    additionalInput 문자열 또는 객체 선택 사항입니다(EC-IES 사용 시 비대칭 암호 해독 작업 제외). KMFCryptoOperation 개체에 지정된 암호화 작업을 수행하는 데 필요한 추가 입력 데이터입니다.
    지원되는 문자열 형식:
    • FORMATTED: 키 관리 프레임워크(KMF) 사양에 따라 형식이 지정됩니다.
    • KMFBASE64: Base64 인코딩.

    KMFEncryptionPayload 개체 형식:

    {
  "ciphertext": String,
  "derivation_secret": String,
  "ephemeral_key": String,
  "ephemeral_key_format": String,
  "signature": String
}
    additionalInput.ciphertext 문자열(Base64) 비대칭 암호 해독에 필요하며 다른 모든 작업에는 선택 사항입니다.
    유효한 값은 다음과 같습니다.
    • RSA 알고리즘을 사용하는 경우: RSA 암호 텍스트
    • EC-IES 알고리즘을 사용하는 경우: 통합 AES 암호 텍스트

    출력 유형이 로 설정된 payload경우 비대칭 암호화 작업에서 사용할 수 있습니다.
    additionalInput.derivation_secret 문자열(Base64) 선택 사항으로, EC-IES를 사용한 비대칭 암호화 또는 비대칭 암호 해독 작업에만 사용됩니다. 통합 체계의 키 파생 프로세스 중에 사용할 공유 암호입니다.
    additionalInput.ephemeral_key 문자열(Base64) EC-IES를 사용할 때 비대칭 암호 해독 작업에 필요하며, 다른 모든 작업에 대해서는 선택 사항입니다. 통합 체계의 기본 합의 프로세스 중에 사용할 임시 공개 키입니다.

    출력 유형이 로 설정된 payload경우 비대칭 암호화 작업에서 사용할 수 있습니다.
    additionalInput.ephemeral_key_format 문자열 선택 사항으로, EC-IES를 사용한 비대칭 암호화 또는 비대칭 암호 해독 작업에만 사용됩니다. 매개변수로 표현되는 공개 키의 형식을 재정의합니다 ephemeral_key .
    유효한 값은 다음과 같습니다.
    • x962
    • 데르
    additionalInput.signature 문자열(Base64) EC-IES를 사용한 비대칭 암호 해독 작업에 필요하며, 다른 모든 작업에는 선택 사항입니다. 통합 체계의 서명 검증 프로세스를 사용하여 유효성을 검사할 암호 텍스트의 서명입니다.

    출력 유형이 로 설정된 payload경우 비대칭 암호화 작업에서 사용할 수 있습니다.
    표 5. 반환
    유형 설명
    안 함

    이 예제에서는 withAdditionalInput() 을 사용하여 KMFCryptoOperation 개체에 문자열 기반 서명을 추가합니다.

    var signature = "John Doe";
var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SIGNATURE_VERIFICATION")
  .withAdditionalInput(signature);

var value = GlideStringUtil.base64Encode("Text to encode"); // Default input format is KMFBase64
var result = op.doOperation(String(value));

    이 예제에서는 withAdditionalInput() 을 사용하여 KMFCryptoOperation 개체에 서명 및 임시 키를 추가합니다. doOperation() 호출 및 payload 설명의 값과 같은 긴 값은 가독성을 위해 잘리고 타원으로 대체되었습니다.

    var payload = new sn_kmf_ns.KMFEncryptionPayload();
payload.signature = "pkg...";
payload.ephemeral_key = " BDi...";
payload.ephemeral_key_format = "x962";

var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_DECRYPTION")
  .withAdditionalInput(payload)
  .doOperation("afFS...";

    KMFCryptoOperation - withAlgorithm(문자열 알고리즘)

    래핑할 키 구성 요소와 연결된 알고리즘을 설정합니다.

    표 6. 매개변수
    이름 유형 설명
    알고리즘 문자열 사용할 알고리즘입니다.
    유효한 값은 다음과 같습니다.
    • AES: 대칭 키 유형
    • EC: 비대칭 키 유형
    • HMAC: 대칭 키 유형
    • RSA: 비대칭 키 유형
    표 7. 반환
    유형 설명
    안 함

    이 예제에서는 withAlgorithm() 을 사용하여 EC에 사용되는 암호화 알고리즘을 변경합니다.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","ASYMMETRIC_WRAPPING").withAlgorithm("EC");
var value = GlideStringUtil.base64Encode("Sample key"); // Default input format is KMFBase64
var result = op.doOperation(String(value));

    KMFCryptoOperation - withInputFormat(문자열 inputFormat)

    암호화 작업이 수행될 입력 데이터의 데이터 형식을 설정합니다. 데이터를 디코딩할 때 지정된 형식을 사용합니다.

    표 8. 매개변수
    이름 유형 설명
    입력 형식 문자열 입력 데이터의 형식입니다.
    유효한 값은 다음과 같습니다.
    • FORMATTED: 키 관리 프레임워크(KMF) 사양에 따라 형식이 지정됩니다.
    • KMFBASE64: Base64 인코딩.
    • KMF_GLIDE_ENCRYPTER_FORMATTED: KMF 암호화 값과 GlideEncrypter 암호화 값 모두의 암호 해독을 지원합니다.
    • KMFNONE: 인코딩이 없습니다.

    기본값: KMFCryptoOperation 개체가 인스턴스화될 때 지정된 작업에 의해 결정되는 값입니다. 자세한 내용은 KMFCryptoOperation - KMFCryptoOperation(String cryptoModuleName, String operationName) 문서를 참조하십시오.
    표 9. 반환
    유형 설명
    안 함

    이 예제에서는 withInputFormat() 을 사용하여 인코딩이 없도록 입력 형식을 변경합니다.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_ENCRYPTION").withInputFormat("KMFNone");
var result = op.doOperation("Text with no encoding"); // Pass in unencrypted String

    이 예제에서는 withInputFormat() 을 사용하여 입력 형식을 KMF_GLIDE_ENCRYPTER_FORMATTED로 변경합니다.

    var encryptOp = new sn_kmf_ns.KMFCryptoOperation("<module_name>", "SYMMETRIC_DECRYPTION")
 .withInputFormat("KMF_GLIDE_ENCRYPTER_FORMATTED")
 .withOutputFormat("KMFNone"); 

var clear_text = encryptOp.doOperation(<encrypted_text>);

    KMFCryptoOperation - withOutputFormat(문자열 outputFormat)

    암호화 작업에 의해 반환되는 출력 데이터의 데이터 형식을 설정합니다. 데이터를 인코딩할 때 지정된 형식을 사용합니다.

    표 10. 매개변수
    이름 유형 설명
    outputFormat 문자열 출력 데이터의 형식입니다.
    유효한 값은 다음과 같습니다.
    • FORMATTED: 키 관리 프레임워크(KMF) 사양에 따라 형식이 지정됩니다.
    • KMFBASE64: Base64 인코딩.
    • KMFNONE: 디코딩이 없습니다. MAC_VERIFICATION 및 SIGNATURE_VERIFICATION에만 지원됩니다.

    이 메서드가 호출되지 않는 경우 기본값: KMFCryptoOperation 개체가 인스턴스화될 때 지정된 작업에 의해 결정되는 값입니다. 자세한 내용은 KMFCryptoOperation - KMFCryptoOperation(String cryptoModuleName, String operationName) 문서를 참조하십시오.
    표 11. 반환
    유형 설명
    안 함

    이 예제에서는 withOutputFormat() 을 사용하여 암호 해독의 출력 형식을 KMFNone(기본값은 KMFBase64)으로 설정합니다.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_DECRYPTION").withOutputFormat("KMFNone");
var clear_data = op.doOperation(<FORMATTED_data>); // Pass in default of FORMATTED data

    KMFCryptoOperation - withOutputType(문자열 outputType)

    암호화 작업이 수행된 후 반환되는 출력 데이터의 데이터 유형을 설정합니다.

    주:
    또는 SIGNATURE_VERIFICATION 작업에 대해 MAC_VERIFICATION 개체를 인스턴스화 KMFCryptoOperation 하는 경우 부울을 전달하여 이 메서드를 호출하여 올바른 출력 형식을 설정해야 하며 그렇지 않으면 작업을 실행할 때 예외가 throw됩니다.
    표 12. 매개변수
    이름 유형 설명
    출력 유형 문자열 출력 데이터의 유형입니다.

    모든 출력 유형을 모든 작업에 적용할 수 있는 것은 아닙니다. 지원되지 않는 형식의 경우 예외가 throw됩니다.

    유효한 값(대/소문자 구분 안 함):
    • 문자열: or SIGNATURE_VERIFICATION 연산에 MAC_VERIFICATION 유효하지 않습니다.
    • 부울: 또는 SIGNATURE_VERIFICATION 연산에만 MAC_VERIFICATION 유효합니다.
    • 페이로드: 해당 작업에만 ASYMMETRIC_ENCRYPTION 유효합니다. EC-IES에 이 출력 유형을 사용합니다.
    주:
    Payload의 출력을 지정할 때 doOperation() 메서드의 출력은 KMFEncryptionPayload 개체입니다. 이 객체의 구조에 대한 자세한 내용은 withAdditionalInput()을 참조하십시오.

    기본값: KMFCryptoOperation 개체가 인스턴스화될 때 지정된 작업에 의해 결정된 값입니다. 자세한 내용은 KMFCryptoOperation - KMFCryptoOperation(String cryptoModuleName, String operationName) 문서를 참조하십시오.
    표 13. 반환
    유형 설명
    안 함

    이 예제에서는 withOutputType() 을 사용하여 MAC_VERIFICATION의 출력 유형을 부울로 설정합니다.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","MAC_VERIFICATION")
  .withOutputType("Boolean").withAdditionalInput(<MAC>);
var value = GlideStringUtil.base64Encode("Text to sign"); // Default input type is KMFBase64
var result = op.doOperation(String(value));

    KMFCryptoOperation - withSysId(문자열 sysId)

    KMFCryptoOperation 개체에서 래핑할 키의 sys_id 설정합니다. 키의 대칭 및 비대칭 래핑에 적용할 수 있습니다.

    표 14. 매개변수
    이름 유형 설명
    sysID 문자열 래핑할 키의 Sys_id입니다.

    표: 모듈 키 [sys_kmf_module_key]
    표 15. 반환
    유형 설명
    안 함

    이 예제에서는 withSysId() 를 사용하여 래핑할 키를 정의합니다.

    var op = new sn_kmf_ns.KMFCryptoOperation("global.sj_cm","SYMMETRIC_WRAPPING").withSysId("0d06ce525b231010f86d1b341d81c777");
var wrappedKey = operation.doOperation(); // No need to pass data when using withSysId()