/contrib/bsnmp/lib/asn1.3

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 492 lines · 490 code · 2 blank · 0 comment · 0 complexity · f1c02913bd43e21f7e4d2f9be552addf MD5 · raw file

  1. .\"
  2. .\" Copyright (c) 2004-2005
  3. .\" Hartmut Brandt.
  4. .\" All rights reserved.
  5. .\" Copyright (c) 2001-2003
  6. .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
  7. .\" All rights reserved.
  8. .\"
  9. .\" Author: Harti Brandt <harti@FreeBSD.org>
  10. .\"
  11. .\" Redistribution and use in source and binary forms, with or without
  12. .\" modification, are permitted provided that the following conditions
  13. .\" are met:
  14. .\" 1. Redistributions of source code must retain the above copyright
  15. .\" notice, this list of conditions and the following disclaimer.
  16. .\" 2. Redistributions in binary form must reproduce the above copyright
  17. .\" notice, this list of conditions and the following disclaimer in the
  18. .\" documentation and/or other materials provided with the distribution.
  19. .\"
  20. .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23. .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  24. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30. .\" SUCH DAMAGE.
  31. .\"
  32. .\" $Begemot: bsnmp/lib/asn1.3,v 1.9 2005/10/04 08:46:49 brandt_h Exp $
  33. .\"
  34. .Dd October 4, 2005
  35. .Dt ASN1 3
  36. .Os
  37. .Sh NAME
  38. .Nm asn_get_header ,
  39. .Nm asn_put_header ,
  40. .Nm asn_put_temp_header ,
  41. .Nm asn_commit_header ,
  42. .Nm asn_get_integer_raw ,
  43. .Nm asn_get_integer ,
  44. .Nm asn_put_integer ,
  45. .Nm asn_get_octetstring_raw ,
  46. .Nm asn_get_octetstring ,
  47. .Nm asn_put_octetstring ,
  48. .Nm asn_get_null_raw ,
  49. .Nm asn_get_null ,
  50. .Nm asn_put_null ,
  51. .Nm asn_put_exception ,
  52. .Nm asn_get_objid_raw ,
  53. .Nm asn_get_objid ,
  54. .Nm asn_put_objid ,
  55. .Nm asn_get_sequence ,
  56. .Nm asn_get_ipaddress_raw ,
  57. .Nm asn_get_ipaddress ,
  58. .Nm asn_put_ipaddress ,
  59. .Nm asn_get_uint32_raw ,
  60. .Nm asn_put_uint32 ,
  61. .Nm asn_get_counter64_raw ,
  62. .Nm asn_put_counter64 ,
  63. .Nm asn_get_timeticks ,
  64. .Nm asn_put_timeticks ,
  65. .Nm asn_skip ,
  66. .Nm asn_slice_oid ,
  67. .Nm asn_append_oid ,
  68. .Nm asn_compare_oid ,
  69. .Nm asn_is_suboid ,
  70. .Nm asn_oid2str_r ,
  71. .Nm asn_oid2str
  72. .Nd "ASN.1 library for SNMP"
  73. .Sh LIBRARY
  74. Begemot SNMP library
  75. .Pq libbsnmp, -lbsnmp
  76. .Sh SYNOPSIS
  77. .In bsnmp/asn1.h
  78. .Ft enum asn_err
  79. .Fn asn_get_header "struct asn_buf *buf" "u_char *type" "asn_len_t *lenp"
  80. .Ft enum asn_err
  81. .Fn asn_put_header "struct asn_buf *buf" "u_char type" "asn_len_t len"
  82. .Ft enum asn_err
  83. .Fn asn_put_temp_header "struct asn_buf *buf" "u_char type" "u_char **ptr"
  84. .Ft enum asn_err
  85. .Fn asn_commit_header "struct asn_buf *buf" "u_char *ptr"
  86. .Ft enum asn_err
  87. .Fn asn_get_integer_raw "struct asn_buf *buf" "asn_len_t len" "int32_t *res"
  88. .Ft enum asn_err
  89. .Fn asn_get_integer "struct asn_buf *buf" "int32_t *res"
  90. .Ft enum asn_err
  91. .Fn asn_put_integer "struct asn_buf *buf" "int32_t arg"
  92. .Ft enum asn_err
  93. .Fn asn_get_octetstring_raw "struct asn_buf *buf" "asn_len_t len" "u_char *out" "u_int *outsize"
  94. .Ft enum asn_err
  95. .Fn asn_get_octetstring "struct asn_buf *buf" "u_char *out" "u_int *outsize"
  96. .Ft enum asn_err
  97. .Fn asn_put_octetstring "struct asn_buf *buf" "const u_char *str" "u_int strsize"
  98. .Ft enum asn_err
  99. .Fn asn_get_null_raw "struct asn_buf *buf" "asn_len_t len"
  100. .Ft enum asn_err
  101. .Fn asn_get_null "struct asn_buf *buf"
  102. .Ft enum asn_err
  103. .Fn asn_put_null "struct asn_buf *buf"
  104. .Ft enum asn_err
  105. .Fn asn_put_exception "struct asn_buf *buf" "u_int type"
  106. .Ft enum asn_err
  107. .Fn asn_get_objid_raw "struct asn_buf *buf" "asn_len_t len" "struct asn_oid *oid"
  108. .Ft enum asn_err
  109. .Fn asn_get_objid "struct asn_buf *buf" "struct asn_oid *oid"
  110. .Ft enum asn_err
  111. .Fn asn_put_objid "struct asn_buf *buf" "const struct asn_oid *oid"
  112. .Ft enum asn_err
  113. .Fn asn_get_sequence "struct asn_buf *buf" "asn_len_t *lenp"
  114. .Ft enum asn_err
  115. .Fn asn_get_ipaddress_raw "struct asn_buf *buf" "asn_len_t len" "u_char *ipa"
  116. .Ft enum asn_err
  117. .Fn asn_get_ipaddress "struct asn_buf *buf" "u_char *ipa"
  118. .Ft enum asn_err
  119. .Fn asn_put_ipaddress "struct asn_buf *buf" "const u_char *ipa"
  120. .Ft enum asn_err
  121. .Fn asn_get_uint32_raw "struct asn_buf *buf" "asn_len_t len" "u_int32_t *res"
  122. .Ft enum asn_err
  123. .Fn asn_put_uint32 "struct asn_buf *buf" "u_char type" "u_int32_t val"
  124. .Ft enum asn_err
  125. .Fn asn_get_counter64_raw "struct asn_buf *buf" "asn_len_t len" "u_int64_t *res"
  126. .Ft enum asn_err
  127. .Fn asn_put_counter64 "struct asn_buf *buf" "u_int64_t val"
  128. .Ft enum asn_err
  129. .Fn asn_get_timeticks "struct asn_buf *buf" "u_int32_t *valp"
  130. .Ft enum asn_err
  131. .Fn asn_put_timeticks "struct asn_buf *buf" "u_int32_t val"
  132. .Ft enum asn_err
  133. .Fn asn_skip "struct asn_buf *buf" "asn_len_t len"
  134. .Ft void
  135. .Fn asn_slice_oid "struct asn_oid *dest" "const struct asn_oid *src" "u_int from" "u_int to"
  136. .Ft void
  137. .Fn asn_append_oid "struct asn_oid *to" "const struct asn_oid *from"
  138. .Ft int
  139. .Fn asn_compare_oid "const struct asn_oid *oid1" "const struct asn_oid *oid2"
  140. .Ft int
  141. .Fn asn_is_suboid "const struct asn_oid *oid1" "const struct asn_oid *oid2"
  142. .Ft char *
  143. .Fn asn_oid2str_r "const struct asn_oid *oid" "char *buf"
  144. .Ft char *
  145. .Fn asn_oid2str "const struct asn_oid *oid"
  146. .Sh DESCRIPTION
  147. The ASN.1 library contains routines to handle ASN.1 encoding for SNMP.
  148. It supports only the restricted form of ASN.1 as required by SNMP.
  149. There are two basic structures used throughout the library:
  150. .Bd -literal -offset indent
  151. /* these restrictions are in the SMI */
  152. #define ASN_MAXID 0xffffffff
  153. #define ASN_MAXOIDLEN 128
  154. /* type of subidentifiers */
  155. typedef u_int32_t asn_subid_t;
  156. struct asn_oid {
  157. u_int len;
  158. asn_subid_t subs[ASN_MAXOIDLEN];
  159. };
  160. .Ed
  161. .Pp
  162. This structure represents an OID with the restrictions defined in the SNMP
  163. SMI.
  164. .Fa len
  165. holds the current length of the OID and
  166. .Fa subs
  167. holds the elements of the OID.
  168. .Bd -literal -offset indent
  169. struct asn_buf {
  170. union {
  171. u_char *ptr;
  172. const u_char *cptr;
  173. } asn_u;
  174. size_t asn_len;
  175. };
  176. #define asn_cptr asn_u.cptr
  177. #define asn_ptr asn_u.ptr
  178. .Ed
  179. .Pp
  180. This structure is used to encode and decode ASN.1.
  181. It describes the output
  182. buffer for encoding routines and the input buffer for decoding routines.
  183. For encoding
  184. .Fa asn_len
  185. holds the number of remaining free octets in the buffer.
  186. The first free byte is pointed to by
  187. .Fa asn_ptr .
  188. For decoding
  189. .Fa asn_len
  190. holds the number of remaining bytes to decode.
  191. The next byte to decode is pointed to by
  192. .Fa asn_cptr .
  193. .Pp
  194. Most of the functions return an error code
  195. .Fa "enum asn_error" :
  196. .Bd -literal -offset indent
  197. enum asn_err {
  198. /* conversion was ok */
  199. ASN_ERR_OK = 0,
  200. /* conversion failed and stopped */
  201. ASN_ERR_FAILED = 1 | 0x1000,
  202. /* length field bad, value skipped */
  203. ASN_ERR_BADLEN = 2,
  204. /* out of buffer, stopped */
  205. ASN_ERR_EOBUF = 3 | 0x1000,
  206. /* length ok, but value is out of range */
  207. ASN_ERR_RANGE = 4,
  208. /* not the expected tag, stopped */
  209. ASN_ERR_TAG = 5 | 0x1000,
  210. };
  211. #define ASN_ERR_STOPPED(E) (((E) & 0x1000) != 0)
  212. .Ed
  213. .Pp
  214. If
  215. .Fn ASN_ERR_STOPPED
  216. returns true, the error was fatal and processing has stopped at the point
  217. of error.
  218. .Pp
  219. The function
  220. .Fn asn_get_header
  221. reads the next header from the input octet stream.
  222. It returns the tag in the variable pointed to by
  223. .Fa type
  224. (note that only single byte tags are supported) and the decoded length field
  225. in the value pointed to by
  226. .Fa lenp
  227. (this is restricted to a unsigned 32-bit value).
  228. All errors in this function are fatal and stop processing.
  229. .Pp
  230. The function
  231. .Fn asn_put_header
  232. writes an ASN.1 header.
  233. .Fa type
  234. is the tag to write and is restricted to one byte tags (i.e., tags
  235. lesser or equal than 0x30).
  236. .Fa len
  237. is the length of the value and is restricted to 16-bit.
  238. .Pp
  239. The functions
  240. .Fn asn_put_temp_header
  241. and
  242. .Fn asn_commit_header
  243. are used to write a header when the length of the value is not known in
  244. advance, for example, for sequences.
  245. .Fn asn_put_temp_header
  246. writes a header with the given tag
  247. .Fa type
  248. and space for the maximum supported length field and sets the pointer pointed
  249. to by
  250. .Fa ptr
  251. to the begin of this length field.
  252. This pointer must then be fed into
  253. .Fn asn_commit_header
  254. directly after writing the value to the buffer.
  255. The function will compute the
  256. length, insert it into the right place and shift the value if the resulting
  257. length field is shorter than the estimated one.
  258. .Pp
  259. The function
  260. .Fn asn_get_integer_raw
  261. is used to decode a signed integer value (32-bit).
  262. It assumes, that the
  263. header of the integer has been decoded already.
  264. .Fa len
  265. is the length obtained from the ASN.1 header and the integer will be returned
  266. in the value pointed to by
  267. .Fa res .
  268. .Pp
  269. The function
  270. .Fn asn_get_integer
  271. decodes a complete 32-bit signed integer including the header.
  272. If the tag is wrong
  273. .Li ASN_ERR_TAG
  274. is returned.
  275. The function
  276. .Fn asn_put_integer
  277. encodes a 32-bit signed integer.
  278. .Pp
  279. The function
  280. .Fn asn_get_octetstring_raw
  281. decodes the value field of an ASN.1 octet string.
  282. The length obtained from the header must be fed into the
  283. .Fa len
  284. argument and
  285. .Fa out
  286. must point to a buffer to receive the octet string.
  287. On entry to the function
  288. .Fa outsize
  289. must point to the size of the buffer.
  290. On exit
  291. .Fa outsize
  292. will point to the number of octets decoded (if no error occurs this will be
  293. equal to
  294. .Fa len ).
  295. The function
  296. .Fn asn_get_octetstring
  297. decodes an octetstring including the header.
  298. .Fa out
  299. must point to a buffer to receive the string,
  300. .Fa outsize
  301. must point to the size of the buffer.
  302. On exit of the function
  303. .Fa outsize
  304. will point to the number of octets decoded.
  305. The function
  306. .Fn asn_put_octetstring
  307. encodes an octetstring (including the header).
  308. .Fa str
  309. points to the string to encode and
  310. .Fa strsize
  311. is the length of the string (the string may contain embedded
  312. .Li NUL Ns s).
  313. .Pp
  314. The function
  315. .Fn asn_get_null_raw
  316. decodes a null value.
  317. .Fa len
  318. is the length obtained from the header and must be 0.
  319. The function
  320. .Fn asn_get_null
  321. decodes a null including the header and the function
  322. .Fn asn_put_null
  323. encodes a null.
  324. .Pp
  325. The function
  326. .Fn asn_put_exception
  327. is used to encode an SNMPv2 exception.
  328. The exception type is
  329. .Fa type .
  330. .Pp
  331. The function
  332. .Fn asn_get_objid_raw
  333. is used to decode an OID value.
  334. .Fa len
  335. must be the value length obtained from the header and
  336. .Fa oid
  337. will receive the decoded OID.
  338. The function
  339. .Fn asn_get_objid
  340. decodes a complete OID (including the header) and the function
  341. .Fn asn_put_objid
  342. encodes a complete OID.
  343. .Pp
  344. The function
  345. .Fn asn_get_sequence
  346. decodes a sequence header.
  347. The length of the sequence value will be stored in the value pointed to by
  348. .Fa lenp .
  349. .Pp
  350. The function
  351. .Fn asn_get_ipaddress_raw
  352. decodes an IP address value.
  353. .Fa len
  354. is the length from the header and must be 4.
  355. .Fa ipa
  356. will receive the decoded IP address and must point to a buffer of at least
  357. four bytes.
  358. The function
  359. .Fn asn_get_ipaddress
  360. decodes a complete IP address (including the header) and
  361. .Fn asn_put_ipaddress
  362. encodes an IP address.
  363. .Pp
  364. The function
  365. .Fn asn_get_uint32_raw
  366. decodes an unsigned 32-bit integer value.
  367. .Fa len
  368. is the length from the header and
  369. .Fa res
  370. will get the decoded value.
  371. The function
  372. .Fn asn_put_uint32
  373. encodes an unsigned 32-bit integer value and inserts the tag given in
  374. .Fa type
  375. into the header.
  376. .Pp
  377. The function
  378. .Fn asn_get_counter64_raw
  379. decodes an unsigned 64-bit integer value.
  380. .Fa len
  381. must be the value length from the header.
  382. The resulting value is stored into the variable pointed to by
  383. .Fa res .
  384. The function
  385. .Fn asn_put_counter64
  386. encodes a complete unsigned 64-bit value.
  387. .Pp
  388. The function
  389. .Fn asn_get_timeticks
  390. decodes an ASN.1 object of type
  391. .Li TIMETICKS
  392. and the function
  393. .Fn asn_put_timeticks
  394. encodes such an object.
  395. .Pp
  396. The function
  397. .Fn asn_skip
  398. can be used to skip
  399. .Fa len
  400. bytes in the input buffer.
  401. .Pp
  402. The function
  403. .Fn asn_slice_oid
  404. splits a part out from an OID.
  405. It takes all the subids from the OID pointed to by
  406. .Fa src
  407. starting with the subid at position
  408. .Fa from
  409. (the first subid being subid 0) up to, but not including, subid
  410. .Fa to
  411. and generates a new OID in
  412. .Fa dest .
  413. If
  414. .Fa to
  415. is less or equal to
  416. .Fa from
  417. the resulting OID will have a length of zero.
  418. .Pp
  419. The function
  420. .Fn asn_append_oid
  421. appends the OID
  422. .Fa from
  423. to the OID
  424. .Fa to
  425. given that the resulting OID is not too long.
  426. If the maximum length is exceeded the result is undefined.
  427. .Pp
  428. The function
  429. .Fn asn_compare_oid
  430. compares two oids and returns the values
  431. .Li -1 ,
  432. .Li 0 or
  433. .Li +1
  434. when
  435. .Fa oid1
  436. is lesser than, equal, or larger than
  437. .Fa oid2
  438. resp.
  439. .Pp
  440. The function
  441. .Fn asn_is_suboid
  442. returns 1 if
  443. .Fa oid1
  444. is equal to the leading part of
  445. .Fa oid2 .
  446. It returns 0 otherwise.
  447. .Pp
  448. The function
  449. .Fn asn_oid2str_r
  450. makes a printable string from
  451. .Fa oid .
  452. The buffer pointed to by
  453. .Fa str
  454. must be large enough to hold the result.
  455. The constant
  456. .Li ASN_OIDSTRLEN
  457. is defined to be the length of the maximum string generated by this function
  458. (including the trailing NUL).
  459. The function
  460. .Fn asn_oid2str
  461. makes a printable string from
  462. .Fa oid
  463. into a private buffer that is overwritten by each call.
  464. .Sh DIAGNOSTICS
  465. When an error occurs in any of the function the function pointed to
  466. by the global pointer
  467. .Bd -literal -offset indent
  468. extern void (*asn_error)(const struct asn_buf *, const char *, ...);
  469. .Ed
  470. .Pp
  471. is called with the current buffer (this may be
  472. .Li NULL )
  473. and a
  474. .Xr printf 3
  475. style format string.
  476. There is a default error handler in the library that prints a message
  477. starting with
  478. .Sq ASN.1:
  479. followed by the error message and an optional dump of the buffer.
  480. .Sh SEE ALSO
  481. .Xr gensnmptree 1 ,
  482. .Xr bsnmpd 1 ,
  483. .Xr bsnmpagent 3 ,
  484. .Xr bsnmpclient 3 ,
  485. .Xr bsnmplib 3
  486. .Sh STANDARDS
  487. This implementation conforms to the applicable IETF RFCs and ITU-T
  488. recommendations.
  489. .Sh AUTHORS
  490. .An Hartmut Brandt Aq harti@FreeBSD.org