OpenSSL EVP_PKEY 関数 (公開鍵暗号)

概要

EVP (The Digital EnVeloPe library) は，OpenSSL の暗号機能（暗号化・復号，ダイジェスト，署名など）に関する高レベルのインタフェース(API) を提供するライブラリである．ここでは，公開鍵暗号アルゴリズム用の EVP 関数 (EVP_PKEY_xxx 関数) の概要を示す．なお，EVP_PKEY_xxx 関数は，OpenSSL 1.0.0 から導入されている．

公開鍵暗号用の EVP 関数の利用上の共通的な注意事項を示す．

EVP 関数を利用するには，ヘッダファイル "openssl/evp.h" をインクルードする．
関数の戻り値が int 型のものは，特に指定が無い限り，成功時 1，失敗時 0 または負の値が返る．特に，公開鍵暗号アルゴリズムとしてサポートされていない操作の場合 -2 が返る．
関数の戻り値がポインタ型のものは，エラー発生時 NULL が返る．

公開鍵暗号アルゴリズムを実現するライブラリで用いられるの基本オブジェクト(構造体) は以下である．

 typedef struct evp_pkey_st EVP_PKEY; /* 公開鍵暗号用の鍵構造体 */
	/* アルゴリズム固有の鍵情報 (秘密鍵，公開鍵)，パラメータなどを含む */

 typedef struct evp_pkey_ctx_st EVP_PKEY_CTX;   /* 公開鍵暗号コンテキストの構造体 */
	/* EVP_PKEY，鍵生成情報，アルゴリズム固有のパラメータなどを含む */

公開鍵暗号関数

公開鍵暗号アルゴリズムに関する主な関数を示す．

初期化関連
- EVP_PKEY_new
```
 EVP_PKEY *EVP_PKEY_new(void);
```
  空の鍵構造体(EVP_KEY) を生成する．
  
  この構造体に秘密鍵を設定するためには，EVP_PKEY_set1_RSA などの関数を呼び出す．
- EVP_PKEY_free
```
 void EVP_PKEY_free(EVP_PKEY *key);
```
  鍵構造体 key を解放する．
- EVP_PKEY_CTX_new
```
 EVP_PKEY_CTX *EVP_PKEY_CTX_new(EVP_PKEY *pkey, ENGINE *e);
```
  公開鍵暗号コンテキスト ctx を鍵 pkey とエンジン e で指定されるアルゴリズムを用いて生成する．e が NULL の場合，デフォルトの実装が使われる．
- EVP_PKEY_CTX_new_id
```
 EVP_PKEY_CTX *EVP_PKEY_CTX_new_id(int id, ENGINE *e);
```
  公開鍵暗号コンテキスト ctx を id とエンジン e で指定されるアルゴリズムを用いて生成する．e が NULL の場合，デフォルトの実装が使われる．
  
  id は，EVP_PKEY_RSA, EVP_PKEY_DSA, EVP_PKEY_DH, EVP_PKEY_EC などである．
- EVP_PKEY_CTX_dup
```
 EVP_PKEY_CTX *EVP_PKEY_CTX_dup(EVP_PKEY_CTX *ctx);
```
  公開鍵暗号コンテキスト ctx を複製する．
- EVP_PKEY_CTX_free
```
 void EVP_PKEY_CTX_free(EVP_PKEY_CTX *ctx);
```
  公開鍵暗号コンテキスト ctx を解放する．
- EVP_PKEY_CTX_ctrl
```
 int EVP_PKEY_CTX_ctrl(EVP_PKEY_CTX *ctx, int keytype, int optype, int cmd,
                       int p1, void *p2);
```
  公開鍵暗号コンテキスト ctx の制御操作 (動作パラメータの設定) を行う．
  
  keytype は -1 でない場合，鍵のタイプを示す．optype はどの制御操作が適用されるかを示すマスクである．cmd は制御コマンドであり，p1，p2 は付加パラメータである．
  
  この関数は，直接呼び出さず各暗号アルゴリズムに固有の以下のマクロを利用する．
```
 #include <openssl/rsa.h>

 int EVP_PKEY_CTX_set_signature_md(EVP_PKEY_CTX *ctx, const EVP_MD *md);

 int EVP_PKEY_CTX_set_rsa_padding(EVP_PKEY_CTX *ctx, int pad);
 int EVP_PKEY_CTX_set_rsa_pss_saltlen(EVP_PKEY_CTX *ctx, int len);
 int EVP_PKEY_CTX_set_rsa_rsa_keygen_bits(EVP_PKEY_CTX *ctx, int mbits);
 int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);

 #include <openssl/dsa.h>
 int EVP_PKEY_CTX_set_dsa_paramgen_bits(EVP_PKEY_CTX *ctx, int nbits);

 #include <openssl/dh.h>
 int EVP_PKEY_CTX_set_dh_paramgen_prime_len(EVP_PKEY_CTX *ctx, int len);
 int EVP_PKEY_CTX_set_dh_paramgen_generator(EVP_PKEY_CTX *ctx, int gen);

 #include <openssl/ec.h>
 int EVP_PKEY_CTX_set_ec_paramgen_curve_nid(EVP_PKEY_CTX *ctx, int nid);
```
鍵生成
- EVP_PKEY_keygen_init
```
 int EVP_PKEY_keygen_init(EVP_PKEY_CTX *ctx);
```
  公開鍵暗号コンテキスト ctx を鍵生成処理のために初期化する．
- EVP_PKEY_keygen
```
 int EVP_PKEY_keygen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
```
  鍵生成処理を行う．生成された鍵は，ppkey に書き込まれる．
- EVP_PKEY_paramgen_init
```
 int EVP_PKEY_paramgen_init(EVP_PKEY_CTX *ctx);
```
  公開鍵暗号コンテキスト ctx をパラメータ生成処理のために初期化する．
  
  パラメータとは，DSA 署名アルゴリズムにおけるシステムパラメータ (p, q, g) などである．
- EVP_PKEY_paramgen
```
 int EVP_PKEY_paramgen(EVP_PKEY_CTX *ctx, EVP_PKEY **ppkey);
```
  パラメータ生成処理を行う．生成されたパラメータは，ppkey に書き込まれる．
- EVP_PKEY_set1_XXX
```
 int EVP_PKEY_set1_RSA(EVP_PKEY *pkey, RSA *key);
 int EVP_PKEY_set1_DSA(EVP_PKEY *pkey, DSA *key);
 int EVP_PKEY_set1_DH(EVP_PKEY *pkey, DH *key);
 int EVP_PKEY_set1_EC_KEY(EVP_PKEY *pkey, EC_KEY *key);
```
  pkey によって参照される鍵を key に設定する．
- EVP_PKEY_get1_XXX
```
 RSA *EVP_PKEY_get1_RSA(EVP_PKEY *pkey);
 DSA *EVP_PKEY_get1_DSA(EVP_PKEY *pkey);
 DH *EVP_PKEY_get1_DH(EVP_PKEY *pkey);
 EC_KEY *EVP_PKEY_get1_EC_KEY(EVP_PKEY *pkey);
```
  pkey によって参照される鍵を返す．鍵が正しいタイプでない場合，NULL が返る．
- EVP_PKEY_type
```
int EVP_PKEY_type(int type);
```
  type に対応する鍵タイプを返す．鍵のタイプは，EVP_PKEY_type(pkey->type) で求められる．戻り値は，EVP_PKEY_RSA, EVP_PKEY_DSA, EVP_PKEY_DH, EVP_PKEY_EC のいずれかである．また，type に対応する鍵のタイプが未定義の場合は，NID_undef が返る．
- EVP_PKEY_size
```
 int EVP_PKEY_size(EVP_PKEY *pkey);
```
  鍵データのバイト長を返す．
暗号化･復号
- EVP_PKEY_encrypt_init
```
 int EVP_PKEY_encrypt_init(EVP_PKEY_CTX *ctx);
```
  公開鍵暗号コンテキスト ctx を暗号化用に初期化する．
- EVP_PKEY_encrypt
```
 int EVP_PKEY_encrypt(EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
                      const unsigned char *in, size_t inlen);
```
  in から始まる inlen バイトのデータを暗号化し，out に出力する． out が NULL の場合，outlen に暗号化データの最大バッファ長が設定される． NULL でない場合は，outlen には確保した out バッファの長さを設定しておく．処理成功時，out に書き込まれたバイト長が outlen に設定される．
  
  この関数は，同じコンテキストを用いて複数回呼び出すことができる．
- EVP_PKEY_decrypt_init
```
 int EVP_PKEY_decrypt_init(EVP_PKEY_CTX *ctx);
```
  公開鍵暗号コンテキスト ctx を復号用に初期化する．
- EVP_PKEY_decrypt
```
 int EVP_PKEY_decrypt(EVP_PKEY_CTX *ctx, unsigned char *out, size_t *outlen,
                      const unsigned char *in, size_t inlen);
```
  in から始まる inlen バイトのデータを復号し，out に出力する． out が NULL の場合，outlen に復号データの最大バッファ長が設定される． NULL でない場合は，outlen には確保した out バッファの長さを設定しておく．処理成功時，out に書き込まれたバイト長が outlen に設定される．
  
  この関数は，同じコンテキストを用いて複数回呼び出すことができる．
署名生成･検証
- EVP_PKEY_sign_init
```
 int EVP_PKEY_sign_init(EVP_PKEY_CTX *ctx);
```
  公開鍵暗号コンテキスト ctx を署名生成用に初期化する．
- EVP_PKEY_sign
```
 int EVP_PKEY_sign(EVP_PKEY_CTX *ctx, unsigned char *sig, size_t *siglen,
                   const unsigned char *tbs, size_t tbslen);
```
  tbs から始まる tbslen バイトのデータに署名し，sig に出力する． sig が NULL の場合，siglen に署名の最大バッファ長が設定される． NULL でない場合は，siglen には確保した sig バッファの長さを設定しておく．処理の成功時には，sig に書き込まれたバイト長が siglen に設定される．
  
  この関数は，同じコンテキストを用いて複数回呼び出すことができる．
- EVP_PKEY_verify_init
```
 int EVP_PKEY_verify_init(EVP_PKEY_CTX *ctx);
```
  公開鍵暗号コンテキスト ctx を署名検証用に初期化する．
- EVP_PKEY_verify
```
 int EVP_PKEY_verify(EVP_PKEY_CTX *ctx, const unsigned char *sig, size_t siglen,
                     const unsigned char *tbs, size_t tbslen);
```
  公開鍵暗号コンテキスト ctx を用いて署名検証処理を行う．署名データは， sig から始まる siglen ，検証対象のデータは tbs から始まる tbslen のデータである．検証成功時 1，失敗時 0 が返る．
  
  この関数は，同じコンテキストを用いて複数回呼び出すことができる．
共有鍵生成
- EVP_PKEY_derive_init
```
 int EVP_PKEY_derive_init(EVP_PKEY_CTX *ctx);
```
  公開鍵暗号コンテキスト ctx を共有鍵生成用に初期化する．
- EVP_PKEY_derive_set_peer
```
 int EVP_PKEY_derive_set_peer(EVP_PKEY_CTX *ctx, EVP_PKEY *peer);
```
  公開鍵暗号コンテキスト ctx に公開情報 peer (通常，公開鍵)を設定する．
- EVP_PKEY_derive
```
 int EVP_PKEY_derive(EVP_PKEY_CTX *ctx, unsigned char *key, size_t *keylen);
```
  公開鍵暗号コンテキスト ctx を用いて共有鍵生成を行う． key が NULL の場合，keylen に共有鍵の最大バッファ長が設定される． NULL でない場合は，keylen には確保した key バッファの長さを設定しておく．処理の成功時には，key に書き込まれたバイト長が keylen に設定される．