メインコンテンツまでスキップ
バージョン: 20 R7 BETA

CryptoKey

4D ランゲージの CryptoKey クラスは、非対称の暗号化キーペアをカプセル化します。

このクラスは 4D クラスストアより提供されます。

参照

このクラスの包括的な概要については、CryptoKey: 暗号化、復号化、署名、検証! ブログ記事を参照ください。

概要

4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey
暗号化キーペアをカプセル化する 4D.CryptoKey オブジェクトを新規作成します
.curve : Text
キーの楕円曲線名
.decrypt( message : Text ; options : Object ) : Object
秘密 鍵を使って message を復号します
.encrypt( message : Text ; options : Object ) : Text
公開 鍵を使って message を暗号化します
.getPrivateKey() : Text
CryptoKey オブジェクトの秘密鍵を返します
.getPublicKey() : Text
CryptoKey オブジェクトの公開鍵を返します
.sign (message : Text ; options : Object) : Text
utf8 形式の message 文字列を署名します
.size : Integer
キーのサイズ (ビット単位)
.type : Text
キーのタイプ: "RSA", "ECDSA", "PEM"
.verify( message : Text ; signature : Text ; options : Object) : Object
utf8 形式の message 文字列の署名を検証します

4D.CryptoKey.new()

履歴
リリース内容
18 R4追加

4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey

引数説明
settingsObject->キーペアを生成・ロードするための設定
戻り値4D.CryptoKey<-暗号化キーペアをカプセル化したオブジェクト

4D.CryptoKey.new() 関数は、settings オブジェクト引数に基づいて暗号化キーペアをカプセル化する 4D.CryptoKey オブジェクトを新規作成します。 新規の RSA または ECDSA キーを生成するほか、PEM 形式の既存のキーペアをロードすることができます。

settings

プロパティ説明
typetext作成するキーのタイプを定義します:
  • "RSA": .size に指定されたサイズを使って、RSA キーペアを生成します。
  • "ECDSA": .curve に指定された曲線を用いて、楕円曲線デジタル署名アルゴリズム (Elliptic Curve Digital Signature Algorithm) を使ったキーペアを生成します。 ECDSA キーは署名だけに使用されるもので、暗号化には使用できないことに留意してください。
  • "PEM": .pem を使って、PEM 形式のキーペアをロードします。
  • curvetextECDSA 曲線名
    pemtextロードする PEM 形式の暗号化キー
    sizeintegerRSA キーのサイズ (ビット単位)

    CryptoKey

    戻り値の CryptoKey オブジェクトは、暗号化キーペアをカプセル化します。 これは共有オブジェクトのため、複数の 4D プロセスによって同時使用できます。

    例題 1

    メッセージが秘密鍵で署名され、その署名は対応する公開鍵で検証されます。 以下のコードは、簡単なメッセージの署名を作成し、検証するものです。

    • Bob側:
    // メッセージを作成します
    $message:="hello world"
    Folder(fk desktop folder).file("message.txt").setText($message)

    // キーを作成します
    $type:=New object("type";"RSA")
    $key:=4D.CryptoKey.new($type)

    // 公開鍵を取得して保存します
    Folder(fk desktop folder).file("public.pem").setText($key.getPublicKey())

    // 署名を base64 形式で取得して保存します
    Folder(fk desktop folder).file("signature").setText($key.sign($message;$type))

    /*Bob はメッセージと公開鍵、署名を Alice に送信します*/
    • Alice側:
    // メッセージと公開鍵、署名を取得します
    $message:=Folder(fk desktop folder).file("message.txt").getText()
    $publicKey:=Folder(fk desktop folder).file("public.pem").getText()
    $signature:=Folder(fk desktop folder).file("signature").getText()

    // キーを作成します
    $type:=New object("type";"PEM";"pem";$publicKey)
    $key:=4D.CryptoKey.new($type)

    // 署名を検証します
    If ($key.verify($message;$signature;$type).success)
    // 署名は有効です

    End if

    例題 2

    たとえば ES256 JSON Web Token (JWT) を作成するために新規 ECDSA キーペアを使ってメッセージの署名と検証をおこないます。

     // 新規 ECDSA キーペアの生成
    $key:=4D.CryptoKey.new(New object("type";"ECDSA";"curve";"prime256v1"))

    // base64 形式で署名を取得
    $message:="hello world"
    $signature:=$key.sign($message;New object("hash";"SHA256"))

    // 署名の検証
    $status:=$key.verify($message;$signature;New object("hash";"SHA256"))
    ASSERT($status.success)

    .curve

    履歴
    リリース内容
    18 R4追加

    .curve : Text

    ECDSA キーのみ: キーの楕円曲線名。 通常、ES256 (デフォルト) の場合は "prime256v1"、ES384 の場合は "secp384r1"、ES512 の場合は "secp521r1"。

    .decrypt()

    履歴
    リリース内容
    18 R4追加

    .decrypt( message : Text ; options : Object ) : Object

    引数説明
    messageText->options.encodingEncrypted を使ってデコードし復号するメッセージ文字列
    optionsObject->デコーディングオプション
    戻り値Object<-ステータス

    .decrypt() 関数は、秘密 鍵を使って message を復号します。 使用されるアルゴリズムはキーの種類に依存します。

    キーは RSA キーでなければならず、アルゴリズムは RSA-OAEP です (RFC 3447 参照)。

    オプション

    プロパティ説明
    hashtext使用する Digest アルゴリズム。 例: "SHA256", "SHA384", "SHA512"。
    encodingEncryptedtext復号するバイナリ形式に message を変換するためのエンコーディング。 可能な値: "Base64" または "Base64URL"。 デフォルト値: "Base64"
    encodingDecryptedtextバイナリの復号メッセージを文字列に変換するためのエンコーディング。 可能な値: "UTF-8", "Base64" または "Base64URL"。 デフォルト値: "UTF-8"

    結果

    message の復号に成功した場合には、success プロパティが true に設定された status オブジェクトを返します。

    プロパティ説明
    successbooleanメッセージの復号に成功した場合は true
    戻り値textoptions.encodingDecrypted を使って復号およびデコードされたメッセージ
    errorscollectionsuccessfalse の場合、エラーのコレクションが含まれている場合があります。

    キーまたはアルゴリズムが合致しないなどの理由で message の復号に成功しなかった場合、返される status オブジェクトの status.errors プロパティにはエラーのコレクションが格納されます。

    .encrypt()

    履歴
    リリース内容
    18 R4追加

    .encrypt( message : Text ; options : Object ) : Text

    引数説明
    messageText->options.encodingDecrypted を使ってエンコードし暗号化するメッセージ文字列
    optionsObject->エンコーディングオプション
    戻り値Text<-options.encodingEncrypted を使って暗号化およびエンコードされたメッセージ

    .encrypt() 関数は、公開 鍵を使って message を暗号化します。 使用されるアルゴリズムはキーの種類に依存します。

    キーは RSA キーでなければならず、アルゴリズムは RSA-OAEP です (RFC 3447 参照)。

    オプション
    プロパティ説明
    hashtext使用する Digest アルゴリズム。 例: "SHA256", "SHA384", "SHA512"。
    encodingEncryptedtextバイナリの暗号化メッセージを文字列に変換するためのエンコーディング。 可能な値: "Base64" または "Base64URL"。 デフォルト値: "Base64"
    encodingDecryptedtext暗号化するバイナリ形式に message を変換するためのエンコーディング。 可能な値: "UTF-8", "Base64" または "Base64URL"。 デフォルト値: "UTF-8"

    結果

    戻り値は暗号化されたメッセージです。

    .getPrivateKey()

    履歴
    リリース内容
    18 R4追加

    .getPrivateKey() : Text

    引数説明
    戻り値Text<-PEM 形式の秘密鍵

    .getPrivateKey() 関数は、CryptoKey オブジェクトの秘密鍵を返します (PEM形式)。無い場合は空の文字列を返します。

    結果

    戻り値は秘密鍵です。

    .getPublicKey()

    履歴
    リリース内容
    18 R4追加

    .getPublicKey() : Text

    引数説明
    戻り値Text<-PEM 形式の公開鍵

    .getPublicKey() 関数は、 CryptoKey オブジェクトの公開鍵を返します (PEM形式)。無い場合は空の文字列を返します。

    結果

    戻り値は公開鍵です。


    .pem

    履歴
    リリース内容
    18 R4追加

    .pem : Text

    ロードする PEM 形式の暗号化キー。 秘密鍵を渡した場合、RSA または ECDSA の公開鍵は秘密鍵から推定されます。

    .sign()

    履歴
    リリース内容
    18 R4追加

    .sign (message : Text ; options : Object) : Text

    引数説明
    messageText->署名をするメッセージ
    optionsObject->署名オプション
    戻り値Text<-"encoding" オプションに応じて Base64 または Base64URL 形式の署名

    .sign() 関数は、CryptoKey オブジェクトキーおよび指定された options を使って、 utf8 形式の message 文字列を署名します。 options.encoding 属性に指定した値に応じて、base64 または base64URL 形式の署名を返します。

    CryptoKey は有効な 秘密 鍵を格納していなくてはなりません。

    オプション

    プロパティ説明
    hashtext使用する Digest アルゴリズム。 例: "SHA256", "SHA384", "SHA512"。 JWT の生成に使われた場合、ハッシュサイズは PS@, ES@, RS@, または PS@ のアルゴリズムサイズと同じでなくてはなりません。
    encodingEncryptedtextバイナリの暗号化メッセージを文字列に変換するためのエンコーディング。 可能な値: "Base64" または "Base64URL"。 デフォルト値: "Base64"
    pssboolean確率的署名スキーム (PSS) を使用する。 RSA キーでない場合は無視されます。 PS@ アルゴリズム用の JWT を生成する場合は true を渡します。
    encodingtext戻り値の署名のエンコード方式。 可能な値: "Base64" または "Base64URL"。 デフォルト値: "Base64"

    結果

    utf8 形式の message 文字列。

    .size

    履歴
    リリース内容
    18 R4追加

    .size : Integer

    RSA キーのみ: キーのサイズ (ビット単位)。 通常は 2048 (デフォルト)。

    .type

    履歴
    リリース内容
    18 R4追加

    .type : Text

    キーのタイプ: "RSA", "ECDSA", "PEM"。

    • "RSA": settings.size に指定されたサイズを .size として使った、RSA キーペア
    • "ECDSA": settings.curve に指定された曲線を .curve として用いた、楕円曲線デジタル署名アルゴリズム (Elliptic Curve Digital Signature Algorithm) キーペア ECDSA キーは署名だけに使用されるもので、暗号化には使用できないことに留意してください。
    • "PEM": settings.pem.pem として使った、PEM 形式のキーペア

    .verify()

    履歴
    リリース内容
    18 R4追加

    .verify( message : Text ; signature : Text ; options : Object) : Object

    引数説明
    messageText->署名生成時に使われたメッセージ文字列
    signatureText->検証の対象である、options.encoding に応じて Base64 または Base64URL 形式の署名
    optionsObject->署名オプション
    戻り値Object<-検証ステータス

    .verify() 関数は、CryptoKey オブジェクトキーおよび指定された options を使って、utf8 形式の message 文字列の署名を検証します。

    CryptoKey は有効な 公開 鍵を格納していなくてはなりません。

    オプション

    プロパティ説明
    hashtext使用する Digest アルゴリズム。 例: "SHA256", "SHA384", "SHA512"。 JWT の生成に使われた場合、ハッシュサイズは PS@, ES@, RS@, または PS@ のアルゴリズムサイズと同じでなくてはなりません。
    pssboolean確率的署名スキーム (PSS) を使用する。 RSA キーでない場合は無視されます。 PS@ アルゴリズム用の JWT を生成する場合は true を渡します。
    encodingtext署名のエンコード方式。 可能な値: "Base64" または "Base64URL"。 デフォルト値: "Base64"

    結果

    検証で署名が合致した場合には、success プロパティが true に設定された status オブジェクトを返します。

    message、キーまたはアルゴリズムが署名と合致しないなどの理由で検証が成功しなかった場合、返される status オブジェクトの status.errors プロパティにはエラーのコレクションが格納されます。

    プロパティ説明
    successboolean署名がメッセージと合致すれば true
    errorscollectionsuccessfalse の場合、エラーのコレクションが含まれている場合があります。