日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
CRYPTO(9) FreeBSD カーネル開発者マニュアル CRYPTO(9)
名称
crypto -- カーネルの暗号サービスのための API
書式
#include <opencrypto/cryptodev.h>
int32_t
crypto_get_driverid(device_t, int);
int
crypto_register(uint32_t, int, uint16_t, uint32_t,
int (*)(void *, uint32_t *, struct cryptoini *),
int (*)(void *, uint64_t), int (*)(void *, struct cryptop *),
void *);
int
crypto_kregister(uint32_t, int, uint32_t,
int (*)(void *, struct cryptkop *), void *);
int
crypto_unregister(uint32_t, int);
int
crypto_unregister_all(uint32_t);
void
crypto_done(struct cryptop *);
void
crypto_kdone(struct cryptkop *);
int
crypto_find_driver(const char *);
int
crypto_newsession(uint64_t *, struct cryptoini *, int);
int
crypto_freesession(uint64_t);
int
crypto_dispatch(struct cryptop *);
int
crypto_kdispatch(struct cryptkop *);
int
crypto_unblock(uint32_t, int);
struct cryptop *
crypto_getreq(int);
void
crypto_freereq(void);
#define CRYPTO_SYMQ 0x1
#define CRYPTO_ASYMQ 0x2
#define EALG_MAX_BLOCK_LEN 16
struct cryptoini {
int cri_alg;
int cri_klen;
int cri_mlen;
caddr_t cri_key;
uint8_t cri_iv[EALG_MAX_BLOCK_LEN];
struct cryptoini *cri_next;
};
struct cryptodesc {
int crd_skip;
int crd_len;
int crd_inject;
int crd_flags;
struct cryptoini CRD_INI;
#define crd_iv CRD_INI.cri_iv
#define crd_key CRD_INI.cri_key
#define crd_alg CRD_INI.cri_alg
#define crd_klen CRD_INI.cri_klen
struct cryptodesc *crd_next;
};
struct cryptop {
TAILQ_ENTRY(cryptop) crp_next;
uint64_t crp_sid;
int crp_ilen;
int crp_olen;
int crp_etype;
int crp_flags;
caddr_t crp_buf;
caddr_t crp_opaque;
struct cryptodesc *crp_desc;
int (*crp_callback) (struct cryptop *);
caddr_t crp_mac;
};
struct crparam {
caddr_t crp_p;
u_int crp_nbits;
};
#define CRK_MAXPARAM 8
struct cryptkop {
TAILQ_ENTRY(cryptkop) krp_next;
u_int krp_op; /* すなわち, CRK_MOD_EXP
またはその他 */
u_int krp_status; /* 返り状態 */
u_short krp_iparams; /* 入力パラメータの数 */
u_short krp_oparams; /* 出力パラメータの数 */
uint32_t krp_hid;
struct crparam krp_param[CRK_MAXPARAM];
int (*krp_callback)(struct cryptkop *);
};
解説
crypto は、``消費者'' (他のカーネルサブシステムと /dev/crypto デバイスに
よるユーザ) が、それを利用することができるように、カーネルで登録される暗
号ハードウェアのドライバのためのフレームワークです。ドライバは、フレーム
ワークでそれらがサポートするアルゴリズムを登録し、フレームワークが、セッ
ションを確立し、使用し、破壊するために呼ぶかもしれないエントリポイント
(関数) を提供します。セッションは、特別のドライバ (あるいは関連するハード
ウェア) の中の暗号の情報をキャッシュするために使用されます。したがって、
初期化は、すべてのリクエストで必要ではありません。暗号のサービスの消費者
は、データ (2 つ以上の暗号の操作が要求できます) で適用されるべき操作のフ
レームワーク (とそれで登録されたドライバ) を指示する 1 組の記述子を渡しま
す。
キー操作は、同じようにサポートされます。上に記述された対称な演算子と異な
り、これらのセッションがないコマンドは、入力と出力のパラメータを使用し
て、数学的な操作を実行します。
消費者がプロセスに関連することができないので、ドライバは、sleep(9) (ス
リープ) できません。同じことはフレームワークにも当てはまります。したがっ
て、コールバックメカニズムは、リクエストが完了したことを (コールバック
は、リクエスト単位で消費者によって指定されます) 消費者に通知するために使
用されます。リクエストが成功して終わっても終わらなかったとしても、コール
バックは、フレームワークによって呼び出されます。エラー表示は、後の場合に
提供されます。特定のエラーコード、EAGAIN は、セッション番号が変更され、リ
クエストが新しいセッション番号で直ちに再提出できることを示すために使用さ
れます。コールバックを呼び出す不十分な情報が利用可能な場合 (引数の検証に
おける致命的なエラーがあることを意味して)、エラーは、呼び出し関数にのみ返
されます。セッション初期化と破壊については、コールバックメカニズムが使用
されていません。
crypto_find_driver() 関数は、提供された名前の特有の id を返すために呼び出
されます。指定されたドライバが見つけられなかったなら、返された id は、-1
です。
crypto_newsession() ルーチンは、フレームワークを持った新しいセッションを
確立したい、暗号サービス (ipsec(4) スタックのような) の消費者によって呼び
出されます。2 番目の引数は、ドライバがセッションを確立するために必要な情
報をすべて含んでいます。3 番目の引数は、特有のドライバ id、またはハード
ウェアデバイスを選択するための CRYPTOCAP_F_HARDWARE またはソフトウェアデ
バイスを選択するための CRYPTOCAP_F_SOFTWARE の 1 つまたは両方のいずれかで
す。両方が指定されるなら、ソフトウェアデバイスが返される前に、ハードウェ
アデバイスが返されます。成功すると、最初の引数によって指された値は、セッ
ション識別子 (SID) です。cryptoini 構造体中の様々なフィールドは、次の通り
です:
cri_alg アルゴリズム識別子を含んでいます。現在サポートされたアルゴリズ
ムは、次の通りです:
CRYPTO_AES_128_NIST_GMAC
CRYPTO_AES_192_NIST_GMAC
CRYPTO_AES_256_NIST_GMAC
CRYPTO_AES_CBC
CRYPTO_AES_ICM
CRYPTO_AES_NIST_GCM_16
CRYPTO_AES_NIST_GMAC
CRYPTO_AES_XTS
CRYPTO_ARC4
CRYPTO_BLF_CBC
CRYPTO_CAMELLIA_CBC
CRYPTO_CAST_CBC
CRYPTO_DEFLATE_COMP
CRYPTO_DES_CBC
CRYPTO_3DES_CBC
CRYPTO_MD5
CRYPTO_MD5_HMAC
CRYPTO_MD5_KPDK
CRYPTO_NULL_HMAC
CRYPTO_NULL_CBC
CRYPTO_RIPEMD160_HMAC
CRYPTO_SHA1
CRYPTO_SHA1_HMAC
CRYPTO_SHA1_KPDK
CRYPTO_SHA2_256_HMAC
CRYPTO_SHA2_384_HMAC
CRYPTO_SHA2_512_HMAC
CRYPTO_SKIPJACK_CBC
cri_klen 可変サイズのキーアルゴリズムのために、ビットでキーの長さを指定
します。
cri_mlen 計算されたハッシュからのいくつのバイトをコピーして戻されるべき
であるかを指定します。0 は、すべてのハッシュを意味します。
cri_key アルゴリズムと共に使用されるキーを含んでいます。
cri_iv それがデータの接頭辞でない場合、明示的な初期化ベクトル (IV) を
含んでいます。このフィールドは、(crypto_newsession) を初期化の
間に無視されます。IV が明示的に渡された場合 (詳細は、下記を参
照)、ランダムな IV は、リクエストを処理するデバイスドライバに
よって使用されます。
cri_next 別の cryptoini 構造体へのポインタを含んでいます。複数のそのよう
な構造は、多重アルゴリズムセッション (ipsec(4) は、そのような特
徴の消費者の例です) を確立するためにリンクされるかもしれませ
ん。
cryptoini 構造体およびその内容は、フレームワーク (あるいは使用されるドラ
イバ) によって修正されません。返された SID を使用する処理のための後のリク
エストは、ハードウェア (本質的には、SID は、ドライバのセッションキャッ
シュ中のインデックスの役割をします) を再初期化するコストを回避します。
crypto_freesession() は、セッションを廃止するために crypto_newsession()
によって返された SID で呼び出されます。
crypto_dispatch() は、リクエストを処理するために呼び出されます。cryptop
構造体中の様々なフィールドは、次の通りです:
crp_sid SID を含んでいます。
crp_ilen 処理されるバッファのバイトの長さの合計を示します。
crp_olen 返り時に、結果の長さの合計を含んでいます。対称な暗号の操作
については、これは、入力の長さと同じになります。フレーム
ワークが、結果のために (あるいは入力を再フォーマットするた
めに) に新しいバッファを割り付ける必要がある場合、これが使
用されます。
crp_callback 成功してもしなくても、このルーチンは、リクエストの完了時に
呼び出されます。それは、crypto_done() ルーチンによって呼び
出されます。リクエストが成功しなかった場合、エラーコード
は、crp_etype フィールドに設定されます。適切な spl(9) レベ
ルを設定することは、コールバックルーチンの責任です。
crp_etype 何らかのエラーに遭遇した場合、エラータイプを含んでいます。
またはリクエストが成功して処理された場合、0 を含んでいま
す。EAGAIN エラーコードが返される場合、SID は、変更されてい
ます (そして crp_sid フィールドに記録されます)。消費者は、
新しい SID を記録し、すべての後のリクエストの中でそれを使用
するべきです。この場合、リクエストは、直ちに再提出されるか
もしれません。このメカニズムは、セッション移行 (有効性、性
能または他の動機のために、あるドライバから他のドライバに
セッションを移動させる) を実行するために、フレームワークに
よって使用されます。
crp_callback の中で指定されたコールバックルーチンによって検
査された時、このフィールドのみが意味があることに注意してく
ださい。十分な情報がコールバックルーチン (つまり、渡された
ポインタが NULL である場合に、あるいはコールバックルーチン
が指定されなかった場合に) を呼び出すためには、存在しない場
合に限り、エラーは、crypto_process() の呼び出し側に返されま
す。
crp_flags このリクエストに関連したフラグのビットマスクです。現在定義
されたフラグは、次の通りです:
CRYPTO_F_IMBUF crp_buf によって指されるバッファは、mbuf
チェーンです。
CRYPTO_F_IOV crp_buf によって指されるバッファは、uio
構造体です。
CRYPTO_F_BATCH 可能であれば、バッチ操作。
CRYPTO_F_CBIMM 専用のカーネルスレッドからそれを行う代わ
りに直ちにコールバックします。
CRYPTO_F_DONE 完了した操作。
CRYPTO_F_CBIFSYNC 操作が同期しているなら (ドライバは、
CRYPTOCAP_F_SYNC フラグを指定した)、直ち
にコールバックします。
crp_buf 入力バッファを指します。返る時 (コールバックが呼び出される
場合)、それは、リクエストの結果を含んでいます。入力バッファ
は、crp_flags に依存する mbuf チェーンあるいは連続するバッ
ファかもしれません。
crp_opaque これは、手付かずの暗号のフレームワークを通して渡され、呼び
出されるアプリケーションの使用のために意図されます。
crp_desc これは、記述子のリンクしたリストです。各記述子は、入力バッ
ファ上でどのタイプの暗号の操作を行わなければならないかに関
する情報を提供します。様々なフィールドは、次の通りです:
crd_iv フラグ CRD_F_IV_EXPLICIT が設定されるとき、この
フィールドは、IV を含んでします。
crd_key CRD_F_KEY_EXPLICIT フラグが設定されるとき、
crd_key は、暗号化または認証キーがあるバッファ
を指します。
crd_alg 使用するアルゴリズム。新しいセッション時に与え
られたものと同じでなければなりません。
crd_klen crd_key キー長。
crd_skip 処理が開始するべきところで、入力バッファ中のオ
フセットです。
crd_len crd_skip の後に、どれだけのバイトを処理しなけれ
ばならないかです。
crd_inject crd_inject フィールドは、バッファの始めからバイ
ト単位のオフセットを指定します。暗号化アルゴリ
ズムについて、これは、暗号化するとき、IV が挿入
されるところで、または IV が (crd_flags にした
がって) 暗号解読のために見つけられるところで
す。MAC アルゴリズムについては、これは、鍵のあ
るハッシュの結果が挿入される場所です。
crd_flags 次のフラグが定義されます:
CRD_F_ENCRYPT
暗号化アルゴリズムについては、暗号化が要求
される時 (設定されない場合、解読が実行され
ます)、このビットは、設定されます。
CRD_F_IV_PRESENT
暗号化のために、このビットが、設定されない
なら、パケットを暗号化するために使用される
IV は、crd_inject によって指された位置で書
き込まれます。IV の長さは、暗号化アルゴリ
ズムのブロックサイズと等しいと仮定されま
す。暗号化のために、このビットが設定される
なら、何も行われません。暗号解読のために、
このフラグは、意味がありません。ipsec(4)
の中の half-IV モードのような特別の ``IV
クッキング (料理)'' を行うアプリケーション
は、IV がパケットに書き込まれてはならない
ことを示すこのフラグを使用することができま
す。このフラグは、一般的には、
CRD_F_IV_EXPLICIT フラグと共に使用されま
す。
CRD_F_IV_EXPLICIT
このビットは、crd_iv フィールドで消費者に
よって明示的に提供されるとき、設定されま
す。そうでなければ、暗号化操作については、
IV は、操作を実行するために使用されるドラ
イバによって提供されるのに対して、暗号解読
操作について、IV のオフセットは、
crd_inject フィールドによって提供されま
す。IV が消費者によって ``急いで'' 計算さ
れる場合、このフラグは、一般的に使用され、
データ (いくつかの ipsec(4) 設定、そして暗
号化されたスワップは、そのような 2 つの例
です) に先行しません。
CRD_F_KEY_EXPLICIT
暗号化と認証 (MAC) アルゴリズムにおいて、
このビットは、与えられた操作のために、キー
が crd_key フィールドの消費者によって明白
に提供されるとき、設定されます。そうでなけ
れば、キーは、新しいセッション時に cri_key
フィールドから取られます。キーのスケジュー
ルに時間がかかる計算のように、使用される
キーがしばしば、それら自体のセッションを与
えられることが推奨されます。
CRD_F_COMP
圧縮アルゴリズムについては、圧縮が要求され
る時 (設定されない場合、展開 (非圧縮) が実
行されます)、このビットは、設定されます。
CRD_INI この cryptoini 構造体は、フレームワークあるいは
デバイスドライバによって修正されません。この情
報がすべての暗号の操作リクエストに伴って起こる
ので、ドライバは、オンデマンド (一般的にの高価
な操作) で状態を再初期化することができます。さ
らに、上に記述されるように、暗号のフレームワー
クは、キューが満杯になる結果かハードウェアの失
敗のようにリクエストを再送できます。
crd_next 次の記述子へのポイントです。リンクした操作は、
ipsec(4) のようなプロトコルにおいて有用です。こ
こで複数の暗号の変換は、データの同じブロック上
で適用されるかもしれません。
crypto_getreq() は、それに渡された引数で指定されたのと同数の cryptodesc
構造体のリンクしたリストで cryptop 構造体を割り付けます。
crypto_freereq() は、構造体 cryptop とそれにリンクされたどんな cryptodesc
構造体も割り付けを解放ます。それが cryptop 構造体で不透明なフィールドに関
連した必要なクリーンアップを行うことは、コールバックルーチンの責任である
ことに注意してください。
crypto_kdispatch() は、キーの操作を実行するために呼び出されます。cryptkop
構造体中の様々なフィールドは、次の通りです:
krp_op CRK_MOD_EXP のようなオペレーションコードです。
krp_status リターンコードです。この errno スタイル変数は、より低いレベ
ルのオペレーションが失敗した理由かどうか示します。
krp_iparams 指定された操作への入力パラメータの場合、数です。各操作が多
くの (一般的には固有の) そのようなパラメータを持っているこ
とに注意してください。
krp_oparams 指定された操作への出力パラメータの場合、数です。各操作が多
くの (一般的には固有の) そのようなパラメータを持っているこ
とに注意してください。
krp_kvp パラメータを含んでいるカーネルメモリブロックの配列です。
krp_hid どのローレベルのドライバが使用されているか指定する識別子で
す。
krp_callback コールバックは、キー操作の完了を呼び出しました。
ドライバ側の API
crypto_get_driverid(), crypto_register(), crypto_kregister(),
crypto_unregister(), crypto_unblock() と crypto_done() ルーチンは、カーネ
ル暗号サービスフレームワークで登録と登録取り消しするために暗号の基本をサ
ポートを提供するドライバによって使用されます。
ドライバは、引数として flags を指定して、ドライバの識別子を取得するため
に、crypto_get_driverid() 関数を最初に使用しなければなりません。
CRYPTOCAP_F_SOFTWARE または CRYPTOCAP_F_HARDWARE の 1 つが、指定されなけ
ればなりません。また、CRYPTOCAP_F_SYNC は、指定され、ドライバが、同期して
操作のすべてを行うなら、指定されるべきです。
ドライバがサポートするアルゴリズムごとに、それは、crypto_register() を呼
び出さなければなりません。最初の 2 つの引数は、ドライバとアルゴリズムの識
別子です。次の 2 つの引数は、このアルゴリズム用のできるだけ大きな演算子の
(公開暗号キーの操作にとって重要なビット単位の) 長さおよびフラグを指定しま
す。最後の 4 つの引数は、crypto_register() への最初の呼び出しで提供されな
ければなりません。そして、すべての後の呼び出しで無視されます。それらは、
ドライバで新しい暗号のコンテキストを確立するために、既に確立しているコン
テキストを解放し、(暗号化する、解読するなど) 処理されるリクエストを求める
ために、フレームワークが呼び出すかもしれない、3 つのドライバに提供される
関数へのポインタです。そして、これらのルーチンの各々を呼び出すとき、渡す
不透明なパラメータです。
crypto_unregister() は、アルゴリズムのサポートを取り下げたいドライバに
よって呼び出されます。2 つの引数は、それぞれドライバとアルゴリズムの識別
子です。一般的には、取り出された PCMCIA 暗号カードのためのドライバは、
カードでサポートされたすべてのアルゴリズム用にこのルーチンを呼び出しま
す。crypto_unregister_all() は、ドライバによって登録されたすべてのアルゴ
リズムの登録取り消しをし、ドライバは、無効になります (新しいセッション
は、そのドライバに割り付けられないし、そして任意の既存のセッションは、他
のドライバに移動されます)。ドライバに関連したすべてのアルゴリズムが 1 つ
ずつ登録を取り消される場合、同じことが行われます。crypto_unregister_all()
への呼び出しの後に、ドライバの newsession または freesession 関数のいずれ
かのスレッドがありません。
3 つのドライバに供給されたルーチンのための呼び出しの仕様は、次の通りです:
int (*newsession)(device_t, uint32_t *, struct cryptoini *);
int (*freesession)(device_t, uint64_t);
int (*process)(device_t, struct cryptop *, int);
int (*kprocess)(device_t, struct cryptkop *, int);
呼び出しで、すべてのルーチンへの最初の引数は、crypto_get_driverid() に提
供された device_t です。newsession() への 2 つ目の引数は、
crypto_get_driverid() によって得られたドライバ識別子を含んでいます。成功
した返りの場合、それは、ドライバに特有のセッション識別子を含んでいるべき
です。3 つ目の引数は、crypto_newsession() のそれと同一です。
freesession() ルーチンは、引数として不透明なデータ値と SID (それは、ドラ
イバ識別子とドライバ特有のセッション識別子の連結です) をとります。それ
は、セッション (ハードウェアレジスタ、メモリなどをクリア) に関連したどん
なコンテキストもクリアすべきです。
process() ルーチンは、暗号処理を実行するリクエストで呼び出されます。この
ルーチンは、ブロックまたはスリープしてはなりませんが、要求をキューに入
れ、直ちに返るか、または完了する要求を処理するべきです。回復不能のエラー
の場合には、エラー表示は、cryptop 構造体の crp_etype フィールドに置かれな
ければなりません。リクエストが終了するか、エラーが検出される時、process()
ルーチンは、crypto_done() を呼び出さなければなりません。前述のように、
セッション移動が実行されるかもしれません。
一時的リソース消耗の場合には、process() ルーチンが ERESTART を返すかもし
れません、その場合には、暗号のサービスは、リクエストを再度キューにし、ド
ライバを ``ブロックした'' としてマークし、そして処理のリクエストを提出す
ることをやめます。ドライバは、それが crypto_unblock() ルーチンによってリ
クエストを再び処理することができる時に、暗号サービスに通知することに責任
を負います。この単純なフロー制御メカニズムは、それが暗号のレイヤ (層) の
中でキューにされる操作のように短命のリソース消耗のために単に使われるべき
です。そうすることは、失われたパケットのような失敗の扱いによりネットワー
クプロトコルに性能を低下させるような場合エラーを返すことより望ましい。
kprocess() ルーチンは、暗号のキー処理を実行するリクエストで呼び出されま
す。このルーチンは、ブロックしてはなりません。しかしリクエストをキューに
するべきであり、直ちに返ります。リクエストを処理する際、コールバックルー
チンは、呼び出されるべきです。回復不能のエラーの場合には、エラー表示が、
cryptkop 構造体の krp_status フィールドに置かれなければなりません。リクエ
ストが終了するか、エラーが検出される場合、kprocess() ルーチンは、
crypto_kdone() を呼び出すべきです。
戻り値
crypto_register(), crypto_kregister(), crypto_unregister(),
crypto_newsession(), crypto_freesession() と crypto_unblock() は、成功す
れば 0 を返し、失敗すればエラーコードを返します。crypto_get_driverid()
は、エラーの場合、負ではない値を返し、失敗すれば -1 を返します。
crypto_getreq() は、cryptop 構造体へのポインタを返し、失敗すれば NULL を
返します。その引数またはコールバック関数が NULL だった場合、
crypto_dispatch() は、EINVAL を返し、そうでなければ 0 を返します。コール
バックは、crp_etype フールドで、失敗の場合のエラーコードが提供されます。
関連ファイル
sys/opencrypto/crypto.c ほとんどのフレームワークコード
関連項目
crypto(4), ipsec(4), crypto(7), malloc(9), sleep(9)
歴史
暗号のフレームワークは、OpenBSD 2.7 ではじめて登場し、Angelos D.
Keromytis <angelos@openbsd.org> によって書かれました。
バグ
フレームワークは、現在、crypto_newsession() 操作中のすべてのアルゴリズム
が同じドライバによって利用可能でなければならないと仮定します。その場合、
セッション初期化は、失敗するでしょう。
フレームワークは、さらに、どのドライバがセッションに関連したアルゴリズム
の特定のセットには、最良かを決めるためのメカニズムを必要とします。あるタ
イプのベンチマークは、ここですぐ使える状態です。
同じセッションで同じアルゴリズムの複数のインスタンスは、サポートされませ
ん。3DES が 1 つの (そして DES の 3 つのインスタンスではない) アルゴリズ
ムと考えられることに注意してください。したがって、同じリクエストで 3DES
と DES を混合することができます。
FreeBSD 11.2 July 10, 2015 FreeBSD 11.2