バージョン: 20

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` オブジェクトの秘密鍵を返します (PEM形式)
.getPublicKey() : Text `CryptoKey` オブジェクトの公開鍵を返します (PEM形式)
.pem : Text ロードする PEM 形式の暗号化キー。秘密鍵を渡した場合、RSA または ECDSA の公開鍵は秘密鍵から推定されます。
.sign (message : Text ; options : Object) : Text .sign (message : Blob ; options : Object) : Text utf8 形式の message 文字列またはBlobを署名します。
.size : Integer キーのサイズ (ビット単位)
.type : Text キーのタイプ: "RSA", "ECDSA", "PEM"
.verify( message : Text ; signature : Text ; options : Object) : Object .verify( message* : Blob ; signature : Text ; options : Object) : Object utf8 形式の message 文字列の署名を検証します。

4D.CryptoKey.new()

履歴

リリース	内容
18 R4	追加

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

Parameter	Type		Description
settings	Object	->	Settings to generate or load a key pair
Result	4D.CryptoKey	<-	Object encapsulating an encryption key pair

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

settings

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

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

Parameter	Type		Description
message	Text	->	Message string to be decoded using `options.encodingEncrypted` and decrypted.
options	Object	->	Decoding options
Result	Object	<-	Status

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

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

options

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

戻り値

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

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

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

.encrypt()

履歴

リリース	内容
18 R4	追加

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

Parameter	Type		Description
message	Text	->	Message string to be encoded using `options.encodingDecrypted` and encrypted.
options	Object	->	Encoding options
Result	Text	<-	Message encrypted and encoded using the `options.encodingEncrypted`

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

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

options

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

戻り値

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

.getPrivateKey()

履歴

リリース	内容
18 R4	追加

.getPrivateKey() : Text

Parameter	Type		Description
Result	Text	<-	Private key in PEM format

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

戻り値

戻り値は秘密鍵です。

.getPublicKey()

履歴

リリース	内容
18 R4	追加

.getPublicKey() : Text

Parameter	Type		Description
Result	Text	<-	Public key in PEM format

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

戻り値

戻り値は公開鍵です。

.pem

履歴

リリース	内容
18 R4	追加

.pem : Text

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

.sign()

履歴

リリース	内容
20 R8	Blob 形式のメッセージをサポート
18 R4	追加

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

Parameter	Type		Description
message	Text OR Blob	->	Message to sign
options	Object	->	Signing options
Result	Text	<-	Signature in Base64 or Base64URL representation, depending on "encoding" option

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

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

options

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

履歴

リリース	内容
20 R8	Blob 形式のメッセージをサポート
18 R4	追加

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

Parameter	Type		Description
message	Text OR Blob	->	Message that was used to produce the signature
signature	Text	->	Signature to verify, in Base64 or Base64URL representation, depending on `options.encoding` value
options	Object	->	Signing options
Result	Object	<-	Status of the verification

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

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

options

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

戻り値

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

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

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

概要​

4D.CryptoKey.new()​

settings​

CryptoKey​

例題 1​

例題 2​

.curve​

.decrypt()​

options​

戻り値​

.encrypt()​

options​

戻り値​

.getPrivateKey()​

戻り値​

.getPublicKey()​

戻り値​

.pem​

.sign()​

options​

戻り値​

.size​

.type​

.verify()​

options​

戻り値​

概要

4D.CryptoKey.new()

settings

CryptoKey

例題 1

例題 2

.curve

.decrypt()

options

戻り値

.encrypt()

options

戻り値

.getPrivateKey()

戻り値

.getPublicKey()

戻り値

.pem

.sign()

options

戻り値

.size

.type

.verify()

options

戻り値