Edit

CryptoKey

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

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

例題

たとえば 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)

概要

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 : Text) : Text     utf8 形式の message 文字列を署名します
.size : Integer     キーのサイズ (ビット単位)
.type : Text     キーのタイプ: "RSA", "ECDSA", "PEM"
.verify( message : Text ; signature : Text ; options : Object) : object     utf8 形式の message 文字列の署名を検証します

4D.CryptoKey.new()

履歴

バージョン	内容
v18 R4	追加

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

参照	タイプ		説明
settings	オブジェクト	->	キーペアを生成・ロードするための設定
result	4D.CryptoKey	<-	暗号化キーペアをカプセル化したオブジェクト

|

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

settings

プロパティ	タイプ	説明
curve	text	ECDSA 曲線名
pem	text	ロードする PEM 形式の暗号化キー
size	integer	RSA キーのサイズ (ビット単位)
type	text	キーのタイプ: "RSA", "ECDSA", "PEM"

cryptoKey

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

.curve

履歴

バージョン	内容
v18 R4	追加

.curve : Text

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

.decrypt()

履歴

バージョン	内容
v18 R4	追加

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

参照	タイプ		説明
message	テキスト	->	options.encodingEncrypted を使ってデコードし復号するメッセージ文字列
options	オブジェクト	->	デコーディングオプション
戻り値	オブジェクト	<-	ステータス

.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
result	text	options.encodingDecrypted を使って復号およびデコードされたメッセージ
errors	collection	success が false の場合、エラーのコレクションが含まれている場合があります。

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

.encrypt()

履歴

バージョン	内容
v18 R4	追加

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

参照	タイプ		説明
message	テキスト	->	options.encodingDecrypted を使ってエンコードし暗号化するメッセージ文字列
options	オブジェクト	->	エンコーディングオプション
戻り値	テキスト	<-	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()

履歴

バージョン	内容
v18 R4	追加

.getPrivateKey() : Text

参照	タイプ		説明
戻り値	テキスト	<-	PEM 形式の秘密鍵

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

戻り値

戻り値は秘密鍵です。

.getPublicKey()

履歴

バージョン	内容
v18 R4	追加

.getPublicKey( ) : Text

参照	タイプ		説明
戻り値	テキスト	<-	PEM 形式の公開鍵

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

戻り値

戻り値は公開鍵です。

---

.pem

履歴

バージョン	内容
v18 R4	追加

.pem : Text

ロードする PEM 形式の暗号化キー

。 秘密鍵を渡した場合、RSA または ECDSA の公開鍵は秘密鍵から推定されます。## .sign()

履歴

バージョン	内容
v18 R4	追加
.sign (message : Text ; options : Text) : Text	参照	タイプ		説明
-------	------	--	-----------------------------------------------
message	テキスト	->	署名をするメッセージ
options	オブジェクト	->	署名オプション
戻り値	テキスト	<-	"encoding" オプションに応じて Base64 または Base64URL 形式の署名	.sign() 関数は、cryptoKey オブジェクトキーおよび指定された options を使って、utf8 形式の message 文字列を署名します

。 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

履歴

バージョン	内容
v18 R4	追加

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

履歴

バージョン	内容
v18 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()

履歴

バージョン	内容
v18 R4	追加
.verify( message : Text ; signature : Text ; options : Object) : object	参照	タイプ		説明
---------	------	--	-----------------------------------------------------------
message	テキスト	->	署名生成時に使われたメッセージ文字列
signature	テキスト	->	検証の対象である、options.encoding に応じて Base64 または Base64URL 形式の署名
options	オブジェクト	->	署名オプション
戻り値	オブジェクト	<-	検証ステータス	.verify() 関数は、cryptoKey オブジェクトキーおよび指定された options を使って、utf8 形式の message 文字列の署名を検証します

。

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 の場合、エラーのコレクションが含まれている場合があります。