Edit

CryptoKey

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

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

例題

The following sample code signs and verifies a message using a new ECDSA key pair, for example in order to make a ES256 JSON Web token.

 // Generate a new ECDSA key pair
$key:=4D.CryptoKey.new(New object("type";"ECDSA";"curve";"prime256v1"))

  // Get signature as base64
$message:="hello world"
$signature:=$key.sign($message;New object("hash";"SHA256"))

  // Verify signature
$status:=$key.verify($message;$signature;New object("hash";"SHA256"))
ASSERT($status.success)

Summary

4D.CryptoKey.new( settings : Object ) : 4D.CryptoKey     creates a new 4D.CryptoKey object encapsulating an encryption key pair
.curve : Text     normalised curve name of the key.
.decrypt( message : Text ; options : Object ) : Object     decrypts the message parameter using the private key
.encrypt( message : Text ; options : Object ) : Text     encrypts the message parameter using the public key
.getPrivateKey() : Text     returns the private key of the cryptoKey object
.getPublicKey( ) : Text     returns the public key of the cryptoKey object
.sign (message : Text ; options : Text) : Text     signs the utf8 representation of a message string
.size : Integer     the size of the key in bits
.type : Text     Name of the key type - "RSA", "ECDSA", "PEM"
.verify( message : Text ; signature : Text ; options : Object) : object     verifies the base64 signature against the utf8 representation of message

4D.CryptoKey.new()

履歴

バージョン	内容
v18 R4	追加

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

参照	タイプ		説明
settings	オブジェクト	->	キーペアを生成・ロードするための設定
result	4D.CryptoKey	<-	Object encapsulating an encryption key pair

|

The 4D.CryptoKey.new() function creates a new 4D.CryptoKey object encapsulating an encryption key pair, based upon the settings object parameter. 新規の RSA または ECDSA キーを生成するほか、PEM 形式の既存のキーペアをロードすることができます。

settings

プロパティ	タイプ	説明
curve	text	Name of ECDSA curve
pem	text	PEM definition of an encryption key to load
size	integer	Size of RSA key in bits
type	text	Type of the key: "RSA", "ECDSA", or "PEM"

cryptoKey

The returned cryptoKey object encapsulates an encryption key pair. It is a shared object and can therefore be used by multiple 4D processes simultaneously.

.curve

履歴

バージョン	内容
v18 R4	追加

.curve : Text

Defined only for ECDSA keys: the normalised curve name of the key. Usually "prime256v1" for ES256 (default), "secp384r1" for ES384, "secp521r1" for ES512.

.decrypt()

履歴

バージョン	内容
v18 R4	追加

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

参照	タイプ		説明
message	テキスト	->	Message string to be decoded using options.encodingEncrypted and decrypted.
options	オブジェクト	->	デコーディングオプション
戻り値	オブジェクト	<-	ステータス

The .decrypt() function decrypts the message parameter using the private key. 使用されるアルゴリズムはキーの種類に依存します。

キーは 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"

戻り値

The function returns a status object with success property set to true if the message could be successfully decrypted.

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

In case the message couldn't be decrypted because it was not encrypted with the same key or algorithm, the status object being returned contains an error collection in status.errors.

.encrypt()

履歴

バージョン	内容
v18 R4	追加

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

参照	タイプ		説明
message	テキスト	->	Message string to be encoded using options.encodingDecrypted and encrypted.
options	オブジェクト	->	エンコーディングオプション
戻り値	テキスト	<-	options.encodingEncrypted を使って暗号化およびエンコードされたメッセージ

The .encrypt() function encrypts the message parameter using the public key. 使用されるアルゴリズムはキーの種類に依存します。

キーは 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"

戻り値

The returned value is an encrypted message.

.getPrivateKey()

履歴

バージョン	内容
v18 R4	追加

.getPrivateKey() : Text

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

The .getPrivateKey() function returns the private key of the cryptoKey object in PEM format, or an empty string if none is available.

戻り値

The returned value is the private key.

.getPublicKey()

履歴

バージョン	内容
v18 R4	追加

.getPublicKey( ) : Text

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

The .getPublicKey() function returns the public key of the cryptoKey object in PEM format, or an empty string if none is available.

戻り値

The returned value is the public key.

---

.pem

履歴

バージョン	内容
v18 R4	追加

.pem : Text

PEM definition of an encryption key to load. 秘密鍵を渡した場合、RSA または ECDSA の公開鍵は秘密鍵から推定されます。

.sign()

履歴

バージョン	内容
v18 R4	追加

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

参照	タイプ		説明
message	テキスト	->	署名をするメッセージ
options	オブジェクト	->	署名オプション
戻り値	テキスト	<-	Signature in Base64 or Base64URL representation, depending on "encoding" option

The .sign() function signs the utf8 representation of a message string using the cryptoKey object keys and provided 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	ERepresentation to be used for result signature. 可能な値: "Base64" または "Base64URL"。 デフォルト値: "Base64"

戻り値

The utf8 representation of the message string.

.size

履歴

バージョン	内容
v18 R4	追加

.size : Integer

Defined only for RSA keys: the size of the key in bits. Typically 2048 (default).

.type

履歴

バージョン	内容
v18 R4	追加

.type : Text

Name of the key type - "RSA", "ECDSA", "PEM"

"RSA": an RSA key pair, using settings.size as .size.

"ECDSA": an Elliptic Curve Digital Signature Algorithm key pair, using settings.curve as .curve. ECDSA キーは署名だけに使用されるもので、暗号化には使用できないことに留意してください。

"PEM": a key pair definition in PEM format, using settings.pem as .pem.

.verify()

履歴

バージョン	内容
v18 R4	追加

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

参照	タイプ		説明
message	テキスト	->	署名生成時に使われたメッセージ文字列
signature	テキスト	->	Signature to verify, in Base64 or Base64URL representation, depending on options.encoding value
options	オブジェクト	->	署名オプション
戻り値	オブジェクト	<-	Status of the verification

The .verify() function verifies the base64 signature against the utf8 representation of message using the cryptoKey object keys and provided 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"

戻り値

The function returns a status object with success property set to true if message could be successfully verified (i.e. the signature matches).

In case the signature couldn't be verified because it was not signed with the same message, key or algorithm, the status object being returned contains an error collection in status.errors.

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