関数用の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; // ビット
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; // ビット
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;
// 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);
// 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が必須の場合、構成オブジェクトに`iv`パラメータが欠けています。

Crypto-ESからTealium暗号ライブラリへの移行

tealium/cryptoライブラリはcrypto-esと同じインターフェースを提供し、直接の置き換えとして使用できます。本番環境での予期しない動作を最小限に抑えるために、以下のアプローチのいずれかを使用して移行をテストしてください：

tealium/cryptoライブラリを使用したサンドボックス環境（推奨）
サンドボックス環境で関数を複製し、インポートをtealium/cryptoを使用するように更新します。テストオーディエンスまたはフィードに限定して呼び出しを行い、ライブトラフィックに影響を与えることなく関数が期待通りに動作することを確認します。
既存の関数と並行してtealium/cryptoバージョンを実行する
関数のコピーを作成し、インポートをtealium/cryptoを使用するように更新します。トラフィックの一部をそれにルーティングして、実際の条件下での直接比較を行います。このアプローチは1対1の出力とパフォーマンスの検証を可能にしますが、リソース使用とコストが増加する可能性があります。テスト後は不要なシステム負荷を避けるために複製をオフにします。

テストペイロードを使用したテストタブは、本番負荷をシミュレートせず、信頼性のあるパフォーマンス洞察を提供しないため、使用を避けてください。

検証後、完全に移行し、crypto-esの以前のバージョンをオフにするか削除してください。

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の出力

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

メッセージ：

関数開始

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

エラー：

警告 - ページが見つかりません
エラー - 変数が定義されていません

console.assert()

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

console.assert(visitor, "visitorが定義されていません");

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

アサーション失敗：visitorが定義されていません

console.group() と console.groupEnd()

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

関数コードに次のようなものが含まれている場合：

console.group("イベント情報：");
console.log("アカウント：", event.account);
console.log("ビジターID：", event.visitor_id);
console.groupEnd();

出力は次のようになります：

イベント情報：
  アカウント： Acme Mfg
  ビジターID： 017407a1d9e50019633c3cea732703079011607100bd6

console.time() と console.timeLog()

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

現在の時間：：1ms

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

console.count() と console.countReset()

同じ文字列で console.count() が呼び出されるたびに、カウントが増加します。console.count() の出力は、文字列に続いてカウントです。console.count("現在のカウント："); が2回呼び出された場合、出力は次のようになります：

現在のカウント：：1
現在のカウント：：2

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