OpenSSL EVP 関数

概要

EVP (The Digital EnVeloPe library) は，OpenSSL の暗号機能（暗号化・復号，ダイジェスト，署名など）に関する高レベルのインタフェース(API) を提供するライブラリである．暗号機能の実現には，各暗号アルゴリズムに固有の関数群を利用することもできるが，EVP 関数を利用することにより，暗号機能は同一のままアルゴリズムのみを変更することが容易になる（より安全性の高いアルゴリズムや，効率の良いアルゴリズムへの変更など）．

EVP 関数の利用上の共通的な注意事項を示す．

EVP 関数を利用するには，ヘッダファイル "openssl/evp.h" をインクルードする．
ダイジェストや暗号のアルゴリズムを EVP_get_cipherbyname() などを使いその名称で参照する場合，内部テーブルを設定するために，次のいずれかの関数を最初に呼び出す必要がある．
```
 void OpenSSL_add_all_algorithms(void);
 void OpenSSL_add_all_ciphers(void);
 void OpenSSL_add_all_digests(void);
```
暗号機能の実行後，次の関数を呼び出す．
```
 void EVP_cleanup(void);
```
関数の戻り値が int 型のものは，特に指定が無い限り，成功時 1，失敗時 0 を返す．
関数名称の最後に "_ex" の付く関数には，暗号エンジンのパラメータ impl を持つものがある．暗号エンジンは，暗号機能を実現するモジュールでありプラグインとして組み込むことのできるものである(ハードウェアアクセラレーター等を含む)．このパラメータ impl を NULL にするとデフォルトの実装が用いられる．

暗号化・復号関数

暗号化・復号に関する高レベル関数である．初期パラメータを変更することにより，同一コードで異なるアルゴリズムを利用できる．また，これらの関数は，ブロック暗号に対するバッファリングを提供する．

各関数は，利用する暗号関数に対応した構造体 EVP_CIPHER へのポインタを引数に持つ (利用者はこの構造体の内容を意識する必要はない)．また，各関数は，引数に暗号処理の状態情報を管理する構造体 EVP_CIPHER_CTX (暗号コンテキスト) へのポインタを持つ．

初期化関連
- EVP_CIPHER_fetch
```
 EVP_CIPHER *EVP_CIPHER_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                              const char *properties);
```
  提供プロバイダから指定されたアルゴリズムとプロパティの実装を取得する．(ver.3.0)
  
  取得した値 (EVP_CIPHER) は EVP_CIPHER_free() で開放しなければならない．EVP_CIPHER は参照数が管理されており，参照数が 0 になると実際に開放される．
- EVP_CIPHER_CTX_new
```
 EVP_CIPHER_CTX *EVP_CIPHER_CTX_new(void);
```
  暗号コンテキストを取得する．(ver.1.1.1 以降)
  
  取得した暗号コンテキストは EVP_CIPHER_CTX_free()で開放しなければならない．
- EVP_CIPHER_CTX_init
```
 void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *ctx);
```
  暗号コンテキスト ctx を初期化する．(ver.1.0.2 以前)
- EVP_CIPHER_CTX_cleanup
```
 void EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *ctx);
```
  暗号コンテキスト ctx を解放する．暗号処理終了後，重要な情報がメモリ上に残らないようにこの関数を呼ばなければならない．(ver.1.0.2 以前)
- EVP_get_cipherbyname
```
 const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
```
  指定された暗号アルゴリズム名 ("AES-128-CBC", "AES-192-CBC" など)の EVP_CIPHER 構造体を返す．
- EVP_CIPHER_CTX_set_padding
```
 int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
```
  パディングの有効 / 無効を指定する．デフォルトの暗号化は，パディング有効（標準ブロックパディング）である．復号時にパディングがチェックされ取り除かれる．
  
  パラメータ padding が 0 ならば，パディングは無効となる．この場合，暗号化または復号データのデータ長は，暗号ブロック長の整数倍でなければならない．整数倍でない場合，エラーが返る．
- EVP_CIPHER_CTX_set_key_length
```
 int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
```
  暗号コンテキスト ctx に鍵長 keylen を設定する．鍵長が固定の暗号の場合に，固定長以外の値を設定すると，エラーが返る．
暗号化
- EVP_EncryptInit_ex / EVP_EncryptInit
```
 int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, ENGINE *impl,
                        unsigned char *key, unsigned char *iv);
 int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *key,
                     unsigned char *iv);
```
  EVP_EncryptInit_ex は，暗号コンテキスト ctx を暗号関数 type ，暗号エンジン impl で暗号化用に初期化する．ctx は，本関数を呼ぶ前に初期化されなければならない．type は，EVP_des_cbc() のような暗号関数である．impl が NULL の場合，デフォルトの実装が用いられる．
  
  key は，共通鍵暗号の鍵であり，iv は初期ベクトルである．鍵長や初期期ベクトル長は，用いる暗号関数に依存する．type, key または iv が NULL の場合，ctx にある値が利用される．
  
  EVP_EncryptInit は，ctx が初期化される必要がないことと，常にデフォルトの実装が用いられることを除き，EVP_EncryptInit_ex と等価である．
- EVP_EncryptUpdate
```
 int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl,
                       unsigned char *in, int inl);
```
  in から始まる inl バイトのデータを暗号化し，out に出力する． out に書き込まれたバイト長が outl に設定される．書き込まれるデータ長は，入力データと暗号のブロック長に依存し，0 バイトから (inl + cipher_block_size - 1) バイトの間である．out は，このデータ長以上の領域を持たなければならない．
  
  この関数は，連続するデータブロックを暗号化するために複数回呼び出すことができる．
- EVP_EncryptFinal_ex / EVP_EncryptFinal
```
 int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
 int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl);
```
  パディングが有効の場合（デフォルト），最終データを暗号化する．すなわち，ブロック長に満たないデータをパディング処理し暗号化する．
  
  パディングが無効の場合，この関数はデータの暗号化を行わず，ctx にデータが残っていれば（データ長がブロック長の整数倍でない）はエラーを返す．
  
  最終的な暗号化データが out に書き込まれる．少なくとも暗号ブロック 1つ分の領域が必要である．書き込まれたバイト数が outl に設定される．この関数の実行後，暗号化処理は終了する．以後の EVP_EncryptUpdate の呼び出しは無効になる．
  
  EVP_EncryptFinal 関数は，実行後 ctx が自動的に消去されることを除き，EVP_EncryptFinal_ex と等価である．
復号
- EVP_DecryptInit_ex / EVP_DecryptInit
```
 int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, ENGINE *impl,
                        unsigned char *key, unsigned char *iv);
 int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *key,
                     unsigned char *iv);
```
  復号用に暗号コンテキスト ctx を初期化することを除き，EVP_EncryptInit_ex/EVP_EncryptInit と同様である．
- EVP_DecryptUpdate
```
 int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl,
                       unsigned char *in, int inl);
```
  復号を実行することを除き，EVP_EncryptUpdate_ex/EVP_EncryptUpdate と同様である．
- EVP_DecryptFinal_ex / EVP_DecryptFinal
```
 int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
```
  復号を実行し，最終的な復号データが outm に書き込まれる．outm に書き込まれたバイト長が outl に設定される．
  
  パディングが有効の場合，最終ブロックが正しいフォーマットでないときエラーを返す．
  
  EVP_DecryptFinal は，呼び出し後 ctx が消去されることを除き，EVP_DecryptFinal_ex と同様である．
暗号化・復号
- EVP_CipherInit_ex / EVP_CipherInit
```
 int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type, ENGINE *impl,
                       unsigned char *key, unsigned char *iv, int enc);
 int EVP_CipherInit(EVP_CIPHER_CTX *ctx, EVP_CIPHER *type, unsigned char *key,
                    unsigned char *iv, int enc);
```
  enc フラグが 1 のとき暗号化，0 のとき復号用に暗号コンテキスト ctx を初期化することを除き，EVP_EncryptInit_ex や EVP_DecryptInit_ex 等と同様である．
- EVP_CipherUpdate
```
 int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out, int *outl,
                      unsigned char *in, int inl);
```
  暗号コンテキスト ctx の状態情報に基づき，EVP_EncryptUpdate または EVP_DecryptUpdate を呼び出す．
- EVP_CipherFinal_ex / EVP_CipherFinal
```
 int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
 int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm, int *outl);
```
  暗号コンテキスト ctx の状態情報に基づき，EVP_EncryptFinal または EVP_DecryptFinal を呼び出す．暗号化モードの時は，常に 1 が返る．復号モードの時は， EVP_DecryptFinal の戻り値が返る．

メッセージダイジェスト関数

メッセージダイジェストを生成する高レベル関数インタフェースである．

メッセージダイジェスト関数では，メッセージダイジェスト関数を指定する構造体 EVP_MD，およびメッセージダイジェストの状態を管理する構造体 (ダイジェストコンテキスト) EVP_MD_CTX が用いられる．

初期化関連
- EVP_MD_fetch
```
 EVP_MD *EVP_MD_fetch(OSSL_LIB_CTX *ctx, const char *algorithm,
                      const char *properties);
```
  提供プロバイダから指定されたアルゴリズムとプロパティの実装を取得する．(ver.3.0)
  
  取得した値 (EVP_MD) は EVP_MD_free() で開放しなければならない．EVP_MD は参照数が管理されており，参照数が 0 になると実際に開放される．
- EVP_MD_CTX_new
```
 EVP_MD_CTX *EVP_MD_CTX_new(void);
```
  ダイジェストコンテキストを取得する．(ver.1.1.1 以降)
  
  取得したダイジェストコンテキストは EVP_MD_CTX_free()で開放しなければならない．
- EVP_MD_CTX_init
```
 void EVP_MD_CTX_init(EVP_MD_CTX *ctx);
```
  ダイジェストコンテキスト ctx を初期化する．(ver.1.0.2 以前)
- EVP_MD_CTX_create
```
 EVP_MD_CTX *EVP_MD_CTX_create(void);
```
  ダイジェストコンテキスト ctx を生成，初期化し返却する．(ver.1.0.2 以前)
- EVP_MD_CTX_cleanup
```
 int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
```
  ダイジェストコンテキスト ctx を消去する．ctx が必要なくなった時に呼び出す関数である．(ver.1.0.2 以前)
- EVP_get_digestbyname
```
 const EVP_MD *EVP_get_digestbyname(const char *name);
```
  指定されたダイジェスト名 ("MD5", "SHA1", "SHA256" など)の EVP_MD 構造体を返す．
- EVP_MD_size
```
 int EVP_MD_size(const EVP_MD *md);
```
  メッセージダイジェスト md のバイト長を返す．
ダイジェスト生成
- EVP_DigestInit_ex / EVP_DigestInit
```
 int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
 int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
```
  EVP_DigestInit_ex は，ダイジェストコンテキスト ctx をダイジェスト関数 type ，暗号エンジン impl で初期化する．ctx は，本関数を呼ぶ前に初期化されなければならない．impl が NULL の場合，デフォルトの実装が用いられる．
  
  EVP_DigestInit は，ctx が初期化される必要がないことと，常にデフォルトの実装が用いられることを除き，EVP_DigestInit_ex と等価である．
- EVP_DigestUpdate
```
 int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
```
  data から始まる cnt バイトのデータのダイジェストを生成し，ダイジェストコンテキスト ctx を更新する．この関数は，連続するデータのダイジェストを生成するために，同一コンテキスト ctx に対して複数回呼び出すことができる．
- EVP_DigestFinal
```
 int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
 int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, unsigned int *s);
```
  EVP_DigestFinal_ex は，メッセージダイジェストの最終結果を md に設定する．s が NULL でない場合，ダイジェスト長が s に設定される．最大 EVP_MAX_MD_SIZE バイトである．
  
  EVP_DigestFinal は，ダイジェストコンテキスト ctx が自動的に消去されることを除き，EVP_DigestFinal_ex と等価である．

ディジタル署名関数

ディジタル署名の生成と検証を行う高レベル関数インタフェースである．

署名生成
- EVP_SignInit_ex / EVP_SignInit
```
 int EVP_SignInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
 int EVP_SignInit(EVP_MD_CTX *ctx, const EVP_MD *type);
```
  EVP_SignInit_ex は，コンテキスト ctx をダイジェスト関数 type ，暗号エンジン impl で署名生成用に初期化する．ctx は，本関数を呼ぶ前に初期化されなければならない．impl が NULL の場合，デフォルトの実装が用いられる．
  
  EVP_SignInit_ex は，ダイジェスト関数 type のデフォルト実装を用いる．
- EVP_SignUpdate
```
 int EVP_SignUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
```
  d から始まる cnt バイトのデータのダイジェストを生成し，署名コンテキスト ctx に設定する．この関数は，連続するデータのダイジェストを生成するために，同一コンテキスト ctx に対して複数回呼び出すことができる．
- EVP_SignFinal
```
 int EVP_SignFinal(EVP_MD_CTX *ctx, unsigned char *sig, unsigned int *s,
                   EVP_PKEY *pkey);
```
  秘密鍵 pkey を用いて ctx のデータに対する署名を生成し，sig に設定する．書き込まれたデータ長が s に設定される．最大 EVP_PKEY_size(pkey) バイトである．
署名検証
- EVP_VerifyInit_ex / EVP_VerifyInit
```
 int EVP_VerifyInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
 int EVP_VerifyInit(EVP_MD_CTX *ctx, const EVP_MD *type);
```
  EVP_VerifyInit_ex は，コンテキスト ctx をダイジェスト関数 type ，暗号エンジン impl で署名検証用に初期化する．ctx は，本関数を呼ぶ前に初期化されなければならない．impl が NULL の場合，デフォルトの実装が用いられる．
  
  EVP_VerifyInit は，ダイジェスト関数 type のデフォルト実装を用いる．
- EVP_VerifyUpdate
```
 int EVP_VerifyUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
```
  d から始まる cnt バイトのデータのダイジェストを生成し，検証コンテキスト ctx に設定する．この関数は，連続するデータのダイジェストを生成するために，同一コンテキスト ctx に対して複数回呼び出すことができる．
- EVP_VerifyFinal
```
 int EVP_VerifyFinal(EVP_MD_CTX *ctx, unsigned char *sigbuf, unsigned int siglen,
                     EVP_PKEY *pkey);
```
  公開鍵 pkey および sigbuf から始まる siglen バイトの署名を ctx のデータを用いて検証する．署名が正しい場合 1，署名が不正な場合 0，エラーの場合 -1 を返す．
その他
- EVP_PKEY_size
```
 int EVP_PKEY_size(EVP_PKEY *pkey);
```
  署名データの最大バイト長を返す．