楕円曲線演算ライブラリ (OpenSSL)
概要
OpenSSL ライブラリには,ECDSA などの楕円曲線暗号アルゴリズムを実現するために楕円曲線演算のライブラリ関数が用意されている.
楕円曲線ライブラリで用いられる基本オブジェクト(構造体) は以下である.
typedef struct ec_method_st EC_METHOD; /* 楕円演算系の構造体 */
/* 楕円曲線演算関数へのポインタなどを含む */
typedef struct ec_group_st EC_GROUP; /* 楕円曲線の構造体 */
/* EC_METHOD,体の定義,楕円曲線パラメータなどを含む */
typedef struct ec_key_st EC_KEY; /* 楕円暗号鍵の構造体 */
/* EC_GROUP,秘密鍵,公開鍵などを含む */
typedef struct ec_point_st EC_POINT; /* 楕円点の構造体 */
/* EC_METHOD,点の座標などを含む */
楕円曲線暗号で用いられる楕円曲線は,楕円曲線 ID (整数値:NID)または,楕円曲線名称
(文字列)で指定される.OpenSSLの暗号ライブラリでは,内部テーブルとして楕円曲線パラメータを保持している(openssl/obj_mac.h).内部テーブルの楕円曲線を取得する時に,以下の構造体が用いられる.
typedef struct {
int nid;
const char *comment;
} EC_builtin_curve;
楕円点 (x, y) のオクテット列への変換方式を指定するパラメータとして以下が使われる.
typedef enum {
POINT_CONVERSION_COMPRESSED = 2, /* 圧縮形式 */
POINT_CONVERSION_UNCOMPRESSED = 4, /* 非圧縮形式 */
POINT_CONVERSION_HYBRID = 6 /* ハイブリッド形式 */
} point_conversion_form_t;
なお,楕円曲線ライブラリを用いるときは,"openssl/ec.h" をインクルードする.
また,これらの関数を使ったプログラムの例は,暗号プログラム (C言語版) にあります.
関数
関数群は,機能により幾つかのグループに分けられる.各関数に共通的な仕様を示す.
- 戻り値が int 型の関数は,特に指定の無い限り,成功時 1,エラー時 0 が返る.
- 戻り値がオブジェクトの関数は,エラー時 NULL が返る.
- 関数の引数に BN_CTX *ctx を持つものがある.この ctx は,関数の実行時に必要なテンポラリな BIGNUM
を保持するために用いられ,関数内部でのメモリ確保のオーバヘッドを避けるためのものである.これは,オプションであり NULL でもよい.
- 同じ機能でも有限体により異なる関数がある.関数名の最後に _GFp (素体),_GF2m (標数 2 の体) が付く関数である.
以下,主な関数を示す(有限体に依存する関数は素体の関数のみ).
- 楕円曲線関数
楕円曲線 (EC_GROUP) の生成,解放やパラメータの設定,取得を行う関数群である.
- size_t EC_get_builtin_curves (EC_builtin_curve *r, size_t nitems)
r が NULL の場合,内部テーブルの有効な楕円曲線の数を返す. r が NULL でない場合,r に内部テーブルの最初の
nitems 個の楕円曲線情報が設定される.
- EC_GROUP *EC_GROUP_new (const EC_METHOD *meth)
新しい EC_METHOD の EC_GROUP オブジェクトを返す.
- void EC_GROUP_free(EC_GROUP *group)
EC_GROUP オブジェクトを解放する.
- int EC_GROUP_copy (EC_GROUP *dst, const EC_GROUP *src)
EC_GROUP オブジェクト src をコピーし dst とする.どちらも同じ EC_METHOD でなければならない.
- EC_GROUP *EC_GROUP_dup (const EC_GROUP *src)
新しい EC_GROUP オブジェクトを生成し,src の内容をコピーして返す.
- const EC_METHOD *EC_GROUP_method_of (const EC_GROUP *group)
EC_GROUP オブジェクトに用いられている EC_METHOD を返す.
- int EC_METHOD_get_field_type (const EC_METHOD *meth)
EC_METHOD オブジェクトの有限体のタイプ (NID) を返す.
- int EC_GROUP_set_generator (EC_GROUP *group, const EC_POINT *generator, const BIGNUM *order,
const BIGNUM *cofactor)
EC_GROUP のベースポイント(生成元),位数,コファクタを設定する.
- const EC_POINT *EC_GROUP_get0_generator (const EC_GROUP *group)
EC_GROUP のベースポイント(生成元)を返す.
- int EC_GROUP_get_order (const EC_GROUP *group, BIGNUM *order, BN_CTX *ctx)
EC_GROUP の位数 order を取得する.
- int EC_GROUP_get_cofactor (const EC_GROUP *group, BIGNUM *cofactor, BN_CTX *ctx)
EC_GROUP のコファクタ cofactor を取得する.
- void EC_GROUP_set_curve_name (EC_GROUP *group, int nid)
EC_GROUP の楕円曲線 ID を設定する.
- int EC_GROUP_get_curve_name (const EC_GROUP *group)
EC_GROUP の楕円曲線 ID (NID) を返す.設定されていない場合 0 が返る.
- void EC_GROUP_set_point_conversion_form (EC_GROUP *group, point_conversion_form_t form)
楕円点変換形式を form に設定する.
- point_conversion_form_t EC_GROUP_get_point_conversion_form (const EC_GROUP *group)
EC_GROUP の楕円点変換形式を取得する.
- int EC_GROUP_set_curve_GFp (EC_GROUP *group, const BIGNUM *p, const BIGNUM *a, const BIGNUM
*b, BN_CTX *ctx)
GF(p) 上で y2 = x3 + a x + b
によって定義された楕円曲線を EC_GROUP に設定する.
- int EC_GROUP_get_curve_GFp (const EC_GROUP *group, BIGNUM *p, BIGNUM *a, BIGNUM *b, BN_CTX
*ctx)
GF(p) 上で y2 = x3 + a x + b
によって定義された楕円曲線のパラメータ(p,a,b)を取得する.
- int EC_GROUP_get_degree (const EC_GROUP *group)
有限体の元を表すために必要なビット数を返す.
- int EC_GROUP_check (const EC_GROUP *group, BN_CTX *ctx)
EC_GROUP に設定されているパラメータが有効な値か否かを判定する. group が有効ならば 1,さもなくば 0 を返す.
- int EC_GROUP_cmp (const EC_GROUP *a, const EC_GROUP *b, BN_CTX *ctx)
2 つの EC_GROUP オブジェクト a と b を比較する.等しければ 0,異なれば 1 を返す.
- EC_GROUP *EC_GROUP_new_curve_GFp (const BIGNUM *p, const BIGNUM *a, const BIGNUM *b, BN_CTX
*ctx)
GF(p) 上で y2 = x3 + a x + b
によって定義された楕円曲線で新しい EC_GROUP を生成する.
- EC_GROUP *EC_GROUP_new_by_curve_name (int nid)
指定された楕円曲線 ID nid で新しい EC_GROUP オブジェクトを生成する.
- 楕円暗号鍵関数
楕円暗号鍵 (EC_KEY) の生成,解放や変換を行う関数群である.
- EC_KEY *EC_KEY_new (void)
新しい EC_KEY オブジェクトを生成する.
- EC_KEY *EC_KEY_new_by_curve_name (int nid)
楕円曲線 ID nid を用いて EC_KEY を生成する.
- void EC_KEY_free(EC_KEY *key)
EC_KEY オブジェクトを解放する.
- EC_KEY *EC_KEY_copy (EC_KEY *dst, const EC_KEY *src)
EC_KEY オブジェクト src を dst にコピーする.dst を返す.
- EC_KEY *EC_KEY_dup (const EC_KEY *src)
EC_KEY オブジェクトを生成し,src の内容をコピーして返す.
- const EC_GROUP *EC_KEY_get0_group (const EC_KEY *key)
EC_KEY オブジェクトの EC_GROUP オブジェクトを返す.
- int EC_KEY_set_group (EC_KEY *key, const EC_GROUP *group)
EC_KEY オブジェクトに EC_GROUP を設定する.EC_KEY は,独自の EC_GROUP のコピーを使用する.
- const BIGNUM *EC_KEY_get0_private_key (const EC_KEY *key)
EC_KEY オブジェクトの秘密鍵を返す.
- int EC_KEY_set_private_key (EC_KEY *key, const BIGNUM *prv)
EC_KEY オブジェクトに秘密鍵 prv を設定する.EC_KEY は,独自の BIGNUM のコピーを使用する.
- const EC_POINT *EC_KEY_get0_public_key (const EC_KEY *key)
EC_KEY オブジェクトの公開鍵を返す.
- int EC_KEY_set_public_key (EC_KEY *key, const EC_POINT *pub)
EC_KEY オブジェクトに公開鍵 pub を設定する.EC_KEY は,独自の EC_POINT のコピーを使用する.
- int EC_KEY_precompute_mult (EC_KEY *key, BN_CTX *ctx)
EC_KEY 演算を高速化するための生成元のスカラー倍の事前計算テーブルを生成する.
- int EC_KEY_generate_key (EC_KEY *key)
新しい秘密鍵(および公開鍵)を生成する.
- int EC_KEY_check_key (const EC_KEY *key)
EC_KEY の秘密鍵と公開鍵が有効か否かを検査する.有効の場合 1,無効の場合 0 を返す.
- 楕円点操作関数
楕円点 (EC_POINT) の生成,解放や楕円点の座標の取得,変換を行う関数群である.
- EC_POINT *EC_POINT_new (const EC_GROUP *group)
指定された EC_GROUP の新しい楕円点オブジェクトを生成する.
- void EC_POINT_free (EC_POINT *point)
楕円点オブジェクト point を解放する.
- void EC_POINT_clear_free (EC_POINT *point)
楕円点オブジェクト point のメモリクリアと解放を行う.
- int EC_POINT_copy (EC_POINT *dst, const EC_POINT *src)
楕円点 src を dst にコピーする.
- EC_POINT *EC_POINT_dup (const EC_POINT *src, const EC_GROUP *group)
指定された EC_GROUP の新しい楕円点オブジェクトを生成し,楕円点 src の内容をコピーする.
- const EC_METHOD *EC_POINT_method_of (const EC_POINT *point)
楕円点 point に用いられる楕円演算系を返す.
- int EC_POINT_set_to_infinity (const EC_GROUP *group, EC_POINT *point)
楕円点 point を無限遠点 O に設定する.
- int EC_POINT_set_Jprojective_coordinates_GFp (const EC_GROUP *group, EC_POINT *p, const
BIGNUM *x, const BIGNUM *y, const BIGNUM *z, BN_CTX *ctx)
GF(p) 上の楕円点 p をヤコビ座標系 (x, y, z) で設定する.
- int EC_POINT_get_Jprojective_coordinates_GFp (const EC_GROUP *group, const EC_POINT *p,
BIGNUM *x, BIGNUM *y, BIGNUM *z, BN_CTX *ctx)
GF(p) 上の楕円点 p のヤコビ座標 (x, y, z) を取得する.
- int EC_POINT_set_affine_coordinates_GFp (const EC_GROUP *group, EC_POINT *p, const BIGNUM
*x, const BIGNUM *y, BN_CTX *ctx)
GF(p) 上の楕円点 p をアフィン座標系 (x, y) で設定する.
- int EC_POINT_get_affine_coordinates_GFp (const EC_GROUP *group, const EC_POINT *p, BIGNUM
*x, BIGNUM *y, BN_CTX *ctx)
GF(p) 上の楕円点 p のアフィン座標 (x, y) を取得する.
- int EC_POINT_set_compressed_coordinates_GFp (const EC_GROUP *group, EC_POINT *p, const
BIGNUM *x, int y_bit, BN_CTX *ctx)
GF(p) 上の楕円点 p に X9.62 の圧縮座標形式 (x, y_bit) を設定する.
- size_t EC_POINT_point2oct (const EC_GROUP *group, const EC_POINT *p, point_conversion_form_t
form, unsigned char *buf, size_t len, BN_CTX *ctx)
楕円点 p をオクテット列に変換する.form は点の変換形式を示す.buf は結果を格納するメモリ領域である.buf が
NULL の場合,必要なバッファ領域長を返す.len はバッファ領域の長さである.戻り値は,変換されたオクテット列の長さである (エラーの場合 0).
- int EC_POINT_oct2point (const EC_GROUP *group, EC_POINT *p,
const unsigned char *buf, size_t len, BN_CTX *ctx)
オクテット列を楕円点 p に変換する.
- 楕円点演算関数
楕円点 (EC_POINT) の演算(加法,スカラー倍)や楕円点の判定,変換を行う関数群である.
- int EC_POINT_add (const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, const EC_POINT *b,
BN_CTX *ctx)
楕円点 a と 楕円点 b を加算した点 r (=a + b) を求める.
- int EC_POINT_dbl (const EC_GROUP *group, EC_POINT *r, const EC_POINT *a, BN_CTX *ctx)
楕円点 a の 2 倍点 r (=2 * a) を求める.
- int EC_POINT_invert (const EC_GROUP *group, EC_POINT *a, BN_CTX *ctx)
楕円点 a の 逆元の点 a (=- a) を求める.
- int EC_POINT_mul (const EC_GROUP *group, EC_POINT *r, const BIGNUM *n, const EC_POINT *q,
const BIGNUM *m, BN_CTX *ctx)
楕円スカラー倍算 r = n * g + m * q を行う.g はベースポイントである.
- int EC_POINT_is_at_infinity (const EC_GROUP *group, const EC_POINT *point)
楕円点 point が無限遠点か否かを判定する.無限遠点の場合 1,そうでない場合 0 を返す.
- int EC_POINT_is_on_curve (const EC_GROUP *group, const EC_POINT *point, BN_CTX *ctx)
楕円点 point が楕円曲線上の点か否かを判定する.曲線上の点の場合 1,そうでない場合 0 を返す.
- int EC_POINT_cmp (const EC_GROUP *group, const EC_POINT *a, const EC_POINT *b, BN_CTX
*ctx)
楕円点 a と b を比較する.等しい場合 0,そうでない場合 非0 が返る.
- int EC_POINT_make_affine (const EC_GROUP *group, EC_POINT *point, BN_CTX *ctx)
楕円点 point をアフィン座標にする(Z座標 = 1).
- int EC_POINTs_make_affine (const EC_GROUP *, size_t num, EC_POINT *points[], BN_CTX
*ctx)
楕円点の配列 points の各楕円点をアフィン座標にする(Z座標 = 1).
- 形式変換関数
楕円パラメータや楕円暗号鍵 (秘密鍵,公開鍵) をエンコード/デコードする関数群である.
- int i2d_ECParameters (EC_KEY *key, unsigned char **out)
EC_KEY オブジェクトの楕円曲線パラメータを DERエンコードし,バッファ out に格納する.out が NULL
の場合,格納に必要なバイト数を返す.
- EC_KEY *d2i_ECParameters (EC_KEY **key, const unsigned char **in, long len)
バッファ in (長さ len) の内容を楕円曲線パラメータとしてデコードする.
key は, EC_KEY オブジェクトへのポインタである.
- int i2d_ECPrivateKey (EC_KEY *key, unsigned char **out)
EC_KEY の秘密鍵を DERエンコードし,バッファ out に格納する.out が NULL の場合,格納に必要なバイト数を返す.
- EC_KEY *d2i_ECPrivateKey (EC_KEY **key, const unsigned char **in, long len)
バッファ in (長さ len) の内容を秘密鍵としてデコードする.
key は, EC_KEY オブジェクトへのポインタである (NULL でもよい).
- int i2o_ECPublicKey (EC_KEY *key, unsigned char **out)
EC_KEY の公開鍵をオクテット列に変換する.out が NULL の場合,格納に必要なバイト数を返す.
- EC_KEY *o2i_ECPublicKey (EC_KEY **key, const unsigned char **in, long len)
オクテット列 (バッファ in,長さ len) を公開鍵に変換する.
key は, EC_KEY オブジェクトへのポインタである (NULL でもよい).