/ 
Tripletail-0.65
River stage zero No dependents
/ Tripletail::Serializer

NAME

Tripletail::Serializer - 値の直列化

SYNOPSIS

my $ser = $TL->newSerializer();
$ser->setCryptoKey($key); # must be 32 octets long

my $bin = $ser->serialize([100, 'foo', {bar => 'baz'}]);
my $val = $ser->deserialize($bin);
# $val equals to [100, 'foo', {bar => 'baz'}]

DESCRIPTION

Perl の各種の値をオクテット列に直列化する。 そのフォーマットは直列化結果が可能な限り小さくなるように設計されており、 また ZLIB 形式による圧縮や AES アルゴリズムによる暗号化、Adler-32 チェックサムによる誤り検出をサポートしている。

METHODS

$TL->newSerializer
my $ser = $TL->newSerializer();

Tripletail::Serializer のインスタンスを生成する。引数は取らない。

getCryptoKey
my $key = $ser->getCryptoKey();

オクテット列表現の暗号化および復号に使用する AES 共通鍵を返す。 もし鍵が設定されていなければ undef を返す。

setCryptoKey
$ser->setCryptoKey($key);

オクテット列表現の暗号化および復号に使用する AES 共通鍵を設定する。 鍵長は 256 ビット、32 バイトでなければならず、それ以外の長さの鍵を設定しようとした場合には die する。 undef を指定した場合には鍵が設定されていない状態になる。

serialize
my $val = [100, 'foo', {bar => 'baz'}];
my $bin = $ser->serialize($val);

第一引数に与えられた任意の値を直列化する。 もしその中に bless されたリファレンスが存在した場合には die する。 AES 共通鍵が設定されていれば暗号化を行い、されていなければ行わない。

deserialize
my $val = $ser->deserialize($bin);

第一引数に与えられた、直列化されたデータを元に戻す。

もしデータが暗号化されているならば設定されている AES 共通鍵を用いて復号を行う。 その際に鍵が設定されていなければ die する。

AES 共通鍵が設定されているにもかかわらずデータが暗号化されていない場合にも die する。 この動作はセキュリティ上の理由による。

FORMAT

本クラスで用いる直列化のフォーマットを以下に述べる。それには主として RFC 4234 (http://tools.ietf.org/html/rfc4234) を用いるが、ビット表現については EBML RFC Draft (http://matroska.org/technical/specs/rfc/index.html) のものを使用する。

document = header payload

直列化結果（以下ドキュメント）はヘッダとペイロードから成る。

header        = 5%b0 is-encrypted is-compressed has-checksum
is-encrypted  = BIT
is-compressed = BIT
has-checksum  = BIT

ヘッダ長は 1 オクテットであり、その上位 5 ビットは常にゼロである。 is-encrypted ビットは後述の暗号化が行われているかどうかを、 is-compressed ビットは圧縮されているかどうかを、 has-checksum ビットは Adler-32 チェックサムが存在するかどうかを示す。 ただし is-compressed と has-checksum は排他である。

payload              = encrypted-payload / plain-payload

encrypted-payload    = iv AES-CBC(plain-payload)
iv                   = 16OCTET

plain-payload        = compressed-payload / uncompressed-payload
compressed-payload   = ZLIB(value)
uncompressed-payload = value-with-checksum / value
value-with-checksum  = value ADLER32(value)

ペイロードには次の 6 種類がある。

暗号化され、圧縮されている

暗号化には AES アルゴリズムの CBC モードを使用する。鍵長は 256 ビット、ブロック長は 128 ビットである。 IV はランダムな 16 オクテットであり、パディングには PKCS#7 (http://tools.ietf.org/html/rfc5652#section-6.3) 形式を用いる。

暗号化され、圧縮されておらず、チェックサムが存在する

チェックサムには Adler-32 (http://tools.ietf.org/html/rfc1950#section-8) アルゴリズムを用いる。これは network byte order の 4 オクテットで記録される。

暗号化され、圧縮されておらず、チェックサムも存在しない

この形式では誤った鍵を用いてペイロードを復号した場合にエラーになる事を保証できないため推奨されない。

暗号化されておらず、圧縮されている

圧縮には RFC 1950 (http://tools.ietf.org/html/rfc1950) ZLIB 形式を用いる。 この場合 ZLIB 形式の定義により必ずその内部に Adler-32 チェックサムが存在する。 従って圧縮されている場合には独立のチェックサムが付けられる事は無い。

暗号化も圧縮もされておらず、チェックサムが存在する

この形式は ZLIB 圧縮すると却って結果が肥大化する場合に限って用いられる。

暗号化も圧縮もされておらず、チェックサムも存在しない

この形式では不正なペイロードを "deserialize" した場合にエラーになる事を保証できないため推奨されない。

value = %x00                     ; undef
      / %x01 vint                ; non-negative integer
      / %x02 vint                ; negative integer
      / %x03 size *OCTET         ; IEEE 754 floating point number
      / %x04 size *OCTET         ; octet string
      / %x05 size *OCTET         ; UTF-8 string
      / %x06 size *value         ; array
      / %x07 size *(value value) ; hash

整数および浮動小数点数は、それを表現するために必要な最小のオクテット数を用いて network byte order で格納される。 整数の幅は任意だが、浮動小数点数の幅は 0, 4, 8 オクテットのいずれかでなければならない。 幅ゼロの整数は 0 を、幅ゼロの浮動小数点数は 0.0 をそれぞれ表す。

負の整数はその絶対値で表現する。

ハッシュテーブルは複数個のキーと値のペアで表現されるが、そのキーには整数、オクテット列、UTF-8 文字列のみが使用可能である。

size = vint
vint = ( %b0 vint 7BIT ) / ( %b1 7BIT )

整数およびデータ長は可変長整数で表現される。その形式は EBML RFC Draft "2.1. Variable size integer" (http://matroska.org/technical/specs/rfc/index.html) に定義されたものと同一である。例:

Width  Size  Representation
  1    2^7   1xxx xxxx
  2    2^14  01xx xxxx  xxxx xxxx
  3    2^21  001x xxxx  xxxx xxxx  xxxx xxxx
  4    2^28  0001 xxxx  xxxx xxxx  xxxx xxxx  xxxx xxxx

AUTHOR INFORMATION

Copyright 2006-2012 YMIRLINK Inc.

This framework is free software; you can redistribute it and/or modify it under the same terms as Perl itself

このフレームワークはフリーソフトウェアです。あなたは Perl と同じライセンスの 元で再配布及び変更を行うことが出来ます。

Address bug reports and comments to: tl@tripletail.jp

Web site: http://tripletail.jp/