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 : 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
| 引数 | タイプ | 説明 | |
|---|---|---|---|
| settings | Object | -> | キーペアを生成・ロードするための設定 |
| result | 4D.CryptoKey | <- | 暗号化キーペアをカプセル化したオブジェクト |
4D.CryptoKey.new() 関数は、settings オブジェクト引数に基づいて暗号化キーペアをカプセル化する 4D.CryptoKey オブジェクトを新規作成します。 新規の RSA または ECDSA キーを生成するほか、PEM 形式の既存のキーペアをロードすることができます。
settings
| プロパティ | タイプ | 説明 |
|---|---|---|
| type | text | 作成するキーのタイプを定義します: |
| curve | text | ECDSA 曲線名 |
| pem | text | ロードする PEM 形式の暗号化キー |
| size | integer | RSA キーのサイズ (ビット単位) |
CryptoKey
戻り値の CryptoKey オブジェクトは、暗号化キーペアをカプセル化します。 これは共有オブジェクトのため、複数の 4D プロセスによって同時使用できます。
.curve
履歴
| リリース | 内容 |
|---|---|
| 18 R4 | 追加 |
.curve : Text
ECDSA キーのみ: キーの楕円曲線名。 通常、ES256 (デフォルト) の場合は "prime256v1"、ES384 の場合は "secp384r1"、ES512 の場合は "secp521r1"。
.decrypt()
履歴
| リリース | 内容 |
|---|---|
| 18 R4 | 追加 |
.decrypt( message : Text ; options : Object ) : Object
| 引数 | タイプ | 説明 | |
|---|---|---|---|
| message | Text | -> | options.encodingEncrypted を使ってデコードし復号するメッセージ文字列 |
| options | Object | -> | デコーディングオプション |
| 戻り値 | Object | <- | ステータス |
.decrypt() 関数は、秘密 鍵を使って message を復号します。 使用されるアルゴリズムはキーの種類に依存します。
キーは RSA キーでなければならず、アルゴリズムは RSA-OAEP です (RFC 3447 参照)。
オプション
| プロパティ | タイプ | 説明 |
|---|---|---|
| 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()
履歴
| リリース | 内容 |
|---|---|
| 18 R4 | 追加 |
.encrypt( message : Text ; options : Object ) : Text
| 引数 | タイプ | 説明 | |
|---|---|---|---|
| message | Text | -> | options.encodingDecrypted を使ってエンコードし暗号化するメッセージ文字列 |
| options | Object | -> | エンコーディングオプション |
| 戻り値 | Text | <- | options.encodingEncrypted を使って暗号化およびエンコードされたメッセージ |
.encrypt() 関数は、公開 鍵を使って message を暗号化します。 使用されるアルゴリズムはキーの種類に依存します。
キーは RSA キーでなければならず、アルゴリズムは RSA-OAEP です (RFC 3447 参照)。
オプション
| プロパティ | タイプ | 説明 |
|---|---|---|
| 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
| 引数 | タイプ | 説明 | |
|---|---|---|---|
| 戻り値 | 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
| 引数 | タイプ | 説明 | |
|---|---|---|---|
| message | Text | -> | 署名をするメッセージ |
| options | Object | -> | 署名オプション |
| 戻り値 | Text | <- | "encoding" オプションに応じて Base64 または Base64URL 形式の署名 |
.sign() 関数は、CryptoKey オブジェクトキーおよび指定された options を使って、 utf8 形式の message 文字列を署名します。 options.encoding 属性に指定した値に応じて、base64 または base64URL 形式の署名を返します。
CryptoKey は有効な 秘密 鍵を格納していなくてはなりません。
オプション
| プロパティ | タイプ | 説明 |
|---|---|---|
| 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()
履歴
| リリース | 内容 |
|---|---|
| 18 R4 | 追加 |
.verify( message : Text ; signature : Text ; options : Object) : object
| 引数 | タイプ | 説明 | |
|---|---|---|---|
| message | Text | -> | 署名生成時に使われたメッセージ文字列 |
| signature | Text | -> | 検証の対象である、options.encoding に応じて Base64 または Base64URL 形式の署名 |
| options | Object | -> | 署名オプション |
| 戻り値 | Object | <- | 検証ステータス |
.verify() 関数は、CryptoKey オブジェクトキーおよび指定された options を使って、utf8 形式の message 文字列の署名を検証します。
CryptoKey は有効な 公開 鍵を格納していなくてはなりません。
オプション
| プロパティ | タイプ | 説明 |
|---|---|---|
| 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 の場合、エラーのコレクションが含まれている場合があります。 |