Docs » Linux Kernel Crypto API » Developing Cipher Algorithms
Developing Cipher Algorithms
Registering And Unregistering Transformation
There are three distinct types of registration functions in the Crypto API. One is used to register a generic cryptographic transformation, while the other two are specific to HASH transformations and COMPRESSion. We will discuss the latter two in a separate chapter, here we will only look at the generic ones.
Crypt APIには、３つの異なる種類の登録関数があります。１つは、一般的な cryptographic transformationを登録するもので、残り二つは、HASH trasnfomationとCOMPRESSionです。最後の２つについては別の機会に議論するとして、ここでは本来の一般的な最初についてだけ見ていきます。
Before discussing the register functions, the data structure to be filled with each, struct crypto_alg, must be considered – see below for a description of this data structure.
登録関数について議論する前に、それぞれ埋めるべきデータ構造体、struct crypt_alg について考えなければなりません。このデータ構造の詳細は以下を確認してください。
The generic registration functions can be found in include/linux/crypto.h and their definition can be seen below. The former function registers a single transformation, while the latter works on an array of transformation descriptions. The latter is useful when registering transformations in bulk, for example when a driver implements multiple transformations.
一般的な登録関数は、include/linux/crypto.hで見つけることができ、それらの定義は以下で見ることができます。former functionはsingle transformationを登録します、後者はtransfomation descriptorsの配列を登録します。。後者は、transformationをまとめて登録するときに役に立ちます。例えば、ドライバーには複数のtransfomationが実装されている場合です。
int crypto_register_alg(struct crypto_alg *alg);
int crypto_register_algs(struct crypto_alg *algs, int count);
The counterparts to those functions are listed below.
これらの関数に対応するものは、以下になります。
void crypto_unregister_alg(struct crypto_alg *alg);
void crypto_unregister_algs(struct crypto_alg *algs, int count);
The registration functions return 0 on success, or a negative errno value on failure. crypto_register_algs() succeeds only if it successfully registered all the given algorithms; if it fails partway through, then any changes are rolled back.
登録関数は成功したら0を、失敗したら負のerrno valueを返します。crypto_register_algs()では、全ての与えられたアルゴリズムに対して、登録が成功した場合にのみ成功となります。途中で失敗した場合には、変更はすべてロールバックされます。
The unregistration functions always succeed, so they don’t have a return value. Don’t try to unregister algorithms that aren’t currently registered.
登録解除関数は常に成功し、戻り値はありません。現在登録していないアルゴリズムに対して、登録解除を試みないでください。
Single-Block Symmetric Ciphers [CIPHER]
Example of transformations: aes, serpent, …
This section describes the simplest of all transformation implementations, that being the CIPHER type used for symmetric ciphers. The CIPHER type is used for transformations which operate on exactly one block at a time and there are no dependencies between blocks at all.
このセクションでは、全てのtransfomation実装のなかでもっとも単純である、symmtric ciphersを用いたCIPHER typeについて記述します。CIPHER typeは、一度に唯一の１ブロックのみを操作し、ブロック間に依存性の無いときに使われます。
Registration specifics
The registration of [CIPHER] algorithm is specific in that struct crypto_alg field .cra_type is empty. The .cra_u.cipher has to be filled in with proper callbacks to implement this transformation.
[CIPHER] algorithmの登録は、構造体crypto_alg のfirld .cra_typeが空である特徴を持ちます。このtransofrmを実装するには、cra_u.cipherに適切なコールバックを入力しなければなりません。
See struct cipher_alg below.
Cipher Definition With struct cipher_alg
Struct cipher_alg defines a single block cipher.
構造体cipher_algは、single block cipherを定義します。
Here are schematics of how these functions are called when operated from other part of the kernel. Note that the .cia_setkey() call might happen before or after any of these schematics happen, but must not happen during any of these are in-flight.
以下は、kernelのほかの部分から処理されたときに、これらの関数がどのように呼び出されるのかを示す図である。cia_setkey()は、これらの処理が実行される前か後に呼び出され、決して実行中には呼ばれないことに注意してください。
KEY ---. PLAINTEXT ---.
v v
.cia_setkey() -> .cia_encrypt()
|
'-----> CIPHERTEXT
Please note that a pattern where .cia_setkey() is called multiple times is also valid:
cia_setkey()が複数回呼ばれるパターンも有効であることを注意してください。
KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --.
v v v v
.cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt()
| |
'---> CIPHERTEXT1 '---> CIPHERTEXT2
Multi-Block Ciphers
Example of transformations: cbc(aes), chacha20, …
This section describes the multi-block cipher transformation implementations. The multi-block ciphers are used for transformations which operate on scatterlists of data supplied to the transformation functions. They output the result into a scatterlist of data as well.
このセクションでは、multi-block cipher transformの実装について記述します。multi-block cipherは、transfomation functionに提供されるデータのscatterlistを操作するtransformに使用されています。また結果をデータのscatterlistの中に出力します。
Registration Specifics
The registration of multi-block cipher algorithms is one of the most standard procedures throughout the crypto API.
multi-block cipher algorimの登録は、crypto APIを通過する最も基本的なやり方の１つである。
Note, if a cipher implementation requires a proper alignment of data, the caller should use the functions of crypto_skcipher_alignmask() to identify a memory alignment mask. The kernel crypto API is able to process requests that are unaligned. This implies, however, additional overhead as the kernel crypto API needs to perform the realignment of the data which may imply moving of data.
cipher実装は、dataの適切なアライメントを期待していることに注意してください。呼び出し元は、crypto_skcipher_alignmask()の関数を使って、メモリアライメントマスクを扱わねばなりません。kernel crypyo APIは、alignmentがあっていない要求を実行することができます。ただし、カーネル暗号APIがデータの再調整を実行する必要があるため、データの移動を意味する可能性があるため、これは追加のオーバーヘッドを意味します。
Cipher Definition With struct skcipher_alg
Struct skcipher_alg defines a multi-block cipher, or more generally, a length-preserving symmetric cipher algorithm.
構造体 skcipher_algでは、multi-block cipher、より一般的に言えば、長さ維持する対象cipher algorithmを定義します。
Scatterlist handling
Some drivers will want to use the Generic ScatterWalk in case the hardware needs to be fed separate chunks of the scatterlist which contains the plaintext and will contain the ciphertext. Please refer to the ScatterWalk interface offered by the Linux kernel scatter / gather list implementation.
ハードウェアに平文と暗号文を含むscatterlistの個別のチャンクを供給する必要がある場合に備えて、一部のドライバはGeneric ScatterWalkを使用することを望みます。