関数用のAPIとライブラリ | 関数

関数では、以下のAPIとライブラリを使用できます：

Crypto
Crypto-ES.js
TweetNaCl.js
JavaScript Console API

Crypto

この機能は、Tealium Functions用の高性能な暗号化およびハッシュライブラリをJavaで実装しています。既存のJavaScriptベースのCrypto-ESライブラリの直接的な代替品であり、同じインターフェースを提供します。

詳細については、NPM: Crypto-ESを参照してください。

ライブラリのインポート

Tealiumの暗号ライブラリをインポートするには、コードに次の行を追加します：

import C from "tealium/crypto";

モジュールのインポート

Tealium Cryptoライブラリは、特定の暗号機能を提供する個別のクラスを持つモジュールに整理されています。必要なモジュールのみをインポートすることで、関数のパフォーマンスを最適化できます。

利用可能なモジュールのリスト：

import { SHA384Algo } from 'tealium/crypto/lib/sha384.js';
import { SHA512Algo } from 'tealium/crypto/lib/sha512.js';
import { SHA3Algo } from 'tealium/crypto/lib/sha3.js';
import { RIPEMD160Algo } from 'tealium/crypto/lib/ripemd160.js';
import { PBKDF2Algo } from 'tealium/crypto/lib/pbkdf2.js';
import { EvpKDFAlgo } from 'tealium/crypto/lib/evpkdf.js';
import { AESAlgo } from 'tealium/crypto/lib/aes.js';
import { DESAlgo } from 'tealium/crypto/lib/tripledes.js';
import { TripleDESAlgo } from 'tealium/crypto/lib/tripledes.js';
import { RabbitAlgo } from 'tealium/crypto/lib/rabbit.js';
import { RabbitLegacyAlgo } from 'tealium/crypto/lib/rabbit-legacy.js';
import { RC4Algo } from 'tealium/crypto/lib/rc4.js';
import { RC4DropAlgo } from 'tealium/crypto/lib/rc4.js';
import { CBC } from 'tealium/crypto/lib/mode-cbc.js';
import { CFB } from 'tealium/crypto/lib/mode-cfb.js';
import { CTR } from 'tealium/crypto/lib/mode-ctr.js';
import { ECB } from 'tealium/crypto/lib/mode-ecb.js';
import { OFB } from 'tealium/crypto/lib/mode-ofb.js';
import { GCM } from 'tealium/crypto/lib/mode-gcm.js';
import { AnsiX923 } from 'tealium/crypto/lib/pad-ansix923.js';
import { Iso10126 } from 'tealium/crypto/lib/pad-iso10126.js';
import { Iso97971 } from 'tealium/crypto/lib/pad-iso97971.js';
import { NoPadding } from 'tealium/crypto/lib/pad-nopadding.js';
import { ZeroPadding } from 'tealium/crypto/lib/pad-zeropadding.js';
import { Pkcs7 } from 'tealium/crypto/lib/pad-pkcs7.js';
import { OpenSSLFormatter } from "tealium/crypto/lib/cipher/OpenSSLFormatter.js";
import { HexFormatter } from 'tealium/crypto/lib/format-hex.js';
import { OpenSSLKdf } from "tealium/crypto/lib/cipher/OpenSSLKdf.js";
import { MD5 } from 'tealium/crypto/lib/md5.js';
import { HmacMD5 } from 'tealium/crypto/lib/md5.js';
import { SHA1 } from 'tealium/crypto/lib/sha1.js';
import { HmacSHA1 } from 'tealium/crypto/lib/sha1.js';
import { SHA224 } from 'tealium/crypto/lib/sha224.js';
import { HmacSHA224 } from 'tealium/crypto/lib/sha224.js';
import { SHA256 } from 'tealium/crypto/lib/sha256.js';
import { HmacSHA256 } from 'tealium/crypto/lib/sha256.js';
import { SHA384 } from 'tealium/crypto/lib/sha384.js';
import { HmacSHA384 } from 'tealium/crypto/lib/sha384.js';
import { SHA512 } from 'tealium/crypto/lib/sha512.js';
import { HmacSHA512 } from 'tealium/crypto/lib/sha512.js';
import { SHA3 } from 'tealium/crypto/lib/sha3.js';
import { HmacSHA3 } from 'tealium/crypto/lib/sha3.js';
import { RIPEMD160 } from 'tealium/crypto/lib/ripemd160.js';
import { HmacRIPEMD160 } from 'tealium/crypto/lib/ripemd160.js';
import { PBKDF2 } from 'tealium/crypto/lib/pbkdf2.js';
import { EvpKDF } from 'tealium/crypto/lib/evpkdf.js';
import { AES } from 'tealium/crypto/lib/aes.js';
import { DES } from 'tealium/crypto/lib/tripledes.js';
import { TripleDES } from 'tealium/crypto/lib/tripledes.js';
import { Rabbit } from 'tealium/crypto/lib/rabbit.js';
import { RabbitLegacy } from 'tealium/crypto/lib/rabbit-legacy.js';
import { RC4 } from 'tealium/crypto/lib/rc4.js';
import { RC4Drop } from 'tealium/crypto/lib/rc4.js';
import { CRC32 } from 'tealium/crypto/lib/crc32.js';

例

ハッシュ化とモード

Galois/CounterモードはCTRGladmanモードの代わりに提供されます。AES暗号でC.mode.GCMを使用します：

import C from "tealium/crypto";
const msg = "message";
const key = C.enc.Hex.parse(
"0123456789ABCDEF11113333555577770123456789ABCDEF1111333355557777");
const iv = C.enc.Hex.parse("0102030405060708090A0B0C");
const encrypted = C.AES.encrypt(msg, key, { iv, mode: C.mode.GCM, padding: C.pad.NoPadding });
const decrypted = C.AES.decrypt(encrypted, key, { iv, mode: C.mode.GCM, padding: C.pad.NoPadding });

追加認証データとタグ長はパラメータとして渡すことができます：

import C from "tealium/crypto";
const msg = "message";
const key = C.enc.Hex.parse(
"0123456789ABCDEF11113333555577770123456789ABCDEF1111333355557777");
const iv = C.enc.Hex.parse("0102030405060708090A0B0C");
const aad = C.enc.Utf8.parse("additional authentication data");
const tagLength = 128; // bits
const encrypted = C.AES.encrypt(msg, key, { iv, mode: C.mode.GCM, padding: C.pad.NoPadding, aad, tagLength });
const decrypted = C.AES.decrypt(encrypted, key, { iv, mode: C.mode.GCM, padding: C.pad.NoPadding, aad, tagLength });

GCM.macメソッドは提供されていませんが、暗号化された出力にはハッシュと連結されたタグも含まれます：

import C from "tealium/crypto";
const msg = "message";
const key = C.enc.Hex.parse(
"0123456789ABCDEF11113333555577770123456789ABCDEF1111333355557777");
const iv = C.enc.Hex.parse("0102030405060708090A0B0C");
const tagLength = 128; // bits
const encrypted = C.AES.encrypt(msg, key, { iv, mode: C.mode.GCM, padding: C.pad.NoPadding, tagLength });
const sEncrypted = encrypted.ciphertext.toString();
const tag = sEncrypted.slice(sEncrypted.length - tagLength / 8 * 2, sEncrypted.length);
const hash = sEncrypted.slice(0, sEncrypted.length - tag.length);

メッセージを復号するには、ハッシュとタグを連結する必要があります：

import C from "tealium/crypto";
import CryptoES from "crypto-es";
const msg = "message";
const key = C.enc.Hex.parse("0123456789ABCDEF11113333555577770123456789ABCDEF1111333355557777");
const iv = C.enc.Hex.parse("0102030405060708090A0B0C");
const aad = C.enc.Utf8.parse("additional authentication data");
const tagLength = 120;
// encrypt with third-party
const encrypted = CryptoES.AES.encrypt(msg, key, { iv, mode: CryptoES.mode.GCM, padding: CryptoES.pad.NoPadding });
const tag = CryptoES.mode.GCM.mac(CryptoES.algo.AES, key, encrypted.iv, aad, encrypted.ciphertext, tagLength / 8);
// decrypt with tealium/crypto
const decrypted = C.AES.decrypt(C.lib.CipherParams.create({ ciphertext: C.enc.Hex.parse(encrypted.ciphertext.toString() + tag) }), key, { iv, mode: C.mode.GCM, padding: C.pad.NoPadding, aad, tagLength });

CRC32

CRC32はcrypto-esの拡張機能として追加され、index.jsまたは名前付きインポートで利用可能です：

import C from "tealium/crypto"; // C.CRC32
import { CRC32 } from "tealium/crypto/lib/crc32.js";

どちらの場合も、関数はデータを表す引数を取ります：

CRC32.buf(byte array): 8ビット符号なし整数のシーケンス（Uint8Arrayまたはバイトの配列）を期待します。
CRC32.bstr(binary string): バイトiがUCS-2文字の下位バイトであるバイナリ文字列を期待します：str.charCodeAt(i) & 0xFF
CRC32.str(string): 標準的なJavaScript文字列を期待し、UTF-8エンコーディングのハッシュを計算します。
CRC32.reset(): インスタンスは状態を持っており、ハッシュ計算後に手動でリセットが必要です。
CRC32.valueOf(): 状態の32ビット符号付き整数表現を返します。

使用例：

import { CRC32 } from "tealium/crypto/lib/crc32.js";
// 単一の反復
const hash1 = CRC32.str("input").valueOf();
CRC32.reset();
// 複数
const hash2 = CRC32
    .buf([11, 111, 88])
    .str("try")
    .bstr("more")
    .valueOf();
CRC32.reset();
// 符号なしに変換
const uHash1 = hash1 >>> 0;
// 16進数に変換
const hHash1 = (hash1 >>> 0).toString(16);

エラーメッセージ

Tealiumの暗号ライブラリはcrypto-esよりも入力データに対して厳格であるため、無効な使用の場合に以下のエラーが発生する可能性があります：

エラー	説明
`Invalid AES key length`	AES暗号のキーサイズは32バイトでなければなりません。
`Wrong key size`	DES暗号のキーサイズは8バイト、TripleDESの場合は16バイトでなければなりません。
`Wrong IV length`	一部の暗号とモードのIVサイズは厳格です（DES、TripleDES、OFB）正しく指定する必要があります。
`Input length not multiple of 16 bytes`	`NoPadding`パッドが使用され、入力は正しくパディングされている必要があります。
`Parameters missing`	その構成オブジェクトは有効ではありません。例えば、必須IVモード（OFB、CFB）の`iv`パラメータが欠けています。
`No IV set when one expected`	BouncyCastle実装モードで必須のIV（CTR）の構成オブジェクトに`iv`パラメータが欠けています。

Crypto-ES.js

crypto-es.jsライブラリは引き続きサポートされ、既存の実装で利用可能です。ただし、新しいユースケースでは、同じインターフェースを提供しつつ、パフォーマンスとモジュラーインポートが向上したTealium暗号ライブラリの使用をお勧めします。

Crypto-ES.jsは、ハッシュ、エンコーディング、暗号アルゴリズムを提供する暗号ライブラリです。詳細については、NPM: Crypto-ESを参照してください。

次の例は、テキストの暗号化と復号化の方法を示しています：

import CryptoES from 'crypto-es';

var encrypted = CryptoES.AES.encrypt("Message", "Secret Passphrase");
console.log(encrypted);
var decrypted = CryptoES.AES.decrypt(encrypted, "Secret Passphrase");
console.log(CryptoES.enc.Utf8.stringify(decrypted));

AES暗号のGCMモード

Crypto-ESライブラリはAES暗号のGCMモードをサポートしています。次の例は、AES GCMモードを使用してテキストを暗号化および復号化する方法を示しています：

// crypto-esライブラリの一部としてインポート
import CryptoES from "crypto-es";
// コンピューティングリソースを節約するために名前付きエクスポートとしてインポート（上記のようにライブラリ全体をインポートする場合は機能しません）
import { GCM } from "crypto-es/lib/mode-gcm.js";

// 暗号化
const msg = "Original Message";
const key = CryptoES.enc.Hex.parse("0123456789ABCDEF11113333555577770123456789ABCDEF1111333355557777");
const iv = CryptoES.enc.Hex.parse("0102030405060708090A0B0C");
const authData = CryptoES.enc.Utf8.parse("Additional authentication data");
const encrypted = CryptoES.AES.encrypt(msg, key, { iv, mode: CryptoES.mode.GCM });
const authTag = CryptoES.mode.GCM.mac(CryptoES.algo.AES, key, encrypted.iv,  authData, encrypted.ciphertext, 16);
const enveloped = encrypted.iv.toString() + encrypted.ciphertext.toString() + authTag.toString();
console.log("encrypted: ", encrypted);
console.log("authTag: ", authTag);
console.log("enveloped: ", enveloped);

// 復号
const decrypted = CryptoES.AES.decrypt(encrypted, key, { iv, mode: CryptoES.mode.GCM });
console.log("decrypted: ", decrypted.toString(CryptoES.enc.Utf8));

SHA3アルゴリズム

crypto-ESライブラリはオリジナルのSHA3アルゴリズムを提供しています。次の例は、SHA3アルゴリズムの使用方法を示しています：

import { SHA3 } from "crypto-es/lib/sha3-original.js";

const hash = SHA3("Original Message", { outputLength: 256 });
console.log("hash: ", hash);

CRC32アルゴリズム

crypto-ESライブラリはCRC32アルゴリズムを提供しています。各CRC32関数はデータを表す引数を取り、オプションで開始シード（ローリングCRC用）を表す第二引数を取ります。戻り値は符号付き32ビット整数です。サポートされている関数は次のとおりです：

CRC32.buf(byte array[, seed]) – 最初の引数は8ビット符号なし整数のシーケンス（Uint8Arrayまたはバイトの配列）です。
CRC32.bstr(binary string[, seed]) – 最初の引数はバイトiがUCS-2文字の下位バイトであるバイナリ文字列です：str.charCodeAt(i) & 0xFF
CRC32.str(string[, seed]) – 最初の引数は標準的なJS文字列で、UTF-8エンコーディングのハッシュを計算します。

次の例は、CRC32アルゴリズムの使用方法を示しています：

import CRC32 from "crypto-es/lib/crc32.js";

const hash = CRC32.str("Original Message");
console.log("hex value: ", (hash >>> 0).toString(16));

TweetNaCl.js

TweetNaClは、秘密鍵認証暗号、公開鍵認証暗号、ハッシュおよび公開鍵署名を実装する暗号ライブラリです。TweetNaClライブラリはイベントおよび訪問関数専用です。

イベントまたは訪問関数にTweetNaCl.jsモジュールを次のようにインポートします：

import nacl from 'tweetnacl';

詳細については、NPM TweetNaCl.jsを参照してください。

JavaScriptコンソールAPI

JavaScriptコンソール関数を使用して、メッセージとエラーをログに書き込みます。

console.log()、console.info()、console.debug()ログメッセージは情報出力ストリームに行きます。console.warn()およびconsole.error()ログメッセージはエラー出力ストリームに行きます。

情報およびエラー出力ストリームは、関数呼び出し毎に10Kbのデータに制限されています。ログメッセージがこの制限を超える場合、ログファイルには最初の10Kbのデータが含まれ、次のメッセージで終了します：
Output was too large and has been truncated.

コンソールオブジェクトは、関数でサポートされている他のメソッドを提供します。コンソールオブジェクトに関するJavaScriptの仕様を参照してください。サポートされている追加のコンソールメソッドは次のとおりです：

assert()
count()
countReset()
group()
groupEnd()
time()
timeEnd()
timeLog()

コンソールAPIの出力

ほとんどのコンソール関数の出力は、ログ表示のメッセージセクションに表示されます。例えば：

Messages:

Function Start

console.warn()およびconsole.error()からの出力は、メッセージ出力の下にあるエラーセクションに表示されます。次のようになります：

Errors:

Warning - page not found
Error - variable not defined

console.assert()

関数がEventStreamでトリガーされ、次のようにconsole.assert()が呼び出された場合：

console.assert(visitor, "visitor not defined");

visitorオブジェクトはトリガーがAudienceStreamの場合にのみ定義されるため、アサーションは偽であり、出力は次のようになります：

Assertion failed: visitor not defined

console.group() と console.groupEnd()

console.group() と console.groupEnd() は、ログ内の関連メッセージを整理するために使用できます。console.group() の後に続く console.log() メッセージはログ内でインデントされます。インデントは console.groupEnd() が呼び出された後に終了します。

関数コードに以下が含まれている場合：

console.group("Event info:");
console.log("Account: ", event.account);
console.log("Visitor ID: ", event.visitor_id);
console.groupEnd();

出力は以下の通りです：

Event info:
  Account:  Acme Mfg
  Visitor ID:  017407a1d9e50019633c3cea732703079011607100bd6

console.time() と console.timeLog()

関数が console.time() を呼び出すと、出力はありません。その文字列で console.time() が呼び出された時間が記録されます。同じ文字列で console.timeLog() が呼び出されると、出力は指定された文字列に続いて console.time() が呼び出されてから経過した時間です：

Current Time: : 1ms

関数が console.timeEnd() を呼び出した後、console.time() が再び呼び出されるまで console.timeLog() を呼び出すことはできません。

console.count() と console.countReset()

同じ文字列で console.count() が呼び出されるたびに、カウントが増加します。console.count() の出力は、文字列に続いてカウントです。console.count("Current count: "); が2回呼び出されると、出力は以下の通りです：

Current count: : 1
Current count: : 2

console.countReset() は指定された文字列のカウントをゼロにリセットします。