名称

asn_get_header, asn_put_header, asn_put_temp_header, asn_commit_header, asn_get_integer_raw, asn_get_integer, asn_put_integer, asn_get_octetstring_raw, asn_get_octetstring, asn_put_octetstring, asn_get_null_raw, asn_get_null, asn_put_null, asn_put_exception, asn_get_objid_raw, asn_get_objid, asn_put_objid, asn_get_sequence, asn_get_ipaddress_raw, asn_get_ipaddress, asn_put_ipaddress, asn_get_uint32_raw, asn_put_uint32, asn_get_counter64_raw, asn_put_counter64, asn_get_timeticks, asn_put_timeticks, asn_skip, asn_slice_oid, asn_append_oid, asn_compare_oid, asn_is_suboid, asn_oid2str_r, asn_oid2str — SNMP のための ASN.1 ライブラリ

ライブラリ

Begemot SNMP ライブラリ (libbsnmp, -lbsnmp)

書式

#include < bsnmp/asn1.h>

enum asn_err
asn_get_header( struct asn_buf *buf, u_char *type, asn_len_t *lenp);

enum asn_err
asn_put_header( struct asn_buf *buf, u_char type, asn_len_t len);

enum asn_err
asn_put_temp_header( struct asn_buf *buf, u_char type, u_char **ptr);

enum asn_err
asn_commit_header( struct asn_buf *buf, u_char *ptr);

enum asn_err
asn_get_integer_raw( struct asn_buf *buf, asn_len_t len, int32_t *res);

enum asn_err
asn_get_integer( struct asn_buf *buf, int32_t *res);

enum asn_err
asn_put_integer( struct asn_buf *buf, int32_t arg);

enum asn_err
asn_get_octetstring_raw( struct asn_buf *buf, asn_len_t len, u_char *out, u_int *outsize);

enum asn_err
asn_get_octetstring( struct asn_buf *buf, u_char *out, u_int *outsize);

enum asn_err
asn_put_octetstring( struct asn_buf *buf, const u_char *str, u_int strsize);

enum asn_err
asn_get_null_raw( struct asn_buf *buf, asn_len_t len);

enum asn_err
asn_get_null( struct asn_buf *buf);

enum asn_err
asn_put_null( struct asn_buf *buf);

enum asn_err
asn_put_exception( struct asn_buf *buf, u_int type);

enum asn_err
asn_get_objid_raw( struct asn_buf *buf, asn_len_t len, struct asn_oid *oid);

enum asn_err
asn_get_objid( struct asn_buf *buf, struct asn_oid *oid);

enum asn_err
asn_put_objid( struct asn_buf *buf, const struct asn_oid *oid);

enum asn_err
asn_get_sequence( struct asn_buf *buf, asn_len_t *lenp);

enum asn_err
asn_get_ipaddress_raw( struct asn_buf *buf, asn_len_t len, u_char *ipa);

enum asn_err
asn_get_ipaddress( struct asn_buf *buf, u_char *ipa);

enum asn_err
asn_put_ipaddress( struct asn_buf *buf, const u_char *ipa);

enum asn_err
asn_get_uint32_raw( struct asn_buf *buf, asn_len_t len, u_int32_t *res);

enum asn_err
asn_put_uint32( struct asn_buf *buf, u_char type, u_int32_t val);

enum asn_err
asn_get_counter64_raw( struct asn_buf *buf, asn_len_t len, u_int64_t *res);

enum asn_err
asn_put_counter64( struct asn_buf *buf, u_int64_t val);

enum asn_err
asn_get_timeticks( struct asn_buf *buf, u_int32_t *valp);

enum asn_err
asn_put_timeticks( struct asn_buf *buf, u_int32_t val);

enum asn_err
asn_skip( struct asn_buf *buf, asn_len_t len);

void
asn_slice_oid( struct asn_oid *dest, const struct asn_oid *src, u_int from, u_int to);

void
asn_append_oid( struct asn_oid *to, const struct asn_oid *from);

int
asn_compare_oid( const struct asn_oid *oid1, const struct asn_oid *oid2);

int
asn_is_suboid( const struct asn_oid *oid1, const struct asn_oid *oid2);

char *
asn_oid2str_r( const struct asn_oid *oid, char *buf);

char *
asn_oid2str( const struct asn_oid *oid);

解説

ASN.1 ライブラリは SNMP のための ASN.1 エンコード (コード化) を操作するルーチンを含んでいます。それは SNMP によって必要とされる ASN.1 の制限された形式だけをサポートします。ライブラリで使用される 2 つの基本構造体があります:

/* これらの制限は SMI にあります */ 
#define ASN_MAXID 0xffffffff 
#define ASN_MAXOIDLEN 128 
 
/* サブ識別子のタイプ */ 
typedef u_int32_t asn_subid_t; 
 
struct asn_oid { 
 u_int len; 
 asn_subid_t subs[ASN_MAXOIDLEN]; 
};

この構造体は、SNMP SMI で定義されている制限がある OID を表します。 len は、OID の現在の長さを保持し、 subs は、OID の要素を保持しています。

struct asn_buf { 
 union { 
  u_char *ptr; 
  const u_char *cptr; 
 } asn_u; 
 size_t asn_len; 
}; 
#define asn_cptr asn_u.cptr 
#define asn_ptr asn_u.ptr

この構造体は、ASN.1 をエンコードして、デコード (復号化) するために使用されます。それはエンコードルーチンのための出力バッファとデコードルーチンのための入力バッファを記述しています。エンコードのために、 asn_len はバッファで残っているフリー (領域) のオクテット数を保持します。最初のフリー (領域) バイトは asn_ptr によって指されます。デコードのために、 asn_len はデコードする残りのバイトの数を保持します。デコードする次のバイトは asn_cptr によって指されます。

関数の大部分はエラーコード enum asn_error を返します:

enum asn_err { 
 /* 変換は ok でした */ 
 ASN_ERR_OK = 0, 
 /* 変換は失敗して停止しました */ 
 ASN_ERR_FAILED = 1 | 0x1000, 
 /* 長さフィールドは不正で, 値はスキップしました */ 
 ASN_ERR_BADLEN = 2, 
 /* バッファを超過し, 停止しました */ 
 ASN_ERR_EOBUF = 3 | 0x1000, 
 /* 長さは ok ですが, 値は範囲外です */ 
 ASN_ERR_RANGE = 4, 
 /* 予期されないタグ, 停止しました */ 
 ASN_ERR_TAG = 5 | 0x1000, 
}; 
#define ASN_ERR_STOPPED(E) (((E) & 0x1000) != 0)

ASN_ERR_STOPPED() が真を返すなら、エラーは致命的であり、処理はエラーの時点で停止しています。

関数 asn_get_header() は、力オクテットストリームから次のヘッダを読み込みます。それは type (単一のバイトタグだけがサポートされていることに注意) よって指された変数でタグを返し、 lenp (これは符号無し 32 ビットの値に制限されます) によって指された値でデコードされた長さのフィールドを返します。この関数でのすべてのエラーは、致命的であり、処理を停止します。

関数 asn_put_header() は、ASN.1 ヘッダを書き込みます。 type は、書き込むためのタグであり、1 バイトのタグ (すなわち、タグは 0x30 以下) に制限されます。 len は、の長さであり、16 ビットに制限されます。

関数 asn_put_temp_header() と asn_commit_header() は、の長さがあらかじめ知られていないとき、例えばシーケンスに関して、ヘッダを書き込むために使用されます。 asn_put_temp_header() は与えられたタグ type と最大のサポートされた長さフィールドのための空間でヘッダを書き込み、 ptr によって指されるポインタをこの長さフィールドの始めに設定します。次に、このポインタはバッファに値を書き込む直後に asn_commit_header() に供給しなければなりません。関数は、長さを計算して、結果の長さフィールドが見積りのものより短いなら、それを適切な場所に挿入して、値をシフトします。

関数 asn_get_integer_raw() は、符号付き整数値 (32 ビット) をデコードするために使用されます。整数のヘッダは既にデコードされていることを仮定します。 len は ASN.1 ヘッダから得られた長さで、整数は res によって指された値に返されます。

関数 asn_get_integer() は、ヘッダを含む完全な 32 ビット符号付き整数をデコードします。タグが間違っているなら、 ASN_ERR_TAG が返えされます。関数 asn_put_integer() は、32 ビット符号付き整数をエンコードします。

関数 asn_get_octetstring_raw() は、ASN.1 オクテット文字列の値フィールドをデコードします。ヘッダから得られた長さは len 引数に入れられなければならなくて、 out は、オクテット文字列を受信するためのバッファを指さなければなりません。関数の入口では、 outsize はバッファのサイズを指さなければなりません。出口では、 outsize は、デコードされたオクテットの数を指します (エラーが発生しないなら、これは len と等しくなります)。関数 asn_get_octetstring() は、ヘッダに含まれているオクテット文字列をデコードします。 out は、文字列を受信するためのバッファを指さなければならなくて、 outsize は、バッファのサイズを指さなければなりません。関数の出口では outsize は、デコードされたオクテットの数を指さなければなりません。関数 asn_put_octetstring() は、(ヘッダを含んで) オクテット文字列をエンコードします。 str は、エンコードする文字列を指し、 strsize は、文字列の長さです (文字列は埋め込まれた複数の ヌル文字 (NUL) を含むかもしれません)。

関数 asn_get_null_raw() は、ヌル (null) 値をデコードします。 len は、ヘッダから得られた長さで、0 でなければなりません。関数 asn_get_null() は、ヘッダを含むヌル (null) をデコードし、関数 asn_put_null() はヌル (null) をエンコードします。

関数 asn_put_exception() は、SNMPv2 例外をエンコードするために使用されます。例外タイプは type です。

関数 asn_get_objid_raw() は、OID 値をデコードするために使用されます。 len はヘッダから得られた値の長さでなければならなくて、 oid はデコードされた OID を受信します。関数 asn_get_objid() は、(ヘッダを含んで) 完全な OID をデコードし、関数 asn_put_objid() は完全な OID をエンコードします。

関数 asn_get_sequence() は、シーケンスヘッダをデコードします。シーケンス値の長さは lenp によって指された値に格納されます。

関数 asn_get_ipaddress_raw() は、IP アドレス値をデコードします。 len はヘッダからの長さであり、4 でなければなりません。 ipa は、デコードされた IP アドレスを受信して、少なくとも 4 バイトのバッファを指さなければなりません。関数 asn_get_ipaddress() は、完全な IP アドレスを (ヘッダを含んで) デコードし、 asn_put_ipaddress() IP アドレスをエンコードします。

関数 asn_get_uint32_raw() は、符号無し 32 ビット整数値をデコードします。 len は、ヘッダからの長さで、 res は、デコードされた値を取得します。関数 asn_put_uint32() は、符号無し 32 ビット整数値をエンコードして、 type で与えられるタグをヘッダに挿入します。

関数 asn_get_counter64_raw() は、符号無し 64 ビット整数値をデコードします。 len は、ヘッダからの値の長さでなければなりません。結果の値は、 res によって指された変数に格納されます。関数 asn_put_counter64() は、完全な符号無し 64 ビット値をエンコードします。

関数 asn_get_timeticks() は、タイプ TIMETICKS の ASN.1 オブジェクトをデコードし、関数 asn_put_timeticks() は、そのようなオブジェクトをエンコードします。

関数 asn_skip() は、入力バッファの中の len バイトをスキップするために使用することができます。

関数 asn_slice_oid() は、OID を部分に分割します。それは、位置 from (最初の subid は subid 0 である) から始まり、subid to 未満までの src によって指される OID からのすべての subid を取り、 dest に新しい OID を生成します。 to が from 以下であるなら、結果の OID は、長さ 0 となります。

関数 asn_append_oid() は、結果の OID がそれほど長くないなら、OID from を OID to に追加します。最大の長さが超えるなら、結果は不定です。

関数 asn_compare_oid() は、 2 つの oid を比較して、 oid1 が、 oid2 より少ない、等しい、大きいときに、それぞれ -1, 0, +1 を返します。

関数 asn_is_suboid() は、 oid1 が oid2 の先導する部分と等しいなら、1 を返します。そうでなければ、0 を返します。

関数 asn_oid2str_r() は、 oid から印刷可能な文字列を作ります。 str によって指されたバッファは結果を保持することができるくらい大きくなければなりません。定数 ASN_OIDSTRLEN は、この関数で生成される最大の文字列 (後続するヌル文字を含んで) の長さになるように定義されます。関数 asn_oid2str() は、各呼び出しによって上書きされるプライベートバッファに oid からの印刷可能な文字列を作ります。

診断

エラーが関数のどれかで発生するとき、グローバルなポインタ

extern void (*asn_error)(const struct asn_buf *, const char *, ...);

で指された関数は、現在のバッファ (これは NULL) であるかもしれません) と printf(3) スタイルの書式文字列で呼び出されます。‘ASN.1:’で始まり、エラーメッセージとオプションのバッファのダンプが続くメッセージを印刷するライブラリにはデフォルトのエラーハンドラがあります:

関連項目

gensnmptree(1), bsnmpd(1), bsnmpagent(3), bsnmpclient(3), bsnmplib(3)

規格

この実装は、適切な IETF RFC と ITU-T 勧告に適合しています。

作者

Hartmut Brandt <harti@FreeBSD.org>