| BSNMPLIB(3) | FreeBSD Library Functions Manual | BSNMPLIB(3) |
名称
snmp_value_free, snmp_value_parse, snmp_value_copy, snmp_pdu_free, snmp_pdu_decode, snmp_pdu_encode, snmp_pdu_decode_header, snmp_pdu_decode_scoped, snmp_pdu_decode_secmode, snmp_pdu_init_secparams, snmp_pdu_dump, snmp_passwd_to_keys, snmp_get_local_keys, snmp_calc_keychange, TRUTH_MK, TRUTH_GET, TRUTH_OK — SNMP デコード (復号化) とエンコード (コード化) ライブラリライブラリ
Begemot SNMP ライブラリ (libbsnmp, -lbsnmp)書式
#include < bsnmp/asn1.h>#include < bsnmp/snmp.h>
void
snmp_value_free( struct snmp_value *value);
int
snmp_value_parse( const char *buf, enum snmp_syntax, union snmp_values *value);
int
snmp_value_copy( struct snmp_value *to, const struct snmp_value *from);
void
snmp_pdu_free( struct snmp_pdu *value);
enum snmp_code
snmp_pdu_decode( struct asn_buf *buf, struct snmp_pdu *pdu, int32_t *ip);
enum snmp_code
snmp_pdu_encode( struct snmp_pdu *pdu, struct asn_buf *buf);
enum snmp_code
snmp_pdu_decode_header( struct snmp_pdu *pdu, struct asn_buf *buf);
enum snmp_code
snmp_pdu_decode_scoped( struct asn_buf *buf, struct snmp_pdu *pdu, int32_t *ip);
enum snmp_code
snmp_pdu_decode_secmode( struct asn_buf *buf, struct snmp_pdu *pdu);
void
snmp_pdu_init_secparams( struct snmp_pdu *pdu);
void
snmp_pdu_dump( const struct snmp_pdu *pdu);
enum snmp_code
snmp_passwd_to_keys( struct snmp_user *user, char *passwd);
enum snmp_code
snmp_get_local_keys( struct snmp_user *user, uint8_t *eid, uint32_t elen);
enum snmp_code
snmp_calc_keychange( struct snmp_user *user, uint8_t *keychange);
int
TRUTH_MK( F);
int
TRUTH_GET( T);
int
TRUTH_OK( T);
解説
SNMP ライブラリは、SNMP バージョン 1、2 と 3 PDU を操作するルーチンを含んでいます。ライブラリの至るところで使用されるいくつかの基本の構造体があります:
struct snmp_value {
struct asn_oid var;
enum snmp_syntax syntax;
union snmp_values {
int32_t integer;/* 同様に integer32 */
struct {
u_int len;
u_char *octets;
} octetstring;
struct asn_oid oid;
u_char ipaddress[4];
uint32_t uint32; /* 同様に gauge32, counter32,
unsigned32, timeticks */
uint64_t counter64;
} v;
};
この構造体は、SNMP PDU から 1 つの変数のバインドを表します。フィールド var は、バインドされた変数の ASN.1 です。 syntax は、値の構文コードか SNMPv2 のための例外コードのどちらかを含み、次の 1 つです:
enum snmp_syntax {
SNMP_SYNTAX_NULL = 0,
SNMP_SYNTAX_INTEGER, /* == INTEGER32 */
SNMP_SYNTAX_OCTETSTRING,
SNMP_SYNTAX_OID,
SNMP_SYNTAX_IPADDRESS,
SNMP_SYNTAX_COUNTER,
SNMP_SYNTAX_GAUGE, /* == UNSIGNED32 */
SNMP_SYNTAX_TIMETICKS,
/* v2 additions */
SNMP_SYNTAX_COUNTER64,
/* exceptions */
SNMP_SYNTAX_NOSUCHOBJECT,
SNMP_SYNTAX_NOSUCHINSTANCE,
SNMP_SYNTAX_ENDOFMIBVIEW,
};
フィールド v は、 syntax に依存する実際の値を保持します。 syntax が SNMP_SYNTAX_OCTETSTRING であり、 v.octetstring.len が 0 でなければ、 v.octetstring.octets は、 malloc(3) によって割り付けられた文字列を指すことに注意してください。
#define SNMP_ENGINE_ID_SIZ 32
struct snmp_engine {
uint8_t engine_id[SNMP_ENGINE_ID_SIZ];
uint32_t engine_len;
int32_t engine_boots;
int32_t engine_time;
int32_t max_msg_size;
};
この構造体は、RFC 3411 に記述された SNMP Management Architecture (管理アーキテクチャ) によって指定される SNMP エンジンを表現しています。
#define SNMP_ADM_STR32_SIZ (32 + 1)
#define SNMP_AUTH_KEY_SIZ 40
#define SNMP_PRIV_KEY_SIZ 32
enum snmp_usm_level {
SNMP_noAuthNoPriv = 1,
SNMP_authNoPriv = 2,
SNMP_authPriv = 3
};
struct snmp_user {
char sec_name[SNMP_ADM_STR32_SIZ];
enum snmp_authentication auth_proto;
enum snmp_privacy priv_proto;
uint8_t auth_key[SNMP_AUTH_KEY_SIZ];
uint8_t priv_key[SNMP_PRIV_KEY_SIZ];
};
この構造体は、RFC 3414 に記述された User-based Security Model (USM) (ユーザベースセキュリティモデル) によって指定される SNMPv3 ユーザを表現しています。フィールド sec_name は、セキュリティユーザ名を含む人間に読み込み可能な文字列です。 auth_proto は、ユーザによって使用中の認証プロトコルの ID を含んでいて、次の 1 つです:
enum snmp_authentication {
SNMP_AUTH_NOAUTH = 0,
SNMP_AUTH_HMAC_MD5,
SNMP_AUTH_HMAC_SHA
};
priv_proto は、ユーザによって使用中のプライバシプロトコルの ID を含んでいて、次の 1 つです:
enum snmp_privacy {
SNMP_PRIV_NOPRIV = 0,
SNMP_PRIV_DES = 1,
SNMP_PRIV_AES
};
auth_key と priv_key は、ユーザのための認証とプライバシキーを含んでいます。
#define SNMP_COMMUNITY_MAXLEN 128
#define SNMP_MAX_BINDINGS 100
#define SNMP_CONTEXT_NAME_SIZ (32 + 1)
#define SNMP_TIME_WINDOW 150
#define SNMP_USM_AUTH_SIZE 12
#define SNMP_USM_PRIV_SIZE 8
#define SNMP_MSG_AUTH_FLAG 0x1
#define SNMP_MSG_PRIV_FLAG 0x2
#define SNMP_MSG_REPORT_FLAG 0x4
#define SNMP_MPM_SNMP_V1 0
#define SNMP_MPM_SNMP_V2c 1
#define SNMP_MPM_SNMP_V3 3
struct snmp_pdu {
char community[SNMP_COMMUNITY_MAXLEN + 1];
enum snmp_version version;
u_int type;
/* SNMPv3 PDU ヘッダフィールド */
int32_t identifier;
uint8_t flags;
int32_t security_model;
struct snmp_engine engine;
/* 関連 USM ユーザパラメータ */
struct snmp_user user;
uint8_t msg_digest[SNMP_USM_AUTH_SIZE];
uint8_t msg_salt[SNMP_USM_PRIV_SIZE];
/* View-based Access Model */
uint32_t context_engine_len;
uint8_t context_engine[SNMP_ENGINE_ID_SIZ];
char context_name[SNMP_CONTEXT_NAME_SIZ];
/* トラップのみ */
struct asn_oid enterprise;
u_char agent_addr[4];
int32_t generic_trap;
int32_t specific_trap;
uint32_t time_stamp;
/* その他 */
int32_t request_id;
int32_t error_status;
int32_t error_index;
/* エンコードのための修理 */
size_t outer_len;
size_t scoped_len;
u_char *outer_ptr;
u_char *digest_ptr;
u_char *encrypted_ptr;
u_char *scoped_ptr;
u_char *pdu_ptr;
u_char *vars_ptr;
struct snmp_value bindings[SNMP_MAX_BINDINGS];
u_int nbindings;
};
この構造体は、デコードされた SNMP PDU を含んでいます。 version は、次のうちの 1 つで、
enum snmp_version {
SNMP_Verr = 0,
SNMP_V1 = 1,
SNMP_V2c,
SNMP_V3
};
そして、 type は、PDU のタイプです。 security_model は、SNMPv3 PDU のために使用されるセキュリティモデルです。現在、唯一サポートされている値は、3 (User-based Security Model) です。 any、unknown、SNMPv1 と SNMPv2c セキュリティモデルのための追加の値も列挙されます。
enum snmp_secmodel {
SNMP_SECMODEL_ANY = 0,
SNMP_SECMODEL_SNMPv1 = 1,
SNMP_SECMODEL_SNMPv2c = 2,
SNMP_SECMODEL_USM = 3,
SNMP_SECMODEL_UNKNOWN
};
関数 snmp_value_free() は、SNMP 値のすべての動的に割り付けられた内容を解放するために使用されます。それは、 value 自体によって指された構造体を解放しません。
関数 snmp_value_parse() は、バイナリ形式に SNMP 値の ASCII 表現を解析します。この関数は、 bsnmpd(1) の設定ファイルを読み込む者によって主に使用されます。
関数 snmp_value_copy() は、 from によって指された値を to によって指された構造体にディープコピー (deep copy) を行います。訳注: deep copy の意味不明。それは、 to が初期化されず、前の内容を上書きすると仮定します。それは、 to によって指された構造体それ自体を割り付けません。
関数 snmp_pdu_free() は、PDU のすべての動的に割り付けられた構成要素を解放します。それは、 pdu によって指された構造体それ自体を解放しません。
関数 snmp_pdu_decode() は、 buf によって指された PDU をデコードして、結果を pdu に格納します。エラーが変数バインドで発生するなら、このバインドの (1 を底とする) インデックスは、 ip によって指された変数に格納されます。
関数 snmp_pdu_encode() は、PDU pdu をバッファのオクテット文字列にエンコードし、認証とプライバシが使用されているなら、メッセージダイジェストを計算して、バッファ buf の PDU データを暗号化します。
関数 snmp_pdu_decode_header() は、 buf によって指された PDU のヘッダをデコードします。エンコード化された PDU の内容は、バッファに残っています。
関数 snmp_pdu_decode_scoped() は、 buf によって指された範囲化された (scoped) PDU をデコードします。
関数 snmp_pdu_decode_secmode() は、PDU (存在しているなら) に含まれている認証パラメータを検証し、 PDU が暗号化されているなら、 buf によって指された PDU の内容を (暗号を) 復号化します。成功すれば、プレーンテキスト範囲化された (scoped) PDU は、バッファに格納されます。
関数 snmp_pdu_init_secparams() は、 pdu によって指された PDU が、暗号化されるか、または復号化される前に使用される、プライバシプロトコルのための初期化ベクトルを計算します。
関数 snmp_pdu_dump() は、 snmp_printf() を呼び出すことによって、人間に解読可能な形式で PDU をダンプします。
関数 snmp_passwd_to_keys() は、プレーンテキストの人間に読み込み可能なパスワードの文字列に対応するバイナリのプライベート認証キーを計算します。計算されたキーは、 user の auth_key フィールドに置かれます。
関数 snmp_get_local_keys() は、指定された SNMPv3 エンジンのためにローカル化された認証とプライバシキーを計算します。計算されたキーは、 user の auth_key と priv_key フィールドに置かれます。
関数 snmp_calc_keychange() は、古いバイナリのローカル化されたキーと新しいバイナリのローカル化されたキーの内容に基づくバイナリキーの変更オクテット文字列を計算します。結果は、 keychange によって指されるバッファに置かれ、彼/彼女のパスワードまたはローカル化されたキーを変更したい SNMPv3 ユーザによって使用されます。
関数 TRUTH_MK() は、C 真理値 (0 か非 0) を取って、SNMP 真理値 (2 か 1) を作ります。関数 TRUTH_GET() は、SNMP 真理値を取って、C 真理値 (0 か 1) を作ります。関数 TRUTH_OK() は、引数が正当な SNMP 真理値であるかどうかをチェックします。
診断
エラーが関数のいずれかで発生するとき、関数は、 printf(3) スタイルの書式文字列でグローバルポインタ
extern void (*snmp_error)(const char *, ...);
によって指されます。‘SNMP:’で始まるメッセージに続くエラーメッセージを標準エラーに印刷 (表示) するライブラリにデフォルトのエラーハンドラがあります。
次によって指された関数は、
extern void (*snmp_printf)(const char *, ...);
snmp_pdu_dump() 関数によって呼び出されます。デフォルトのハンドラは、 printf(3) です。
エラー
snmp_pdu_decode() は、次のリターンコードの 1 つを返します:- [ SNMP_CODE_OK]
- 成功。
- [ SNMP_CODE_FAILED]
- ASN.1 コーディングは、間違っています。
- [ SNMP_CODE_BADLEN]
- 変数バインド値は、間違った長さのフィールドがあります。
- [ SNMP_CODE_OORANGE]
- 変数バインド値は、許された範囲外です。
- [ SNMP_CODE_BADVERS]
- PDU は、サポートされないバージョンのものです。
- [ SNMP_CODE_BADENQ]
- サポートされないタグの ASN.1 値があります。
- [ SNMP_CODE_BADSECLEVEL]
- PDU に含まれる要求された securityLevel は、サポートされていません。
- [ SNMP_CODE_BADDIGEST]
- PDU で受信された PDU 認証パラメータは、計算されたメッセージダイジェストにマッチしませんでした。
- [ SNMP_CODE_EDECRYPT]
- PDU を復号化しようとしている間にエラーが起こりました。
snmp_pdu_encode() は、次のリターンコードの 1 つを返します:
- [ SNMP_CODE_OK]
- 成功。
- [ SNMP_CODE_FAILED]
- エンコードの失敗。
警告
SNMPv3 メッセージダイジェスト、暗号化と復号化、とキールーチンは、 crypto(3) から暗号化の関数を使用しています。ライブラリは、 crypto(3) ライブラリへの参照なしで状況に応じて構築されるかもしれません。その場合、メッセージダイジェストのないプレーンテキスト SNMPv3 PDU だけは、正しく処理されるかもしれません。規格
この実装は、適切な IETF RFC と ITU-T 推薦に適合しています。作者
Begemot SNMP ライブラリは、最初は <harti@FreeBSD.org>によって書かれました。<syrinx@FreeBSD.org>は、SNMPv3 メッセージ処理と User-Based Security モデルメッセージ認証とプライバシのサポートを追加しました。
| December 19, 2010 | FreeBSD |