doc/libtasn1.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- This manual is for GNU Libtasn1
   4 (version 4.12, 4 April 2016),
   5 which is a library for Abstract Syntax Notation One (ASN.1) and
   6 Distinguished Encoding Rules (DER) manipulation.
   7
   8 Copyright (C) 2001-2015 Free Software Foundation, Inc.
   9
  10 Permission is granted to copy, distribute and/or modify this document
  11 under the terms of the GNU Free Documentation License, Version 1.3 or
  12 any later version published by the Free Software Foundation; with no
  13 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
  14 copy of the license is included in the section entitled "GNU Free
  15 Documentation License". -->
  16 <!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
  17 <head>
  18 <title>GNU Libtasn1 4.12</title>
  19
  20 <meta name="description" content="GNU Libtasn1 4.12">
  21 <meta name="keywords" content="GNU Libtasn1 4.12">
  22 <meta name="resource-type" content="document">
  23 <meta name="distribution" content="global">
  24 <meta name="Generator" content="makeinfo">
  25 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  26 <link href="#Top" rel="start" title="Top">
  27 <link href="#Concept-Index" rel="index" title="Concept Index">
  28 <link href="#SEC_Contents" rel="contents" title="Table of Contents">
  29 <link href="dir.html#Top" rel="up" title="(dir)">
  30 <style type="text/css">
  31 <!--
  32 a.summary-letter {text-decoration: none}
  33 blockquote.indentedblock {margin-right: 0em}
  34 blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
  35 blockquote.smallquotation {font-size: smaller}
  36 div.display {margin-left: 3.2em}
  37 div.example {margin-left: 3.2em}
  38 div.lisp {margin-left: 3.2em}
  39 div.smalldisplay {margin-left: 3.2em}
  40 div.smallexample {margin-left: 3.2em}
  41 div.smalllisp {margin-left: 3.2em}
  42 kbd {font-style: oblique}
  43 pre.display {font-family: inherit}
  44 pre.format {font-family: inherit}
  45 pre.menu-comment {font-family: serif}
  46 pre.menu-preformatted {font-family: serif}
  47 pre.smalldisplay {font-family: inherit; font-size: smaller}
  48 pre.smallexample {font-size: smaller}
  49 pre.smallformat {font-family: inherit; font-size: smaller}
  50 pre.smalllisp {font-size: smaller}
  51 span.nolinebreak {white-space: nowrap}
  52 span.roman {font-family: initial; font-weight: normal}
  53 span.sansserif {font-family: sans-serif; font-weight: normal}
  54 ul.no-bullet {list-style: none}
  55 body {
  56         margin: 2%;
  57         padding: 0 5%;
  58         background: #ffffff;
  59 }
  60 h1,h2,h3,h4,h5 {
  61     font-weight: bold;
  62     padding: 5px 5px 5px 5px;
  63     background-color: #c2e0ff;
  64     color: #336699;
  65 }
  66 h1 {
  67     padding: 2em 2em 2em 5%;
  68     color: white;
  69     background: #336699;
  70     text-align: center;
  71     letter-spacing: 3px;
  72 }
  73 h2 { text-decoration: underline; }
  74 pre {
  75   margin: 0 5%;
  76   padding: 0.5em;
  77 }
  78 pre.example {
  79   border: solid 1px;
  80   background: #eeeeff;
  81   padding-bottom: 1em;
  82 }
  83 pre.verbatim {
  84   border: solid 1px gray;
  85   background: white;
  86   padding-bottom: 1em;
  87 }
  88 div.node {
  89   margin: 0 -5% 0 -2%;
  90   padding: 0.5em 0.5em;
  91   margin-top: 0.5em;
  92   margin-bottom: 0.5em;
  93   font-weight: bold;
  94 }
  95 dd, li {
  96   padding-top: 0.1em;
  97   padding-bottom: 0.1em;
  98 }
  99
 100 -->
 101 </style>
 102
 103
 104 </head>
 105
 106 <body lang="en">
 107 <h1 class="settitle" align="center">GNU Libtasn1 4.12</h1>
 108
 109
 110
 111
 112
 113 <a name="SEC_Contents"></a>
 114 <h2 class="contents-heading">Table of Contents</h2>
 115
 116 <div class="contents">
 117
 118 <ul class="no-bullet">
 119   <li><a name="toc-Introduction-1" href="#Introduction">1 Introduction</a></li>
 120   <li><a name="toc-ASN_002e1-structure-handling-1" href="#ASN_002e1-structure-handling">2 ASN.1 structure handling</a>
 121   <ul class="no-bullet">
 122     <li><a name="toc-ASN_002e1-syntax-1" href="#ASN_002e1-syntax">2.1 ASN.1 syntax</a></li>
 123     <li><a name="toc-Naming-1" href="#Naming">2.2 Naming</a></li>
 124     <li><a name="toc-Simple-parsing-1" href="#Simple-parsing">2.3 Simple parsing</a></li>
 125     <li><a name="toc-Library-Notes-1" href="#Library-Notes">2.4 Library Notes</a></li>
 126     <li><a name="toc-Future-developments-1" href="#Future-developments">2.5 Future developments</a></li>
 127   </ul></li>
 128   <li><a name="toc-Utilities-1" href="#Utilities">3 Utilities</a>
 129   <ul class="no-bullet">
 130     <li><a name="toc-Invoking-asn1Parser-1" href="#Invoking-asn1Parser">3.1 Invoking asn1Parser</a></li>
 131     <li><a name="toc-Invoking-asn1Coding-1" href="#Invoking-asn1Coding">3.2 Invoking asn1Coding</a></li>
 132     <li><a name="toc-Invoking-asn1Decoding-1" href="#Invoking-asn1Decoding">3.3 Invoking asn1Decoding</a></li>
 133   </ul></li>
 134   <li><a name="toc-Function-reference-1" href="#Function-reference">4 Function reference</a>
 135   <ul class="no-bullet">
 136     <li><a name="toc-ASN_002e1-schema-functions-1" href="#ASN_002e1-schema-functions">4.1 ASN.1 schema functions</a></li>
 137     <li><a name="toc-ASN_002e1-field-functions-1" href="#ASN_002e1-field-functions">4.2 ASN.1 field functions</a></li>
 138     <li><a name="toc-DER-functions-1" href="#DER-functions">4.3 DER functions</a></li>
 139     <li><a name="toc-Error-handling-functions-1" href="#Error-handling-functions">4.4 Error handling functions</a></li>
 140     <li><a name="toc-Auxilliary-functions-1" href="#Auxilliary-functions">4.5 Auxilliary functions</a></li>
 141   </ul></li>
 142   <li><a name="toc-Copying-Information-1" href="#Copying-Information">Appendix A Copying Information</a>
 143   <ul class="no-bullet">
 144     <li><a name="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">A.1 GNU Free Documentation License</a></li>
 145   </ul></li>
 146   <li><a name="toc-Concept-Index-1" href="#Concept-Index">Concept Index</a></li>
 147   <li><a name="toc-Function-and-Data-Index-1" href="#Function-and-Data-Index">Function and Data Index</a></li>
 148 </ul>
 149 </div>
 150
 151
 152 <a name="Top"></a>
 153 <div class="header">
 154 <p>
 155 Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 156 </div>
 157 <a name="Libtasn1"></a>
 158 <h1 class="top">Libtasn1</h1>
 159
 160 <p>This manual is for GNU Libtasn1
 161 (version 4.12, 4 April 2016),
 162 which is a library for Abstract Syntax Notation One (ASN.1) and
 163 Distinguished Encoding Rules (DER) manipulation.
 164 </p>
 165 <p>Copyright &copy; 2001-2015 Free Software Foundation, Inc.
 166 </p>
 167 <blockquote>
 168 <p>Permission is granted to copy, distribute and/or modify this document
 169 under the terms of the GNU Free Documentation License, Version 1.3 or
 170 any later version published by the Free Software Foundation; with no
 171 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
 172 copy of the license is included in the section entitled &ldquo;GNU Free
 173 Documentation License&rdquo;.
 174 </p></blockquote>
 175
 176
 177 <table class="menu" border="0" cellspacing="0">
 178 <tr><td align="left" valign="top">&bull; <a href="#Introduction" accesskey="1">Introduction</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 179 </td></tr>
 180 <tr><td align="left" valign="top">&bull; <a href="#ASN_002e1-structure-handling" accesskey="2">ASN.1 structure handling</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 181 </td></tr>
 182 <tr><td align="left" valign="top">&bull; <a href="#Utilities" accesskey="3">Utilities</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 183 </td></tr>
 184 <tr><td align="left" valign="top">&bull; <a href="#Function-reference" accesskey="4">Function reference</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 185 </td></tr>
 186 <tr><td align="left" valign="top">&bull; <a href="#Copying-Information" accesskey="5">Copying Information</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 187 </td></tr>
 188 <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
 189
 190 Indices
 191
 192 </pre></th></tr><tr><td align="left" valign="top">&bull; <a href="#Concept-Index" accesskey="6">Concept Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Index of concepts and programs.
 193 </td></tr>
 194 <tr><td align="left" valign="top">&bull; <a href="#Function-and-Data-Index" accesskey="7">Function and Data Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Index of functions, variables and data types.
 195 </td></tr>
 196 </table>
 197
 198 <hr>
 199 <a name="Introduction"></a>
 200 <div class="header">
 201 <p>
 202 Next: <a href="#ASN_002e1-structure-handling" accesskey="n" rel="next">ASN.1 structure handling</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 203 </div>
 204 <a name="Introduction-1"></a>
 205 <h2 class="chapter">1 Introduction</h2>
 206
 207 <p>This document describes the Libtasn1 library that provides
 208 Abstract Syntax Notation One (ASN.1, as specified by the X.680 ITU-T
 209 recommendation) parsing and structures management,
 210 and Distinguished Encoding Rules (DER, as per X.690) encoding and
 211 decoding functions.
 212 </p>
 213 <p>The main features of this library are:
 214 </p>
 215 <ul>
 216 <li> On-line ASN.1 structure management that doesn&rsquo;t require any
 217 C code file generation.
 218
 219 </li><li> Off-line ASN.1 structure management with C code file generation
 220 containing an array.
 221
 222 </li><li> Distinguished Encoding Rules (DER) encoding support.
 223
 224 </li><li> No limits for INTEGER and ENUMERATED values.
 225
 226 </li><li> It&rsquo;s Free Software.
 227 Anybody can use, modify, and redistribute the library under the terms
 228 of the GNU Lesser General Public License version 2.1 or later.  The
 229 command line tools, self-tests and build infrastructure are licensed
 230 under the GNU General Public License version 3.0 or later.
 231
 232 </li><li> Thread-safety.
 233 <a name="index-threads"></a>
 234 No global variables are used and multiple library handles and session
 235 handles may be used in parallel.
 236
 237 </li><li> Portability.
 238 <a name="index-Porting"></a>
 239 The code should work on all Unix like operating systems, and Windows.
 240 The library itself should be portable to any C89 system, not even
 241 POSIX is required.
 242 </li></ul>
 243
 244 <hr>
 245 <a name="ASN_002e1-structure-handling"></a>
 246 <div class="header">
 247 <p>
 248 Next: <a href="#Utilities" accesskey="n" rel="next">Utilities</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 249 </div>
 250 <a name="ASN_002e1-structure-handling-1"></a>
 251 <h2 class="chapter">2 ASN.1 structure handling</h2>
 252
 253 <table class="menu" border="0" cellspacing="0">
 254 <tr><td align="left" valign="top">&bull; <a href="#ASN_002e1-syntax" accesskey="1">ASN.1 syntax</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 255 </td></tr>
 256 <tr><td align="left" valign="top">&bull; <a href="#Naming" accesskey="2">Naming</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 257 </td></tr>
 258 <tr><td align="left" valign="top">&bull; <a href="#Simple-parsing" accesskey="3">Simple parsing</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 259 </td></tr>
 260 <tr><td align="left" valign="top">&bull; <a href="#Library-Notes" accesskey="4">Library Notes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 261 </td></tr>
 262 <tr><td align="left" valign="top">&bull; <a href="#Future-developments" accesskey="5">Future developments</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 263 </td></tr>
 264 </table>
 265
 266 <hr>
 267 <a name="ASN_002e1-syntax"></a>
 268 <div class="header">
 269 <p>
 270 Next: <a href="#Naming" accesskey="n" rel="next">Naming</a>, Up: <a href="#ASN_002e1-structure-handling" accesskey="u" rel="up">ASN.1 structure handling</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 271 </div>
 272 <a name="ASN_002e1-syntax-1"></a>
 273 <h3 class="section">2.1 ASN.1 syntax</h3>
 274
 275 <a name="index-ASN_002e1-schema"></a>
 276
 277 <p>The parser is case sensitive.  The comments begin with <code>--</code> and
 278 end either with another <code>--</code>, or at the end of the respective
 279 line, whichever comes first.  The C-style <code>/*</code>, <code>*/</code>
 280 comments are not supported.
 281 </p>
 282 <p>For an example of the syntax, check the <samp>pkix.asn</samp> file
 283 distributed with the library.
 284 </p>
 285 <p>ASN.1 definitions must follow the syntax below:
 286 </p>
 287 <pre class="verbatim">      definitions_name {&lt;object definition&gt;}
 288
 289       DEFINITIONS &lt;EXPLICIT or IMPLICIT&gt; TAGS ::=
 290
 291       BEGIN
 292
 293       &lt;type and constants definitions&gt;
 294
 295       END
 296 </pre>
 297 <p>The <code>::=</code> token must be separate from other elements, so the
 298 following declaration is invalid:
 299 </p>
 300 <div class="example">
 301 <pre class="example">   -- INCORRECT
 302    Version ::=INTEGER
 303 </pre></div>
 304
 305 <p>The correct form is:
 306 </p>
 307 <div class="example">
 308 <pre class="example">   Version ::= INTEGER
 309 </pre></div>
 310
 311 <p>Here is the list of types that the parser can manage:
 312 </p>
 313 <a name="index-Supported-ASN_002e1-types_002c-list-of"></a>
 314
 315 <ul>
 316 <li> <code>INTEGER</code>;
 317 </li><li> <code>ENUMERATED</code>;
 318 </li><li> <code>BOOLEAN</code>;
 319 </li><li> <code>OBJECT IDENTIFIER</code>;
 320 </li><li> <code>NULL</code>;
 321 </li><li> <code>BIT STRING</code>;
 322 </li><li> <code>OCTET STRING</code>;
 323 </li><li> <code>UTCTime</code>;
 324 </li><li> <code>GeneralizedTime</code>;
 325 </li><li> <code>GeneralString</code>;
 326 </li><li> <code>NumericString</code>;
 327 </li><li> <code>IA5String</code>;
 328 </li><li> <code>TeletexString</code>;
 329 </li><li> <code>PrintableString</code>;
 330 </li><li> <code>UniversalString</code>;
 331 </li><li> <code>BMPString</code>;
 332 </li><li> <code>UTF8String</code>;
 333 </li><li> <code>VisibleString</code>;
 334 </li><li> <code>SEQUENCE</code>;
 335 </li><li> <code>SEQUENCE OF</code>;
 336 </li><li> <code>SET</code>;
 337 </li><li> <code>SET OF</code>;
 338 </li><li> <code>CHOICE</code>;
 339 </li><li> <code>ANY</code>;
 340 </li><li> <code>ANY DEFINED BY</code>.
 341
 342 </li></ul>
 343
 344 <p>This version doesn&rsquo;t handle the <code>REAL</code> type.  It doesn&rsquo;t support
 345 the <code>AUTOMATIC TAGS</code> option, and the <code>EXPORT</code> and
 346 <code>IMPORT</code> sections, either.
 347 </p>
 348 <p>The <code>SIZE</code> constraints are allowed, but no check is done on them.
 349 </p>
 350 <hr>
 351 <a name="Naming"></a>
 352 <div class="header">
 353 <p>
 354 Next: <a href="#Simple-parsing" accesskey="n" rel="next">Simple parsing</a>, Previous: <a href="#ASN_002e1-syntax" accesskey="p" rel="prev">ASN.1 syntax</a>, Up: <a href="#ASN_002e1-structure-handling" accesskey="u" rel="up">ASN.1 structure handling</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 355 </div>
 356 <a name="Naming-1"></a>
 357 <h3 class="section">2.2 Naming</h3>
 358
 359 <p>Consider this definition:
 360 </p>
 361 <pre class="verbatim">      Example { 1 2 3 4 }
 362
 363       DEFINITIONS EXPLICIT TAGS ::=
 364
 365       BEGIN
 366
 367       Group ::= SEQUENCE {
 368          id   OBJECT IDENTIFIER,
 369          value  Value
 370       }
 371
 372       Value ::= SEQUENCE {
 373          value1  INTEGER,
 374          value2  BOOLEAN
 375       }
 376
 377       END
 378 </pre>
 379 <p>The notation to access the &lsquo;<samp>Group</samp>&rsquo; type of the &lsquo;<samp>Example</samp>&rsquo;
 380 definition above is &lsquo;<samp>Example.Group</samp>&rsquo; (as a NUL-terminated string.)
 381 Such strings are used in the functions described below.
 382 </p>
 383 <p>Others examples:
 384 </p>
 385 <ul>
 386 <li> field &lsquo;<samp>id</samp>&rsquo; of the &lsquo;<samp>Group</samp>&rsquo; type: &lsquo;<samp>Example.Group.id</samp>&rsquo;;
 387
 388 </li><li> field &lsquo;<samp>value1</samp>&rsquo; of the &lsquo;<samp>value</samp>&rsquo; field of the &lsquo;<samp>Group</samp>&rsquo;
 389 type: &lsquo;<samp>Example.Group.value.value1</samp>&rsquo;.
 390
 391 </li></ul>
 392
 393 <p>Elements of structured types unnamed by the respective definition
 394 receive the names <code>?1</code>, <code>?2</code>, and so on.
 395 </p>
 396 <p>The <code>?LAST</code> name indicates the last element of a <code>SET OF</code> or
 397 <code>SEQUENCE OF</code>.
 398 </p>
 399 <hr>
 400 <a name="Simple-parsing"></a>
 401 <div class="header">
 402 <p>
 403 Next: <a href="#Library-Notes" accesskey="n" rel="next">Library Notes</a>, Previous: <a href="#Naming" accesskey="p" rel="prev">Naming</a>, Up: <a href="#ASN_002e1-structure-handling" accesskey="u" rel="up">ASN.1 structure handling</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 404 </div>
 405 <a name="Simple-parsing-1"></a>
 406 <h3 class="section">2.3 Simple parsing</h3>
 407
 408 <p>For simple types like <code>OCTET STRING</code> the simple parsing functions listed
 409 below may be used instead.
 410 </p>
 411 <ul>
 412 <li> <a href="#asn1_005fdecode_005fsimple_005fder">asn1_decode_simple_der</a>
 413 </li><li> <a href="#asn1_005fencode_005fsimple_005fder">asn1_encode_simple_der</a>
 414 </li></ul>
 415
 416 <hr>
 417 <a name="Library-Notes"></a>
 418 <div class="header">
 419 <p>
 420 Next: <a href="#Future-developments" accesskey="n" rel="next">Future developments</a>, Previous: <a href="#Simple-parsing" accesskey="p" rel="prev">Simple parsing</a>, Up: <a href="#ASN_002e1-structure-handling" accesskey="u" rel="up">ASN.1 structure handling</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 421 </div>
 422 <a name="Library-Notes-1"></a>
 423 <h3 class="section">2.4 Library Notes</h3>
 424
 425 <a name="index-Header-file-libtasn1_002eh"></a>
 426
 427 <p>The header file of this library is <samp>libtasn1.h</samp>.
 428 </p>
 429 <a name="index-Main-type-asn1_005fnode"></a>
 430
 431 <p>The main type used in it is <code>asn1_node</code>, and it&rsquo;s used to store
 432 the ASN.1 definitions and structures (instances).
 433 </p>
 434 <p>The <code>NULL</code> constant can be used for the variable
 435 initialization.  For example:
 436 </p>
 437 <div class="example">
 438 <pre class="example"> asn1_node definitions = NULL;
 439 </pre></div>
 440
 441 <p>Some functions require an <code>errorDescription</code> argument of type
 442 <code>char *</code>, pointing to a pre-allocated buffer of at least
 443 <code>ASN1_MAX_ERROR_DESCRIPTION_SIZE</code> bytes size (e.g., as in
 444 &lsquo;<samp>char description[ASN1_MAX_ERROR_DESCRIPTION_SIZE];</samp>&rsquo;).
 445 </p>
 446 <p><code>ASN1_MAX_NAME_SIZE</code> is the maximum number of characters allowed
 447 for an ASN.1 identifier.
 448 </p>
 449 <hr>
 450 <a name="Future-developments"></a>
 451 <div class="header">
 452 <p>
 453 Previous: <a href="#Library-Notes" accesskey="p" rel="prev">Library Notes</a>, Up: <a href="#ASN_002e1-structure-handling" accesskey="u" rel="up">ASN.1 structure handling</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 454 </div>
 455 <a name="Future-developments-1"></a>
 456 <h3 class="section">2.5 Future developments</h3>
 457 <a name="index-Future-developments"></a>
 458
 459 <ul>
 460 <li> Add functions for a C code file generation containing equivalent
 461 data structures (not a single array like now).
 462
 463 </li><li> The <code>REAL</code> type.
 464
 465 </li></ul>
 466
 467 <hr>
 468 <a name="Utilities"></a>
 469 <div class="header">
 470 <p>
 471 Next: <a href="#Function-reference" accesskey="n" rel="next">Function reference</a>, Previous: <a href="#ASN_002e1-structure-handling" accesskey="p" rel="prev">ASN.1 structure handling</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 472 </div>
 473 <a name="Utilities-1"></a>
 474 <h2 class="chapter">3 Utilities</h2>
 475
 476 <table class="menu" border="0" cellspacing="0">
 477 <tr><td align="left" valign="top">&bull; <a href="#Invoking-asn1Parser" accesskey="1">Invoking asn1Parser</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 478 </td></tr>
 479 <tr><td align="left" valign="top">&bull; <a href="#Invoking-asn1Coding" accesskey="2">Invoking asn1Coding</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 480 </td></tr>
 481 <tr><td align="left" valign="top">&bull; <a href="#Invoking-asn1Decoding" accesskey="3">Invoking asn1Decoding</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 482 </td></tr>
 483 </table>
 484
 485 <hr>
 486 <a name="Invoking-asn1Parser"></a>
 487 <div class="header">
 488 <p>
 489 Next: <a href="#Invoking-asn1Coding" accesskey="n" rel="next">Invoking asn1Coding</a>, Up: <a href="#Utilities" accesskey="u" rel="up">Utilities</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 490 </div>
 491 <a name="Invoking-asn1Parser-1"></a>
 492 <h3 class="section">3.1 Invoking asn1Parser</h3>
 493 <a name="index-asn1Parser-program"></a>
 494
 495 <p><code>asn1Parser</code> reads a single file with ASN.1 definitions and
 496 generates a
 497 file with an array to use with libtasn1 functions.
 498 </p>
 499 <pre class="verbatim">Usage:  asn1Parser [options] file
 500
 501 Options:
 502  -h : shows the help message.
 503  -v : shows version information and exit.
 504  -c : checks the syntax only.
 505  -o file : output file.
 506  -n name : array name.
 507 </pre>
 508 <hr>
 509 <a name="Invoking-asn1Coding"></a>
 510 <div class="header">
 511 <p>
 512 Next: <a href="#Invoking-asn1Decoding" accesskey="n" rel="next">Invoking asn1Decoding</a>, Previous: <a href="#Invoking-asn1Parser" accesskey="p" rel="prev">Invoking asn1Parser</a>, Up: <a href="#Utilities" accesskey="u" rel="up">Utilities</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 513 </div>
 514 <a name="Invoking-asn1Coding-1"></a>
 515 <h3 class="section">3.2 Invoking asn1Coding</h3>
 516 <a name="index-asn1Coding-program"></a>
 517
 518 <p><code>asn1Coding</code> generates a DER encoding from a file with ASN.1
 519 definitions and another one with assignments.
 520 </p>
 521 <p>The file with assignments must have this syntax:
 522 </p>
 523 <pre class="verbatim">InstanceName  Asn1Definition
 524
 525 nameString  value
 526
 527 nameString  value
 528 ...
 529 </pre>
 530 <p>To specify the field of a <code>CHOICE</code> to be used, specify its name
 531 as a value to the <code>CHOICE</code> element itself.  Use <code>''</code> to
 532 denote the root element itself.
 533 (as in the example below.)
 534 </p>
 535 <p>The output file is a binary file with the DER encoding.
 536 </p>
 537 <pre class="verbatim">Usage:  asn1Coding [options] file1 file2
 538  file1 : file with ASN1 definitions.
 539  file2 : file with assignments.
 540 Options:
 541  -h : shows the help message.
 542  -v : shows version information and exit.
 543  -c : checks the syntax only.
 544  -o file : output file.
 545 </pre>
 546 <p>For example, consider an ASN.1 definitions file as follows:
 547 </p>
 548 <pre class="verbatim">MYPKIX1 { }
 549
 550 DEFINITIONS IMPLICIT TAGS ::=
 551
 552 BEGIN
 553
 554 OtherStruct := SEQUENCE {
 555      x       INTEGER,
 556      y       CHOICE {
 557          y1 INTEGER,
 558          y2 OCTET STRING },
 559 }
 560
 561 Dss-Sig-Value ::= SEQUENCE {
 562      r       INTEGER,
 563      s       INTEGER,
 564      other   OtherStruct
 565      z       INTEGER OPTIONAL,
 566 }
 567
 568 END
 569 </pre>
 570 <p>And a assignments file as follows:
 571 </p>
 572 <pre class="verbatim">dp MYPKIX1.Dss-Sig-Value
 573
 574 r 42
 575 s 47
 576 other.x 66
 577 other.y y1
 578 other.y.y1 15
 579 z (NULL)
 580 </pre>
 581 <p>Running the command below will generate a <samp>assign.out</samp> file,
 582 containing the DER encoding of <code>PKIX1.Dss-Sig-Value</code>.
 583 </p>
 584 <pre class="verbatim">$ asn1Coding pkix.asn assign.asn1
 585 </pre>
 586 <p>If the root element is of the <code>CHOICE</code> type, the assignment file
 587 may be like (using the types defined in <samp>pkix.asn</samp>):
 588 </p><pre class="verbatim">elt PKIX1Implicit88.GeneralName
 589
 590 ''      dNSName
 591 dNSName example.org
 592 </pre>
 593 <hr>
 594 <a name="Invoking-asn1Decoding"></a>
 595 <div class="header">
 596 <p>
 597 Previous: <a href="#Invoking-asn1Coding" accesskey="p" rel="prev">Invoking asn1Coding</a>, Up: <a href="#Utilities" accesskey="u" rel="up">Utilities</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 598 </div>
 599 <a name="Invoking-asn1Decoding-1"></a>
 600 <h3 class="section">3.3 Invoking asn1Decoding</h3>
 601 <a name="index-asn1Decoding-program"></a>
 602
 603 <p><code>asn1Decoding</code> generates an ASN.1 structure from a file with
 604 ASN.1
 605 definitions and a binary file with a DER encoding.
 606 </p>
 607 <pre class="verbatim">Usage:  asn1Decoding [options] file1 file2 type
 608  file1 : file with ASN1 definitions.
 609  file2 : binary file with a DER encoding.
 610  type : ASN1 definition name.
 611 Options:
 612  -h : shows the help message.
 613  -v : shows version information and exit.
 614  -o file : output file.
 615 </pre>
 616 <p>For example, after generating the <samp>assign.out</samp> file from the
 617 example section of the <code>asn1Coding</code> command above, the
 618 following
 619 invocation will decode the DER data.
 620 </p>
 621 <pre class="verbatim">$ asn1Decoding pkix.asn assign.out PKIX1.Dss-Sig-Value
 622 </pre>
 623 <hr>
 624 <a name="Function-reference"></a>
 625 <div class="header">
 626 <p>
 627 Next: <a href="#Copying-Information" accesskey="n" rel="next">Copying Information</a>, Previous: <a href="#Utilities" accesskey="p" rel="prev">Utilities</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 628 </div>
 629 <a name="Function-reference-1"></a>
 630 <h2 class="chapter">4 Function reference</h2>
 631
 632 <table class="menu" border="0" cellspacing="0">
 633 <tr><td align="left" valign="top">&bull; <a href="#ASN_002e1-schema-functions" accesskey="1">ASN.1 schema functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 634 </td></tr>
 635 <tr><td align="left" valign="top">&bull; <a href="#ASN_002e1-field-functions" accesskey="2">ASN.1 field functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 636 </td></tr>
 637 <tr><td align="left" valign="top">&bull; <a href="#DER-functions" accesskey="3">DER functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 638 </td></tr>
 639 <tr><td align="left" valign="top">&bull; <a href="#Error-handling-functions" accesskey="4">Error handling functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 640 </td></tr>
 641 <tr><td align="left" valign="top">&bull; <a href="#Auxilliary-functions" accesskey="5">Auxilliary functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 642 </td></tr>
 643 </table>
 644
 645 <hr>
 646 <a name="ASN_002e1-schema-functions"></a>
 647 <div class="header">
 648 <p>
 649 Next: <a href="#ASN_002e1-field-functions" accesskey="n" rel="next">ASN.1 field functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 650 </div>
 651 <a name="ASN_002e1-schema-functions-1"></a>
 652 <h3 class="section">4.1 ASN.1 schema functions</h3>
 653
 654 <a name="asn1_005fparser2tree-1"></a>
 655 <h4 class="subheading">asn1_parser2tree</h4>
 656 <a name="asn1_005fparser2tree"></a><dl>
 657 <dt><a name="index-asn1_005fparser2tree"></a>Function: <em>int</em> <strong>asn1_parser2tree</strong> <em>(const char * <var>file</var>, asn1_node * <var>definitions</var>, char * <var>error_desc</var>)</em></dt>
 658 <dd><p><var>file</var>: specify the path and the name of file that contains
 659 ASN.1 declarations.
 660 </p>
 661 <p><var>definitions</var>: return the pointer to the structure created from
 662 &quot;file&quot; ASN.1 declarations.
 663 </p>
 664 <p><var>error_desc</var>: return the error description or an empty
 665 string if success.
 666 </p>
 667 <p>Function used to start the parse algorithm.  Creates the structures
 668 needed to manage the definitions included in  <code>file</code> file.
 669 </p>
 670 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if the file has a correct syntax and every
 671 identifier is known, <code>ASN1_ELEMENT_NOT_EMPTY</code>  if  <code>definitions</code> not
 672 <code>NULL</code> , <code>ASN1_FILE_NOT_FOUND</code>  if an error occured while
 673 opening  <code>file</code> , <code>ASN1_SYNTAX_ERROR</code>  if the syntax is not
 674 correct, <code>ASN1_IDENTIFIER_NOT_FOUND</code>  if in the file there is an
 675 identifier that is not defined, <code>ASN1_NAME_TOO_LONG</code>  if in the
 676 file there is an identifier whith more than <code>ASN1_MAX_NAME_SIZE</code>
 677 characters.
 678 </p></dd></dl>
 679
 680 <a name="asn1_005fparser2array-1"></a>
 681 <h4 class="subheading">asn1_parser2array</h4>
 682 <a name="asn1_005fparser2array"></a><dl>
 683 <dt><a name="index-asn1_005fparser2array"></a>Function: <em>int</em> <strong>asn1_parser2array</strong> <em>(const char * <var>inputFileName</var>, const char * <var>outputFileName</var>, const char * <var>vectorName</var>, char * <var>error_desc</var>)</em></dt>
 684 <dd><p><var>inputFileName</var>: specify the path and the name of file that
 685 contains ASN.1 declarations.
 686 </p>
 687 <p><var>outputFileName</var>: specify the path and the name of file that will
 688 contain the C vector definition.
 689 </p>
 690 <p><var>vectorName</var>: specify the name of the C vector.
 691 </p>
 692 <p><var>error_desc</var>: return the error description or an empty
 693 string if success.
 694 </p>
 695 <p>Function that generates a C structure from an ASN1 file.  Creates a
 696 file containing a C vector to use to manage the definitions
 697 included in  <code>inputFileName</code> file. If  <code>inputFileName</code> is
 698 &quot;/aa/bb/xx.yy&quot; and  <code>outputFileName</code> is <code>NULL</code> , the file created is
 699 &quot;/aa/bb/xx_asn1_tab.c&quot;.  If  <code>vectorName</code> is <code>NULL</code>  the vector name
 700 will be &quot;xx_asn1_tab&quot;.
 701 </p>
 702 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if the file has a correct syntax and every
 703 identifier is known, <code>ASN1_FILE_NOT_FOUND</code>  if an error occured
 704 while opening  <code>inputFileName</code> , <code>ASN1_SYNTAX_ERROR</code>  if the syntax is
 705 not correct, <code>ASN1_IDENTIFIER_NOT_FOUND</code>  if in the file there is
 706 an identifier that is not defined, <code>ASN1_NAME_TOO_LONG</code>  if in the
 707 file there is an identifier whith more than <code>ASN1_MAX_NAME_SIZE</code>
 708 characters.
 709 </p></dd></dl>
 710
 711
 712 <hr>
 713 <a name="ASN_002e1-field-functions"></a>
 714 <div class="header">
 715 <p>
 716 Next: <a href="#DER-functions" accesskey="n" rel="next">DER functions</a>, Previous: <a href="#ASN_002e1-schema-functions" accesskey="p" rel="prev">ASN.1 schema functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
 717 </div>
 718 <a name="ASN_002e1-field-functions-1"></a>
 719 <h3 class="section">4.2 ASN.1 field functions</h3>
 720
 721 <a name="asn1_005farray2tree-1"></a>
 722 <h4 class="subheading">asn1_array2tree</h4>
 723 <a name="asn1_005farray2tree"></a><dl>
 724 <dt><a name="index-asn1_005farray2tree"></a>Function: <em>int</em> <strong>asn1_array2tree</strong> <em>(const asn1_static_node * <var>array</var>, asn1_node * <var>definitions</var>, char * <var>errorDescription</var>)</em></dt>
 725 <dd><p><var>array</var>: specify the array that contains ASN.1 declarations
 726 </p>
 727 <p><var>definitions</var>: return the pointer to the structure created by
 728 *ARRAY ASN.1 declarations
 729 </p>
 730 <p><var>errorDescription</var>: return the error description.
 731 </p>
 732 <p>Creates the structures needed to manage the ASN.1 definitions.
 733  <code>array</code> is a vector created by <code>asn1_parser2array()</code> .
 734 </p>
 735 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if structure was created correctly,
 736 <code>ASN1_ELEMENT_NOT_EMPTY</code>  if * <code>definitions</code> not NULL,
 737 <code>ASN1_IDENTIFIER_NOT_FOUND</code>  if in the file there is an identifier
 738 that is not defined (see  <code>errorDescription</code> for more information),
 739 <code>ASN1_ARRAY_ERROR</code>  if the array pointed by  <code>array</code> is wrong.
 740 </p></dd></dl>
 741
 742 <a name="asn1_005fdelete_005fstructure-1"></a>
 743 <h4 class="subheading">asn1_delete_structure</h4>
 744 <a name="asn1_005fdelete_005fstructure"></a><dl>
 745 <dt><a name="index-asn1_005fdelete_005fstructure"></a>Function: <em>int</em> <strong>asn1_delete_structure</strong> <em>(asn1_node * <var>structure</var>)</em></dt>
 746 <dd><p><var>structure</var>: pointer to the structure that you want to delete.
 747 </p>
 748 <p>Deletes the structure * <code>structure</code> .  At the end, * <code>structure</code> is set
 749 to NULL.
 750 </p>
 751 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if successful, <code>ASN1_ELEMENT_NOT_FOUND</code>  if
 752 * <code>structure</code> was NULL.
 753 </p></dd></dl>
 754
 755 <a name="asn1_005fdelete_005fstructure2-1"></a>
 756 <h4 class="subheading">asn1_delete_structure2</h4>
 757 <a name="asn1_005fdelete_005fstructure2"></a><dl>
 758 <dt><a name="index-asn1_005fdelete_005fstructure2"></a>Function: <em>int</em> <strong>asn1_delete_structure2</strong> <em>(asn1_node * <var>structure</var>, unsigned int <var>flags</var>)</em></dt>
 759 <dd><p><var>structure</var>: pointer to the structure that you want to delete.
 760 </p>
 761 <p><var>flags</var>: additional flags (see <code>ASN1_DELETE_FLAG</code> )
 762 </p>
 763 <p>Deletes the structure * <code>structure</code> .  At the end, * <code>structure</code> is set
 764 to NULL.
 765 </p>
 766 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if successful, <code>ASN1_ELEMENT_NOT_FOUND</code>  if
 767 * <code>structure</code> was NULL.
 768 </p></dd></dl>
 769
 770 <a name="asn1_005fdelete_005felement-1"></a>
 771 <h4 class="subheading">asn1_delete_element</h4>
 772 <a name="asn1_005fdelete_005felement"></a><dl>
 773 <dt><a name="index-asn1_005fdelete_005felement"></a>Function: <em>int</em> <strong>asn1_delete_element</strong> <em>(asn1_node <var>structure</var>, const char * <var>element_name</var>)</em></dt>
 774 <dd><p><var>structure</var>: pointer to the structure that contains the element you
 775 want to delete.
 776 </p>
 777 <p><var>element_name</var>: element&rsquo;s name you want to delete.
 778 </p>
 779 <p>Deletes the element named * <code>element_name</code> inside * <code>structure</code> .
 780 </p>
 781 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if successful, <code>ASN1_ELEMENT_NOT_FOUND</code>  if
 782 the  <code>element_name</code> was not found.
 783 </p></dd></dl>
 784
 785 <a name="asn1_005fcreate_005felement-1"></a>
 786 <h4 class="subheading">asn1_create_element</h4>
 787 <a name="asn1_005fcreate_005felement"></a><dl>
 788 <dt><a name="index-asn1_005fcreate_005felement"></a>Function: <em>int</em> <strong>asn1_create_element</strong> <em>(asn1_node <var>definitions</var>, const char * <var>source_name</var>, asn1_node * <var>element</var>)</em></dt>
 789 <dd><p><var>definitions</var>: pointer to the structure returned by &quot;parser_asn1&quot; function
 790 </p>
 791 <p><var>source_name</var>: the name of the type of the new structure (must be
 792 inside p_structure).
 793 </p>
 794 <p><var>element</var>: pointer to the structure created.
 795 </p>
 796 <p>Creates a structure of type  <code>source_name</code> .  Example using
 797 &quot;pkix.asn&quot;:
 798 </p>
 799 <p>rc = asn1_create_element(cert_def, &quot;PKIX1.Certificate&quot;, certptr);
 800 </p>
 801 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if creation OK, <code>ASN1_ELEMENT_NOT_FOUND</code>  if
 802  <code>source_name</code> is not known.
 803 </p></dd></dl>
 804
 805 <a name="asn1_005fprint_005fstructure-1"></a>
 806 <h4 class="subheading">asn1_print_structure</h4>
 807 <a name="asn1_005fprint_005fstructure"></a><dl>
 808 <dt><a name="index-asn1_005fprint_005fstructure"></a>Function: <em>void</em> <strong>asn1_print_structure</strong> <em>(FILE * <var>out</var>, asn1_node <var>structure</var>, const char * <var>name</var>, int <var>mode</var>)</em></dt>
 809 <dd><p><var>out</var>: pointer to the output file (e.g. stdout).
 810 </p>
 811 <p><var>structure</var>: pointer to the structure that you want to visit.
 812 </p>
 813 <p><var>name</var>: an element of the structure
 814 </p>
 815 <p><var>mode</var>: specify how much of the structure to print, can be
 816 <code>ASN1_PRINT_NAME</code> , <code>ASN1_PRINT_NAME_TYPE</code> ,
 817 <code>ASN1_PRINT_NAME_TYPE_VALUE</code> , or <code>ASN1_PRINT_ALL</code> .
 818 </p>
 819 <p>Prints on the  <code>out</code> file descriptor the structure&rsquo;s tree starting
 820 from the  <code>name</code> element inside the structure  <code>structure</code> .
 821 </p></dd></dl>
 822
 823 <a name="asn1_005fnumber_005fof_005felements-1"></a>
 824 <h4 class="subheading">asn1_number_of_elements</h4>
 825 <a name="asn1_005fnumber_005fof_005felements"></a><dl>
 826 <dt><a name="index-asn1_005fnumber_005fof_005felements"></a>Function: <em>int</em> <strong>asn1_number_of_elements</strong> <em>(asn1_node <var>element</var>, const char * <var>name</var>, int * <var>num</var>)</em></dt>
 827 <dd><p><var>element</var>: pointer to the root of an ASN1 structure.
 828 </p>
 829 <p><var>name</var>: the name of a sub-structure of ROOT.
 830 </p>
 831 <p><var>num</var>: pointer to an integer where the result will be stored
 832 </p>
 833 <p>Counts the number of elements of a sub-structure called NAME with
 834 names equal to &quot;?1&quot;,&quot;?2&quot;, ...
 835 </p>
 836 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if successful, <code>ASN1_ELEMENT_NOT_FOUND</code>  if
 837  <code>name</code> is not known, <code>ASN1_GENERIC_ERROR</code>  if pointer  <code>num</code> is <code>NULL</code> .
 838 </p></dd></dl>
 839
 840 <a name="asn1_005ffind_005fstructure_005ffrom_005foid-1"></a>
 841 <h4 class="subheading">asn1_find_structure_from_oid</h4>
 842 <a name="asn1_005ffind_005fstructure_005ffrom_005foid"></a><dl>
 843 <dt><a name="index-asn1_005ffind_005fstructure_005ffrom_005foid"></a>Function: <em>const char *</em> <strong>asn1_find_structure_from_oid</strong> <em>(asn1_node <var>definitions</var>, const char * <var>oidValue</var>)</em></dt>
 844 <dd><p><var>definitions</var>: ASN1 definitions
 845 </p>
 846 <p><var>oidValue</var>: value of the OID to search (e.g. &quot;1.2.3.4&quot;).
 847 </p>
 848 <p>Search the structure that is defined just after an OID definition.
 849 </p>
 850 <p><strong>Returns:</strong> <code>NULL</code>  when  <code>oidValue</code> not found, otherwise the pointer to a
 851 constant string that contains the element name defined just after
 852 the OID.
 853 </p></dd></dl>
 854
 855 <a name="asn1_005fcopy_005fnode-1"></a>
 856 <h4 class="subheading">asn1_copy_node</h4>
 857 <a name="asn1_005fcopy_005fnode"></a><dl>
 858 <dt><a name="index-asn1_005fcopy_005fnode"></a>Function: <em>int</em> <strong>asn1_copy_node</strong> <em>(asn1_node <var>dst</var>, const char * <var>dst_name</var>, asn1_node <var>src</var>, const char * <var>src_name</var>)</em></dt>
 859 <dd><p><var>dst</var>: Destination asn1 node.
 860 </p>
 861 <p><var>dst_name</var>: Field name in destination node.
 862 </p>
 863 <p><var>src</var>: Source asn1 node.
 864 </p>
 865 <p><var>src_name</var>: Field name in source node.
 866 </p>
 867 <p>Create a deep copy of a asn1_node variable. That
 868 function requires  <code>dst</code> to be expanded using <code>asn1_create_element()</code> .
 869 </p>
 870 <p><strong>Returns:</strong> Return <code>ASN1_SUCCESS</code>  on success.
 871 </p></dd></dl>
 872
 873 <a name="asn1_005fdup_005fnode-1"></a>
 874 <h4 class="subheading">asn1_dup_node</h4>
 875 <a name="asn1_005fdup_005fnode"></a><dl>
 876 <dt><a name="index-asn1_005fdup_005fnode"></a>Function: <em>asn1_node</em> <strong>asn1_dup_node</strong> <em>(asn1_node <var>src</var>, const char * <var>src_name</var>)</em></dt>
 877 <dd><p><var>src</var>: Source asn1 node.
 878 </p>
 879 <p><var>src_name</var>: Field name in source node.
 880 </p>
 881 <p>Create a deep copy of a asn1_node variable. This function
 882 will return an exact copy of the provided structure.
 883 </p>
 884 <p><strong>Returns:</strong> Return <code>NULL</code>  on failure.
 885 </p></dd></dl>
 886
 887 <a name="asn1_005fwrite_005fvalue-1"></a>
 888 <h4 class="subheading">asn1_write_value</h4>
 889 <a name="asn1_005fwrite_005fvalue"></a><dl>
 890 <dt><a name="index-asn1_005fwrite_005fvalue"></a>Function: <em>int</em> <strong>asn1_write_value</strong> <em>(asn1_node <var>node_root</var>, const char * <var>name</var>, const void * <var>ivalue</var>, int <var>len</var>)</em></dt>
 891 <dd><p><var>node_root</var>: pointer to a structure
 892 </p>
 893 <p><var>name</var>: the name of the element inside the structure that you want to set.
 894 </p>
 895 <p><var>ivalue</var>: vector used to specify the value to set. If len is &gt;0,
 896 VALUE must be a two&rsquo;s complement form integer.  if len=0 *VALUE
 897 must be a null terminated string with an integer value.
 898 </p>
 899 <p><var>len</var>: number of bytes of *value to use to set the value:
 900 value[0]..value[len-1] or 0 if value is a null terminated string
 901 </p>
 902 <p>Set the value of one element inside a structure.
 903 </p>
 904 <p>If an element is OPTIONAL and you want to delete it, you must use
 905 the value=NULL and len=0.  Using &quot;pkix.asn&quot;:
 906 </p>
 907 <p>result=asn1_write_value(cert, &quot;tbsCertificate.issuerUniqueID&quot;,
 908 NULL, 0);
 909 </p>
 910 <p>Description for each type:
 911 </p>
 912 <p><strong>INTEGER:</strong> VALUE must contain a two&rsquo;s complement form integer.
 913 </p>
 914 <p>value[0]=0xFF ,               len=1 -&gt; integer=-1.
 915 value[0]=0xFF value[1]=0xFF , len=2 -&gt; integer=-1.
 916 value[0]=0x01 ,               len=1 -&gt; integer= 1.
 917 value[0]=0x00 value[1]=0x01 , len=2 -&gt; integer= 1.
 918 value=&quot;123&quot;                 , len=0 -&gt; integer= 123.
 919 </p>
 920 <p><strong>ENUMERATED:</strong> As INTEGER (but only with not negative numbers).
 921 </p>
 922 <p><strong>BOOLEAN:</strong> VALUE must be the null terminated string &quot;TRUE&quot; or
 923 &quot;FALSE&quot; and LEN != 0.
 924 </p>
 925 <p>value=&quot;TRUE&quot; , len=1 -&gt; boolean=TRUE.
 926 value=&quot;FALSE&quot; , len=1 -&gt; boolean=FALSE.
 927 </p>
 928 <p>OBJECT IDENTIFIER: VALUE must be a null terminated string with
 929 each number separated by a dot (e.g. &quot;1.2.3.543.1&quot;).  LEN != 0.
 930 </p>
 931 <p>value=&quot;1 2 840 10040 4 3&quot; , len=1 -&gt; OID=dsa-with-sha.
 932 </p>
 933 <p><strong>UTCTime:</strong> VALUE must be a null terminated string in one of these
 934 formats: &quot;YYMMDDhhmmssZ&quot;, &quot;YYMMDDhhmmssZ&quot;,
 935 &quot;YYMMDDhhmmss+hh&rsquo;mm&rsquo;&quot;, &quot;YYMMDDhhmmss-hh&rsquo;mm&rsquo;&quot;,
 936 &quot;YYMMDDhhmm+hh&rsquo;mm&rsquo;&quot;, or &quot;YYMMDDhhmm-hh&rsquo;mm&rsquo;&quot;.  LEN != 0.
 937 </p>
 938 <p>value=&quot;9801011200Z&quot; , len=1 -&gt; time=Jannuary 1st, 1998
 939 at 12h 00m Greenwich Mean Time
 940 </p>
 941 <p><strong>GeneralizedTime:</strong> VALUE must be in one of this format:
 942 &quot;YYYYMMDDhhmmss.sZ&quot;, &quot;YYYYMMDDhhmmss.sZ&quot;,
 943 &quot;YYYYMMDDhhmmss.s+hh&rsquo;mm&rsquo;&quot;, &quot;YYYYMMDDhhmmss.s-hh&rsquo;mm&rsquo;&quot;,
 944 &quot;YYYYMMDDhhmm+hh&rsquo;mm&rsquo;&quot;, or &quot;YYYYMMDDhhmm-hh&rsquo;mm&rsquo;&quot; where ss.s
 945 indicates the seconds with any precision like &quot;10.1&quot; or &quot;01.02&quot;.
 946 LEN != 0
 947 </p>
 948 <p>value=&quot;2001010112001.12-0700&quot; , len=1 -&gt; time=Jannuary
 949 1st, 2001 at 12h 00m 01.12s Pacific Daylight Time
 950 </p>
 951 <p>OCTET STRING: VALUE contains the octet string and LEN is the
 952 number of octets.
 953 </p>
 954 <p>value=&quot;$\backslash$x01$\backslash$x02$\backslash$x03&quot; ,
 955 len=3 -&gt; three bytes octet string
 956 </p>
 957 <p><strong>GeneralString:</strong> VALUE contains the generalstring and LEN is the
 958 number of octets.
 959 </p>
 960 <p>value=&quot;$\backslash$x01$\backslash$x02$\backslash$x03&quot; ,
 961 len=3 -&gt; three bytes generalstring
 962 </p>
 963 <p>BIT STRING: VALUE contains the bit string organized by bytes and
 964 LEN is the number of bits.
 965 </p>
 966 <p>value=&quot;$\backslash$xCF&quot; , len=6 -&gt; bit string=&quot;110011&quot; (six
 967 bits)
 968 </p>
 969 <p><strong>CHOICE:</strong> if NAME indicates a choice type, VALUE must specify one of
 970 the alternatives with a null terminated string. LEN != 0. Using
 971 &quot;pkix.asn&quot;\:
 972 </p>
 973 <p>result=asn1_write_value(cert,
 974 &quot;certificate1.tbsCertificate.subject&quot;, &quot;rdnSequence&quot;,
 975 1);
 976 </p>
 977 <p><strong>ANY:</strong> VALUE indicates the der encoding of a structure.  LEN != 0.
 978 </p>
 979 <p>SEQUENCE OF: VALUE must be the null terminated string &quot;NEW&quot; and
 980 LEN != 0. With this instruction another element is appended in
 981 the sequence. The name of this element will be &quot;?1&quot; if it&rsquo;s the
 982 first one, &quot;?2&quot; for the second and so on.
 983 </p>
 984 <p>Using &quot;pkix.asn&quot;\:
 985 </p>
 986 <p>result=asn1_write_value(cert,
 987 &quot;certificate1.tbsCertificate.subject.rdnSequence&quot;, &quot;NEW&quot;, 1);
 988 </p>
 989 <p>SET OF: the same as SEQUENCE OF.  Using &quot;pkix.asn&quot;:
 990 </p>
 991 <p>result=asn1_write_value(cert,
 992 &quot;tbsCertificate.subject.rdnSequence.?LAST&quot;, &quot;NEW&quot;, 1);
 993 </p>
 994 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if the value was set,
 995 <code>ASN1_ELEMENT_NOT_FOUND</code>  if  <code>name</code> is not a valid element, and
 996 <code>ASN1_VALUE_NOT_VALID</code>  if  <code>ivalue</code> has a wrong format.
 997 </p></dd></dl>
 998
 999 <a name="asn1_005fread_005fvalue-1"></a>
1000 <h4 class="subheading">asn1_read_value</h4>
1001 <a name="asn1_005fread_005fvalue"></a><dl>
1002 <dt><a name="index-asn1_005fread_005fvalue"></a>Function: <em>int</em> <strong>asn1_read_value</strong> <em>(asn1_node <var>root</var>, const char * <var>name</var>, void * <var>ivalue</var>, int * <var>len</var>)</em></dt>
1003 <dd><p><var>root</var>: pointer to a structure.
1004 </p>
1005 <p><var>name</var>: the name of the element inside a structure that you want to read.
1006 </p>
1007 <p><var>ivalue</var>: vector that will contain the element&rsquo;s content, must be a
1008 pointer to memory cells already allocated (may be <code>NULL</code> ).
1009 </p>
1010 <p><var>len</var>: number of bytes of *value: value[0]..value[len-1]. Initialy
1011 holds the sizeof value.
1012 </p>
1013 <p>Returns the value of one element inside a structure.
1014 If an element is OPTIONAL and this returns
1015 <code>ASN1_ELEMENT_NOT_FOUND</code> , it means that this element wasn&rsquo;t present
1016 in the der encoding that created the structure.  The first element
1017 of a SEQUENCE_OF or SET_OF is named &quot;?1&quot;. The second one &quot;?2&quot; and
1018 so on. If the  <code>root</code> provided is a node to specific sequence element,
1019 then the keyword &quot;?CURRENT&quot; is also acceptable and indicates the
1020 current sequence element of this node.
1021 </p>
1022 <p>Note that there can be valid values with length zero. In these case
1023 this function will succeed and  <code>len</code> will be zero.
1024 </p>
1025 <p><strong>INTEGER:</strong> VALUE will contain a two&rsquo;s complement form integer.
1026 </p>
1027 <p>integer=-1  -&gt; value[0]=0xFF , len=1.
1028 integer=1   -&gt; value[0]=0x01 , len=1.
1029 </p>
1030 <p><strong>ENUMERATED:</strong> As INTEGER (but only with not negative numbers).
1031 </p>
1032 <p><strong>BOOLEAN:</strong> VALUE will be the null terminated string &quot;TRUE&quot; or
1033 &quot;FALSE&quot; and LEN=5 or LEN=6.
1034 </p>
1035 <p>OBJECT IDENTIFIER: VALUE will be a null terminated string with
1036 each number separated by a dot (i.e. &quot;1.2.3.543.1&quot;).
1037 </p>
1038 <p>LEN = strlen(VALUE)+1
1039 </p>
1040 <p><strong>UTCTime:</strong> VALUE will be a null terminated string in one of these
1041 formats: &quot;YYMMDDhhmmss+hh&rsquo;mm&rsquo;&quot; or &quot;YYMMDDhhmmss-hh&rsquo;mm&rsquo;&quot;.
1042 LEN=strlen(VALUE)+1.
1043 </p>
1044 <p><strong>GeneralizedTime:</strong> VALUE will be a null terminated string in the
1045 same format used to set the value.
1046 </p>
1047 <p>OCTET STRING: VALUE will contain the octet string and LEN will be
1048 the number of octets.
1049 </p>
1050 <p><strong>GeneralString:</strong> VALUE will contain the generalstring and LEN will
1051 be the number of octets.
1052 </p>
1053 <p>BIT STRING: VALUE will contain the bit string organized by bytes
1054 and LEN will be the number of bits.
1055 </p>
1056 <p><strong>CHOICE:</strong> If NAME indicates a choice type, VALUE will specify the
1057 alternative selected.
1058 </p>
1059 <p><strong>ANY:</strong> If NAME indicates an any type, VALUE will indicate the DER
1060 encoding of the structure actually used.
1061 </p>
1062 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if value is returned,
1063 <code>ASN1_ELEMENT_NOT_FOUND</code>  if  <code>name</code> is not a valid element,
1064 <code>ASN1_VALUE_NOT_FOUND</code>  if there isn&rsquo;t any value for the element
1065 selected, and <code>ASN1_MEM_ERROR</code>  if The value vector isn&rsquo;t big enough
1066 to store the result, and in this case  <code>len</code> will contain the number of
1067 bytes needed.
1068 </p></dd></dl>
1069
1070 <a name="asn1_005fread_005fvalue_005ftype-1"></a>
1071 <h4 class="subheading">asn1_read_value_type</h4>
1072 <a name="asn1_005fread_005fvalue_005ftype"></a><dl>
1073 <dt><a name="index-asn1_005fread_005fvalue_005ftype"></a>Function: <em>int</em> <strong>asn1_read_value_type</strong> <em>(asn1_node <var>root</var>, const char * <var>name</var>, void * <var>ivalue</var>, int * <var>len</var>, unsigned int * <var>etype</var>)</em></dt>
1074 <dd><p><var>root</var>: pointer to a structure.
1075 </p>
1076 <p><var>name</var>: the name of the element inside a structure that you want to read.
1077 </p>
1078 <p><var>ivalue</var>: vector that will contain the element&rsquo;s content, must be a
1079 pointer to memory cells already allocated (may be <code>NULL</code> ).
1080 </p>
1081 <p><var>len</var>: number of bytes of *value: value[0]..value[len-1]. Initialy
1082 holds the sizeof value.
1083 </p>
1084 <p><var>etype</var>: The type of the value read (ASN1_ETYPE)
1085 </p>
1086 <p>Returns the type and value of one element inside a structure.
1087 If an element is OPTIONAL and this returns
1088 <code>ASN1_ELEMENT_NOT_FOUND</code> , it means that this element wasn&rsquo;t present
1089 in the der encoding that created the structure.  The first element
1090 of a SEQUENCE_OF or SET_OF is named &quot;?1&quot;. The second one &quot;?2&quot; and
1091 so on. If the  <code>root</code> provided is a node to specific sequence element,
1092 then the keyword &quot;?CURRENT&quot; is also acceptable and indicates the
1093 current sequence element of this node.
1094 </p>
1095 <p>Note that there can be valid values with length zero. In these case
1096 this function will succeed and  <code>len</code> will be zero.
1097 </p>
1098 <p><strong>INTEGER:</strong> VALUE will contain a two&rsquo;s complement form integer.
1099 </p>
1100 <p>integer=-1  -&gt; value[0]=0xFF , len=1.
1101 integer=1   -&gt; value[0]=0x01 , len=1.
1102 </p>
1103 <p><strong>ENUMERATED:</strong> As INTEGER (but only with not negative numbers).
1104 </p>
1105 <p><strong>BOOLEAN:</strong> VALUE will be the null terminated string &quot;TRUE&quot; or
1106 &quot;FALSE&quot; and LEN=5 or LEN=6.
1107 </p>
1108 <p>OBJECT IDENTIFIER: VALUE will be a null terminated string with
1109 each number separated by a dot (i.e. &quot;1.2.3.543.1&quot;).
1110 </p>
1111 <p>LEN = strlen(VALUE)+1
1112 </p>
1113 <p><strong>UTCTime:</strong> VALUE will be a null terminated string in one of these
1114 formats: &quot;YYMMDDhhmmss+hh&rsquo;mm&rsquo;&quot; or &quot;YYMMDDhhmmss-hh&rsquo;mm&rsquo;&quot;.
1115 LEN=strlen(VALUE)+1.
1116 </p>
1117 <p><strong>GeneralizedTime:</strong> VALUE will be a null terminated string in the
1118 same format used to set the value.
1119 </p>
1120 <p>OCTET STRING: VALUE will contain the octet string and LEN will be
1121 the number of octets.
1122 </p>
1123 <p><strong>GeneralString:</strong> VALUE will contain the generalstring and LEN will
1124 be the number of octets.
1125 </p>
1126 <p>BIT STRING: VALUE will contain the bit string organized by bytes
1127 and LEN will be the number of bits.
1128 </p>
1129 <p><strong>CHOICE:</strong> If NAME indicates a choice type, VALUE will specify the
1130 alternative selected.
1131 </p>
1132 <p><strong>ANY:</strong> If NAME indicates an any type, VALUE will indicate the DER
1133 encoding of the structure actually used.
1134 </p>
1135 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if value is returned,
1136 <code>ASN1_ELEMENT_NOT_FOUND</code>  if  <code>name</code> is not a valid element,
1137 <code>ASN1_VALUE_NOT_FOUND</code>  if there isn&rsquo;t any value for the element
1138 selected, and <code>ASN1_MEM_ERROR</code>  if The value vector isn&rsquo;t big enough
1139 to store the result, and in this case  <code>len</code> will contain the number of
1140 bytes needed.
1141 </p></dd></dl>
1142
1143 <a name="asn1_005fread_005ftag-1"></a>
1144 <h4 class="subheading">asn1_read_tag</h4>
1145 <a name="asn1_005fread_005ftag"></a><dl>
1146 <dt><a name="index-asn1_005fread_005ftag"></a>Function: <em>int</em> <strong>asn1_read_tag</strong> <em>(asn1_node <var>root</var>, const char * <var>name</var>, int * <var>tagValue</var>, int * <var>classValue</var>)</em></dt>
1147 <dd><p><var>root</var>: pointer to a structure
1148 </p>
1149 <p><var>name</var>: the name of the element inside a structure.
1150 </p>
1151 <p><var>tagValue</var>: variable that will contain the TAG value.
1152 </p>
1153 <p><var>classValue</var>: variable that will specify the TAG type.
1154 </p>
1155 <p>Returns the TAG and the CLASS of one element inside a structure.
1156 CLASS can have one of these constants: <code>ASN1_CLASS_APPLICATION</code> ,
1157 <code>ASN1_CLASS_UNIVERSAL</code> , <code>ASN1_CLASS_PRIVATE</code>  or
1158 <code>ASN1_CLASS_CONTEXT_SPECIFIC</code> .
1159 </p>
1160 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if successful, <code>ASN1_ELEMENT_NOT_FOUND</code>  if
1161  <code>name</code> is not a valid element.
1162 </p></dd></dl>
1163
1164 <a name="asn1_005fread_005fnode_005fvalue-1"></a>
1165 <h4 class="subheading">asn1_read_node_value</h4>
1166 <a name="asn1_005fread_005fnode_005fvalue"></a><dl>
1167 <dt><a name="index-asn1_005fread_005fnode_005fvalue"></a>Function: <em>int</em> <strong>asn1_read_node_value</strong> <em>(asn1_node <var>node</var>, asn1_data_node_st * <var>data</var>)</em></dt>
1168 <dd><p><var>node</var>: pointer to a node.
1169 </p>
1170 <p><var>data</var>: a point to a asn1_data_node_st
1171 </p>
1172 <p>Returns the value a data node inside a asn1_node structure.
1173 The data returned should be handled as constant values.
1174 </p>
1175 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if the node exists.
1176 </p></dd></dl>
1177
1178
1179 <hr>
1180 <a name="DER-functions"></a>
1181 <div class="header">
1182 <p>
1183 Next: <a href="#Error-handling-functions" accesskey="n" rel="next">Error handling functions</a>, Previous: <a href="#ASN_002e1-field-functions" accesskey="p" rel="prev">ASN.1 field functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
1184 </div>
1185 <a name="DER-functions-1"></a>
1186 <h3 class="section">4.3 DER functions</h3>
1187
1188 <a name="asn1_005flength_005fder-1"></a>
1189 <h4 class="subheading">asn1_length_der</h4>
1190 <a name="asn1_005flength_005fder"></a><dl>
1191 <dt><a name="index-asn1_005flength_005fder"></a>Function: <em>void</em> <strong>asn1_length_der</strong> <em>(unsigned long int <var>len</var>, unsigned char * <var>der</var>, int * <var>der_len</var>)</em></dt>
1192 <dd><p><var>len</var>: value to convert.
1193 </p>
1194 <p><var>der</var>: buffer to hold the returned encoding (may be <code>NULL</code> ).
1195 </p>
1196 <p><var>der_len</var>: number of meaningful bytes of ANS (der[0]..der[der_len-1]).
1197 </p>
1198 <p>Creates the DER encoding of the provided length value.
1199 The  <code>der</code> buffer must have enough room for the output. The maximum
1200 length this function will encode is <code>ASN1_MAX_LENGTH_SIZE</code> .
1201 </p>
1202 <p>To know the size of the DER encoding use a <code>NULL</code>  value for  <code>der</code> .
1203 </p></dd></dl>
1204
1205 <a name="asn1_005foctet_005fder-1"></a>
1206 <h4 class="subheading">asn1_octet_der</h4>
1207 <a name="asn1_005foctet_005fder"></a><dl>
1208 <dt><a name="index-asn1_005foctet_005fder"></a>Function: <em>void</em> <strong>asn1_octet_der</strong> <em>(const unsigned char * <var>str</var>, int <var>str_len</var>, unsigned char * <var>der</var>, int * <var>der_len</var>)</em></dt>
1209 <dd><p><var>str</var>: the input data.
1210 </p>
1211 <p><var>str_len</var>: STR length (str[0]..str[*str_len-1]).
1212 </p>
1213 <p><var>der</var>: encoded string returned.
1214 </p>
1215 <p><var>der_len</var>: number of meaningful bytes of DER (der[0]..der[der_len-1]).
1216 </p>
1217 <p>Creates a length-value DER encoding for the input data.
1218 The DER encoding of the input data will be placed in the  <code>der</code> variable.
1219 </p>
1220 <p>Note that the OCTET STRING tag is not included in the output.
1221 </p>
1222 <p>This function does not return any value because it is expected
1223 that  <code>der_len</code> will contain enough bytes to store the string
1224 plus the DER encoding. The DER encoding size can be obtained using
1225 <code>asn1_length_der()</code> .
1226 </p></dd></dl>
1227
1228 <a name="asn1_005fencode_005fsimple_005fder-1"></a>
1229 <h4 class="subheading">asn1_encode_simple_der</h4>
1230 <a name="asn1_005fencode_005fsimple_005fder"></a><dl>
1231 <dt><a name="index-asn1_005fencode_005fsimple_005fder"></a>Function: <em>int</em> <strong>asn1_encode_simple_der</strong> <em>(unsigned int <var>etype</var>, const unsigned char * <var>str</var>, unsigned int <var>str_len</var>, unsigned char * <var>tl</var>, unsigned int * <var>tl_len</var>)</em></dt>
1232 <dd><p><var>etype</var>: The type of the string to be encoded (ASN1_ETYPE_)
1233 </p>
1234 <p><var>str</var>: the string data.
1235 </p>
1236 <p><var>str_len</var>: the string length
1237 </p>
1238 <p><var>tl</var>: the encoded tag and length
1239 </p>
1240 <p><var>tl_len</var>: the bytes of the  <code>tl</code> field
1241 </p>
1242 <p>Creates the DER encoding for various simple ASN.1 types like strings etc.
1243 It stores the tag and length in  <code>tl</code> , which should have space for at least
1244 <code>ASN1_MAX_TL_SIZE</code>  bytes. Initially  <code>tl_len</code> should contain the size of  <code>tl</code> .
1245 </p>
1246 <p>The complete DER encoding should consist of the value in  <code>tl</code> appended
1247 with the provided  <code>str</code> .
1248 </p>
1249 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if successful or an error value.
1250 </p></dd></dl>
1251
1252 <a name="asn1_005fbit_005fder-1"></a>
1253 <h4 class="subheading">asn1_bit_der</h4>
1254 <a name="asn1_005fbit_005fder"></a><dl>
1255 <dt><a name="index-asn1_005fbit_005fder"></a>Function: <em>void</em> <strong>asn1_bit_der</strong> <em>(const unsigned char * <var>str</var>, int <var>bit_len</var>, unsigned char * <var>der</var>, int * <var>der_len</var>)</em></dt>
1256 <dd><p><var>str</var>: BIT string.
1257 </p>
1258 <p><var>bit_len</var>: number of meaningful bits in STR.
1259 </p>
1260 <p><var>der</var>: string returned.
1261 </p>
1262 <p><var>der_len</var>: number of meaningful bytes of DER
1263 (der[0]..der[ans_len-1]).
1264 </p>
1265 <p>Creates a length-value DER encoding for the input data
1266 as it would have been for a BIT STRING.
1267 The DER encoded data will be copied in  <code>der</code> .
1268 </p>
1269 <p>Note that the BIT STRING tag is not included in the output.
1270 </p>
1271 <p>This function does not return any value because it is expected
1272 that  <code>der_len</code> will contain enough bytes to store the string
1273 plus the DER encoding. The DER encoding size can be obtained using
1274 <code>asn1_length_der()</code> .
1275 </p></dd></dl>
1276
1277 <a name="asn1_005fder_005fcoding-1"></a>
1278 <h4 class="subheading">asn1_der_coding</h4>
1279 <a name="asn1_005fder_005fcoding"></a><dl>
1280 <dt><a name="index-asn1_005fder_005fcoding"></a>Function: <em>int</em> <strong>asn1_der_coding</strong> <em>(asn1_node <var>element</var>, const char * <var>name</var>, void * <var>ider</var>, int * <var>len</var>, char * <var>ErrorDescription</var>)</em></dt>
1281 <dd><p><var>element</var>: pointer to an ASN1 element
1282 </p>
1283 <p><var>name</var>: the name of the structure you want to encode (it must be
1284 inside *POINTER).
1285 </p>
1286 <p><var>ider</var>: vector that will contain the DER encoding. DER must be a
1287 pointer to memory cells already allocated.
1288 </p>
1289 <p><var>len</var>: number of bytes of * <code>ider</code> :  <code>ider</code> [0].. <code>ider</code> [len-1], Initialy
1290 holds the sizeof of der vector.
1291 </p>
1292 <p><var>ErrorDescription</var>: return the error description or an empty
1293 string if success.
1294 </p>
1295 <p>Creates the DER encoding for the NAME structure (inside *POINTER
1296 structure).
1297 </p>
1298 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if DER encoding OK, <code>ASN1_ELEMENT_NOT_FOUND</code>
1299 if  <code>name</code> is not a valid element, <code>ASN1_VALUE_NOT_FOUND</code>  if there
1300 is an element without a value, <code>ASN1_MEM_ERROR</code>  if the  <code>ider</code> vector isn&rsquo;t big enough and in this case  <code>len</code> will contain the
1301 length needed.
1302 </p></dd></dl>
1303
1304 <a name="asn1_005fget_005flength_005fder-1"></a>
1305 <h4 class="subheading">asn1_get_length_der</h4>
1306 <a name="asn1_005fget_005flength_005fder"></a><dl>
1307 <dt><a name="index-asn1_005fget_005flength_005fder"></a>Function: <em>long</em> <strong>asn1_get_length_der</strong> <em>(const unsigned char * <var>der</var>, int <var>der_len</var>, int * <var>len</var>)</em></dt>
1308 <dd><p><var>der</var>: DER data to decode.
1309 </p>
1310 <p><var>der_len</var>: Length of DER data to decode.
1311 </p>
1312 <p><var>len</var>: Output variable containing the length of the DER length field.
1313 </p>
1314 <p>Extract a length field from DER data.
1315 </p>
1316 <p><strong>Returns:</strong> Return the decoded length value, or -1 on indefinite
1317 length, or -2 when the value was too big to fit in a int, or -4
1318 when the decoded length value plus  <code>len</code> would exceed  <code>der_len</code> .
1319 </p></dd></dl>
1320
1321 <a name="asn1_005fget_005ftag_005fder-1"></a>
1322 <h4 class="subheading">asn1_get_tag_der</h4>
1323 <a name="asn1_005fget_005ftag_005fder"></a><dl>
1324 <dt><a name="index-asn1_005fget_005ftag_005fder"></a>Function: <em>int</em> <strong>asn1_get_tag_der</strong> <em>(const unsigned char * <var>der</var>, int <var>der_len</var>, unsigned char * <var>cls</var>, int * <var>len</var>, unsigned long * <var>tag</var>)</em></dt>
1325 <dd><p><var>der</var>: DER data to decode.
1326 </p>
1327 <p><var>der_len</var>: Length of DER data to decode.
1328 </p>
1329 <p><var>cls</var>: Output variable containing decoded class.
1330 </p>
1331 <p><var>len</var>: Output variable containing the length of the DER TAG data.
1332 </p>
1333 <p><var>tag</var>: Output variable containing the decoded tag.
1334 </p>
1335 <p>Decode the class and TAG from DER code.
1336 </p>
1337 <p><strong>Returns:</strong> Returns <code>ASN1_SUCCESS</code>  on success, or an error.
1338 </p></dd></dl>
1339
1340 <a name="asn1_005fget_005flength_005fber-1"></a>
1341 <h4 class="subheading">asn1_get_length_ber</h4>
1342 <a name="asn1_005fget_005flength_005fber"></a><dl>
1343 <dt><a name="index-asn1_005fget_005flength_005fber"></a>Function: <em>long</em> <strong>asn1_get_length_ber</strong> <em>(const unsigned char * <var>ber</var>, int <var>ber_len</var>, int * <var>len</var>)</em></dt>
1344 <dd><p><var>ber</var>: BER data to decode.
1345 </p>
1346 <p><var>ber_len</var>: Length of BER data to decode.
1347 </p>
1348 <p><var>len</var>: Output variable containing the length of the BER length field.
1349 </p>
1350 <p>Extract a length field from BER data.  The difference to
1351 <code>asn1_get_length_der()</code>  is that this function will return a length
1352 even if the value has indefinite encoding.
1353 </p>
1354 <p><strong>Returns:</strong> Return the decoded length value, or negative value when
1355 the value was too big.
1356 </p>
1357 <p><strong>Since:</strong> 2.0
1358 </p></dd></dl>
1359
1360 <a name="asn1_005fget_005foctet_005fder-1"></a>
1361 <h4 class="subheading">asn1_get_octet_der</h4>
1362 <a name="asn1_005fget_005foctet_005fder"></a><dl>
1363 <dt><a name="index-asn1_005fget_005foctet_005fder"></a>Function: <em>int</em> <strong>asn1_get_octet_der</strong> <em>(const unsigned char * <var>der</var>, int <var>der_len</var>, int * <var>ret_len</var>, unsigned char * <var>str</var>, int <var>str_size</var>, int * <var>str_len</var>)</em></dt>
1364 <dd><p><var>der</var>: DER data to decode containing the OCTET SEQUENCE.
1365 </p>
1366 <p><var>der_len</var>: The length of the  <code>der</code> data to decode.
1367 </p>
1368 <p><var>ret_len</var>: Output variable containing the encoded length of the DER data.
1369 </p>
1370 <p><var>str</var>: Pre-allocated output buffer to put decoded OCTET SEQUENCE in.
1371 </p>
1372 <p><var>str_size</var>: Length of pre-allocated output buffer.
1373 </p>
1374 <p><var>str_len</var>: Output variable containing the length of the contents of the OCTET SEQUENCE.
1375 </p>
1376 <p>Extract an OCTET SEQUENCE from DER data. Note that this function
1377 expects the DER data past the tag field, i.e., the length and
1378 content octets.
1379 </p>
1380 <p><strong>Returns:</strong> Returns <code>ASN1_SUCCESS</code>  on success, or an error.
1381 </p></dd></dl>
1382
1383 <a name="asn1_005fget_005fobject_005fid_005fder-1"></a>
1384 <h4 class="subheading">asn1_get_object_id_der</h4>
1385 <a name="asn1_005fget_005fobject_005fid_005fder"></a><dl>
1386 <dt><a name="index-asn1_005fget_005fobject_005fid_005fder"></a>Function: <em>int</em> <strong>asn1_get_object_id_der</strong> <em>(const unsigned char * <var>der</var>, int <var>der_len</var>, int * <var>ret_len</var>, char * <var>str</var>, int <var>str_size</var>)</em></dt>
1387 <dd><p><var>der</var>: DER data to decode containing the OBJECT IDENTIFIER
1388 </p>
1389 <p><var>der_len</var>: Length of DER data to decode.
1390 </p>
1391 <p><var>ret_len</var>: Output variable containing the length of the DER data.
1392 </p>
1393 <p><var>str</var>: Pre-allocated output buffer to put the textual object id in.
1394 </p>
1395 <p><var>str_size</var>: Length of pre-allocated output buffer.
1396 </p>
1397 <p>Converts a DER encoded object identifier to its textual form.
1398 </p>
1399 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  on success, or an error.
1400 </p></dd></dl>
1401
1402 <a name="asn1_005fget_005fbit_005fder-1"></a>
1403 <h4 class="subheading">asn1_get_bit_der</h4>
1404 <a name="asn1_005fget_005fbit_005fder"></a><dl>
1405 <dt><a name="index-asn1_005fget_005fbit_005fder"></a>Function: <em>int</em> <strong>asn1_get_bit_der</strong> <em>(const unsigned char * <var>der</var>, int <var>der_len</var>, int * <var>ret_len</var>, unsigned char * <var>str</var>, int <var>str_size</var>, int * <var>bit_len</var>)</em></dt>
1406 <dd><p><var>der</var>: DER data to decode containing the BIT SEQUENCE.
1407 </p>
1408 <p><var>der_len</var>: Length of DER data to decode.
1409 </p>
1410 <p><var>ret_len</var>: Output variable containing the length of the DER data.
1411 </p>
1412 <p><var>str</var>: Pre-allocated output buffer to put decoded BIT SEQUENCE in.
1413 </p>
1414 <p><var>str_size</var>: Length of pre-allocated output buffer.
1415 </p>
1416 <p><var>bit_len</var>: Output variable containing the size of the BIT SEQUENCE.
1417 </p>
1418 <p>Extract a BIT SEQUENCE from DER data.
1419 </p>
1420 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  on success, or an error.
1421 </p></dd></dl>
1422
1423 <a name="asn1_005fder_005fdecoding2-1"></a>
1424 <h4 class="subheading">asn1_der_decoding2</h4>
1425 <a name="asn1_005fder_005fdecoding2"></a><dl>
1426 <dt><a name="index-asn1_005fder_005fdecoding2"></a>Function: <em>int</em> <strong>asn1_der_decoding2</strong> <em>(asn1_node * <var>element</var>, const void * <var>ider</var>, int * <var>max_ider_len</var>, unsigned int <var>flags</var>, char * <var>errorDescription</var>)</em></dt>
1427 <dd><p><var>element</var>: pointer to an ASN1 structure.
1428 </p>
1429 <p><var>ider</var>: vector that contains the DER encoding.
1430 </p>
1431 <p><var>max_ider_len</var>: pointer to an integer giving the information about the
1432 maximal number of bytes occupied by * <code>ider</code> . The real size of the DER
1433 encoding is returned through this pointer.
1434 </p>
1435 <p><var>flags</var>: flags controlling the behaviour of the function.
1436 </p>
1437 <p><var>errorDescription</var>: null-terminated string contains details when an
1438 error occurred.
1439 </p>
1440 <p>Fill the structure * <code>element</code> with values of a DER encoding string. The
1441 structure must just be created with function <code>asn1_create_element()</code> .
1442 </p>
1443 <p>If <code>ASN1_DECODE_FLAG_ALLOW_PADDING</code>  flag is set then the function will ignore
1444 padding after the decoded DER data. Upon a successful return the value of
1445 * <code>max_ider_len</code> will be set to the number of bytes decoded.
1446 </p>
1447 <p>If <code>ASN1_DECODE_FLAG_STRICT_DER</code>  flag is set then the function will
1448 not decode any BER-encoded elements.
1449 </p>
1450 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if DER encoding OK, <code>ASN1_ELEMENT_NOT_FOUND</code>
1451 if  <code>ELEMENT</code> is <code>NULL</code> , and <code>ASN1_TAG_ERROR</code>  or
1452 <code>ASN1_DER_ERROR</code>  if the der encoding doesn&rsquo;t match the structure
1453 name (* <code>ELEMENT</code> deleted).
1454 </p></dd></dl>
1455
1456 <a name="asn1_005fder_005fdecoding-1"></a>
1457 <h4 class="subheading">asn1_der_decoding</h4>
1458 <a name="asn1_005fder_005fdecoding"></a><dl>
1459 <dt><a name="index-asn1_005fder_005fdecoding"></a>Function: <em>int</em> <strong>asn1_der_decoding</strong> <em>(asn1_node * <var>element</var>, const void * <var>ider</var>, int <var>ider_len</var>, char * <var>errorDescription</var>)</em></dt>
1460 <dd><p><var>element</var>: pointer to an ASN1 structure.
1461 </p>
1462 <p><var>ider</var>: vector that contains the DER encoding.
1463 </p>
1464 <p><var>ider_len</var>: number of bytes of * <code>ider</code> :  <code>ider</code> [0].. <code>ider</code> [len-1].
1465 </p>
1466 <p><var>errorDescription</var>: null-terminated string contains details when an
1467 error occurred.
1468 </p>
1469 <p>Fill the structure * <code>element</code> with values of a DER encoding
1470 string. The structure must just be created with function
1471 <code>asn1_create_element()</code> .
1472 </p>
1473 <p>Note that the * <code>element</code> variable is provided as a pointer for
1474 historical reasons.
1475 </p>
1476 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if DER encoding OK, <code>ASN1_ELEMENT_NOT_FOUND</code>
1477 if  <code>ELEMENT</code> is <code>NULL</code> , and <code>ASN1_TAG_ERROR</code>  or
1478 <code>ASN1_DER_ERROR</code>  if the der encoding doesn&rsquo;t match the structure
1479 name (* <code>ELEMENT</code> deleted).
1480 </p></dd></dl>
1481
1482 <a name="asn1_005fder_005fdecoding_005felement-1"></a>
1483 <h4 class="subheading">asn1_der_decoding_element</h4>
1484 <a name="asn1_005fder_005fdecoding_005felement"></a><dl>
1485 <dt><a name="index-asn1_005fder_005fdecoding_005felement"></a>Function: <em>int</em> <strong>asn1_der_decoding_element</strong> <em>(asn1_node * <var>structure</var>, const char * <var>elementName</var>, const void * <var>ider</var>, int <var>len</var>, char * <var>errorDescription</var>)</em></dt>
1486 <dd><p><var>structure</var>: pointer to an ASN1 structure
1487 </p>
1488 <p><var>elementName</var>: name of the element to fill
1489 </p>
1490 <p><var>ider</var>: vector that contains the DER encoding of the whole structure.
1491 </p>
1492 <p><var>len</var>: number of bytes of *der: der[0]..der[len-1]
1493 </p>
1494 <p><var>errorDescription</var>: null-terminated string contains details when an
1495 error occurred.
1496 </p>
1497 <p>Fill the element named  <code>ELEMENTNAME</code> with values of a DER encoding
1498 string.  The structure must just be created with function
1499 <code>asn1_create_element()</code> .  The DER vector must contain the encoding
1500 string of the whole  <code>STRUCTURE</code> .  If an error occurs during the
1501 decoding procedure, the * <code>STRUCTURE</code> is deleted and set equal to
1502 <code>NULL</code> .
1503 </p>
1504 <p>This function is deprecated and may just be an alias to asn1_der_decoding
1505 in future versions. Use <code>asn1_der_decoding()</code>  instead.
1506 </p>
1507 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if DER encoding OK, <code>ASN1_ELEMENT_NOT_FOUND</code>
1508 if ELEMENT is <code>NULL</code>  or  <code>elementName</code> == NULL, and
1509 <code>ASN1_TAG_ERROR</code>  or <code>ASN1_DER_ERROR</code>  if the der encoding doesn&rsquo;t
1510 match the structure  <code>structure</code> (*ELEMENT deleted).
1511 </p></dd></dl>
1512
1513 <a name="asn1_005fder_005fdecoding_005fstartEnd-1"></a>
1514 <h4 class="subheading">asn1_der_decoding_startEnd</h4>
1515 <a name="asn1_005fder_005fdecoding_005fstartEnd"></a><dl>
1516 <dt><a name="index-asn1_005fder_005fdecoding_005fstartEnd"></a>Function: <em>int</em> <strong>asn1_der_decoding_startEnd</strong> <em>(asn1_node <var>element</var>, const void * <var>ider</var>, int <var>ider_len</var>, const char * <var>name_element</var>, int * <var>start</var>, int * <var>end</var>)</em></dt>
1517 <dd><p><var>element</var>: pointer to an ASN1 element
1518 </p>
1519 <p><var>ider</var>: vector that contains the DER encoding.
1520 </p>
1521 <p><var>ider_len</var>: number of bytes of * <code>ider</code> :  <code>ider</code> [0].. <code>ider</code> [len-1]
1522 </p>
1523 <p><var>name_element</var>: an element of NAME structure.
1524 </p>
1525 <p><var>start</var>: the position of the first byte of NAME_ELEMENT decoding
1526 ( <code>ider</code> [*start])
1527 </p>
1528 <p><var>end</var>: the position of the last byte of NAME_ELEMENT decoding
1529 ( <code>ider</code> [*end])
1530 </p>
1531 <p>Find the start and end point of an element in a DER encoding
1532 string. I mean that if you have a der encoding and you have already
1533 used the function <code>asn1_der_decoding()</code>  to fill a structure, it may
1534 happen that you want to find the piece of string concerning an
1535 element of the structure.
1536 </p>
1537 <p>One example is the sequence &quot;tbsCertificate&quot; inside an X509
1538 certificate.
1539 </p>
1540 <p>Note that since libtasn1 3.7 the  <code>ider</code> and  <code>ider_len</code> parameters
1541 can be omitted, if the element is already decoded using <code>asn1_der_decoding()</code> .
1542 </p>
1543 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if DER encoding OK, <code>ASN1_ELEMENT_NOT_FOUND</code>
1544 if ELEMENT is <code>asn1_node</code>  EMPTY or  <code>name_element</code> is not a valid
1545 element, <code>ASN1_TAG_ERROR</code>  or <code>ASN1_DER_ERROR</code>  if the der encoding
1546 doesn&rsquo;t match the structure ELEMENT.
1547 </p></dd></dl>
1548
1549 <a name="asn1_005fexpand_005fany_005fdefined_005fby-1"></a>
1550 <h4 class="subheading">asn1_expand_any_defined_by</h4>
1551 <a name="asn1_005fexpand_005fany_005fdefined_005fby"></a><dl>
1552 <dt><a name="index-asn1_005fexpand_005fany_005fdefined_005fby"></a>Function: <em>int</em> <strong>asn1_expand_any_defined_by</strong> <em>(asn1_node <var>definitions</var>, asn1_node * <var>element</var>)</em></dt>
1553 <dd><p><var>definitions</var>: ASN1 definitions
1554 </p>
1555 <p><var>element</var>: pointer to an ASN1 structure
1556 </p>
1557 <p>Expands every &quot;ANY DEFINED BY&quot; element of a structure created from
1558 a DER decoding process (asn1_der_decoding function). The element
1559 ANY must be defined by an OBJECT IDENTIFIER. The type used to
1560 expand the element ANY is the first one following the definition of
1561 the actual value of the OBJECT IDENTIFIER.
1562 </p>
1563 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if Substitution OK, <code>ASN1_ERROR_TYPE_ANY</code>  if
1564 some &quot;ANY DEFINED BY&quot; element couldn&rsquo;t be expanded due to a
1565 problem in OBJECT_ID -&gt; TYPE association, or other error codes
1566 depending on DER decoding.
1567 </p></dd></dl>
1568
1569 <a name="asn1_005fexpand_005foctet_005fstring-1"></a>
1570 <h4 class="subheading">asn1_expand_octet_string</h4>
1571 <a name="asn1_005fexpand_005foctet_005fstring"></a><dl>
1572 <dt><a name="index-asn1_005fexpand_005foctet_005fstring"></a>Function: <em>int</em> <strong>asn1_expand_octet_string</strong> <em>(asn1_node <var>definitions</var>, asn1_node * <var>element</var>, const char * <var>octetName</var>, const char * <var>objectName</var>)</em></dt>
1573 <dd><p><var>definitions</var>: ASN1 definitions
1574 </p>
1575 <p><var>element</var>: pointer to an ASN1 structure
1576 </p>
1577 <p><var>octetName</var>: name of the OCTECT STRING field to expand.
1578 </p>
1579 <p><var>objectName</var>: name of the OBJECT IDENTIFIER field to use to define
1580 the type for expansion.
1581 </p>
1582 <p>Expands an &quot;OCTET STRING&quot; element of a structure created from a DER
1583 decoding process (the <code>asn1_der_decoding()</code>  function).  The type used
1584 for expansion is the first one following the definition of the
1585 actual value of the OBJECT IDENTIFIER indicated by OBJECTNAME.
1586 </p>
1587 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if substitution OK, <code>ASN1_ELEMENT_NOT_FOUND</code>
1588 if  <code>objectName</code> or  <code>octetName</code> are not correct,
1589 <code>ASN1_VALUE_NOT_VALID</code>  if it wasn&rsquo;t possible to find the type to
1590 use for expansion, or other errors depending on DER decoding.
1591 </p></dd></dl>
1592
1593 <a name="asn1_005fdecode_005fsimple_005fder-1"></a>
1594 <h4 class="subheading">asn1_decode_simple_der</h4>
1595 <a name="asn1_005fdecode_005fsimple_005fder"></a><dl>
1596 <dt><a name="index-asn1_005fdecode_005fsimple_005fder"></a>Function: <em>int</em> <strong>asn1_decode_simple_der</strong> <em>(unsigned int <var>etype</var>, const unsigned char * <var>der</var>, unsigned int <var>_der_len</var>, const unsigned char ** <var>str</var>, unsigned int * <var>str_len</var>)</em></dt>
1597 <dd><p><var>etype</var>: The type of the string to be encoded (ASN1_ETYPE_)
1598 </p>
1599 <p><var>der</var>: the encoded string
1600 </p>
1601 <p><var>_der_len</var>: the bytes of the encoded string
1602 </p>
1603 <p><var>str</var>: a pointer to the data
1604 </p>
1605 <p><var>str_len</var>: the length of the data
1606 </p>
1607 <p>Decodes a simple DER encoded type (e.g. a string, which is not constructed).
1608 The output is a pointer inside the  <code>der</code> .
1609 </p>
1610 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if successful or an error value.
1611 </p></dd></dl>
1612
1613 <a name="asn1_005fdecode_005fsimple_005fber-1"></a>
1614 <h4 class="subheading">asn1_decode_simple_ber</h4>
1615 <a name="asn1_005fdecode_005fsimple_005fber"></a><dl>
1616 <dt><a name="index-asn1_005fdecode_005fsimple_005fber"></a>Function: <em>int</em> <strong>asn1_decode_simple_ber</strong> <em>(unsigned int <var>etype</var>, const unsigned char * <var>der</var>, unsigned int <var>_der_len</var>, unsigned char ** <var>str</var>, unsigned int * <var>str_len</var>, unsigned int * <var>ber_len</var>)</em></dt>
1617 <dd><p><var>etype</var>: The type of the string to be encoded (ASN1_ETYPE_)
1618 </p>
1619 <p><var>der</var>: the encoded string
1620 </p>
1621 <p><var>_der_len</var>: the bytes of the encoded string
1622 </p>
1623 <p><var>str</var>: a pointer to the data
1624 </p>
1625 <p><var>str_len</var>: the length of the data
1626 </p>
1627 <p><var>ber_len</var>: the total length occupied by BER (may be <code>NULL</code> )
1628 </p>
1629 <p>Decodes a BER encoded type. The output is an allocated value
1630 of the data. This decodes BER STRINGS only. Other types are
1631 decoded as DER.
1632 </p>
1633 <p><strong>Returns:</strong> <code>ASN1_SUCCESS</code>  if successful or an error value.
1634 </p></dd></dl>
1635
1636
1637 <hr>
1638 <a name="Error-handling-functions"></a>
1639 <div class="header">
1640 <p>
1641 Next: <a href="#Auxilliary-functions" accesskey="n" rel="next">Auxilliary functions</a>, Previous: <a href="#DER-functions" accesskey="p" rel="prev">DER functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
1642 </div>
1643 <a name="Error-handling-functions-1"></a>
1644 <h3 class="section">4.4 Error handling functions</h3>
1645
1646 <a name="asn1_005fperror-1"></a>
1647 <h4 class="subheading">asn1_perror</h4>
1648 <a name="asn1_005fperror"></a><dl>
1649 <dt><a name="index-asn1_005fperror"></a>Function: <em>void</em> <strong>asn1_perror</strong> <em>(int <var>error</var>)</em></dt>
1650 <dd><p><var>error</var>: is an error returned by a libtasn1 function.
1651 </p>
1652 <p>Prints a string to stderr with a description of an error.  This
1653 function is like <code>perror()</code> .  The only difference is that it accepts
1654 an error returned by a libtasn1 function.
1655 </p>
1656 <p><strong>Since:</strong> 1.6
1657 </p></dd></dl>
1658
1659 <a name="asn1_005fstrerror-1"></a>
1660 <h4 class="subheading">asn1_strerror</h4>
1661 <a name="asn1_005fstrerror"></a><dl>
1662 <dt><a name="index-asn1_005fstrerror"></a>Function: <em>const char *</em> <strong>asn1_strerror</strong> <em>(int <var>error</var>)</em></dt>
1663 <dd><p><var>error</var>: is an error returned by a libtasn1 function.
1664 </p>
1665 <p>Returns a string with a description of an error.  This function is
1666 similar to strerror.  The only difference is that it accepts an
1667 error (number) returned by a libtasn1 function.
1668 </p>
1669 <p><strong>Returns:</strong> Pointer to static zero-terminated string describing error
1670 code.
1671 </p>
1672 <p><strong>Since:</strong> 1.6
1673 </p></dd></dl>
1674
1675
1676 <hr>
1677 <a name="Auxilliary-functions"></a>
1678 <div class="header">
1679 <p>
1680 Previous: <a href="#Error-handling-functions" accesskey="p" rel="prev">Error handling functions</a>, Up: <a href="#Function-reference" accesskey="u" rel="up">Function reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
1681 </div>
1682 <a name="Auxilliary-functions-1"></a>
1683 <h3 class="section">4.5 Auxilliary functions</h3>
1684
1685 <a name="asn1_005ffind_005fnode-1"></a>
1686 <h4 class="subheading">asn1_find_node</h4>
1687 <a name="asn1_005ffind_005fnode"></a><dl>
1688 <dt><a name="index-asn1_005ffind_005fnode"></a>Function: <em>asn1_node</em> <strong>asn1_find_node</strong> <em>(asn1_node <var>pointer</var>, const char * <var>name</var>)</em></dt>
1689 <dd><p><var>pointer</var>: NODE_ASN element pointer.
1690 </p>
1691 <p><var>name</var>: null terminated string with the element&rsquo;s name to find.
1692 </p>
1693 <p>Searches for an element called  <code>name</code> starting from  <code>pointer</code> .  The
1694 name is composed by differents identifiers separated by dots.  When
1695 * <code>pointer</code> has a name, the first identifier must be the name of
1696 * <code>pointer</code> , otherwise it must be the name of one child of * <code>pointer</code> .
1697 </p>
1698 <p><strong>Returns:</strong> the search result, or <code>NULL</code>  if not found.
1699 </p></dd></dl>
1700
1701 <a name="asn1_005fcheck_005fversion-1"></a>
1702 <h4 class="subheading">asn1_check_version</h4>
1703 <a name="asn1_005fcheck_005fversion"></a><dl>
1704 <dt><a name="index-asn1_005fcheck_005fversion"></a>Function: <em>const char *</em> <strong>asn1_check_version</strong> <em>(const char * <var>req_version</var>)</em></dt>
1705 <dd><p><var>req_version</var>: Required version number, or <code>NULL</code> .
1706 </p>
1707 <p>Check that the version of the library is at minimum the
1708 requested one and return the version string; return <code>NULL</code>  if the
1709 condition is not satisfied.  If a <code>NULL</code>  is passed to this function,
1710 no check is done, but the version string is simply returned.
1711 </p>
1712 <p>See <code>ASN1_VERSION</code>  for a suitable  <code>req_version</code> string.
1713 </p>
1714 <p><strong>Returns:</strong> Version string of run-time library, or <code>NULL</code>  if the
1715 run-time library does not meet the required version number.
1716 </p></dd></dl>
1717
1718
1719 <hr>
1720 <a name="Copying-Information"></a>
1721 <div class="header">
1722 <p>
1723 Next: <a href="#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="#Function-reference" accesskey="p" rel="prev">Function reference</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
1724 </div>
1725 <a name="Copying-Information-1"></a>
1726 <h2 class="appendix">Appendix A Copying Information</h2>
1727
1728 <table class="menu" border="0" cellspacing="0">
1729 <tr><td align="left" valign="top">&bull; <a href="#GNU-Free-Documentation-License" accesskey="1">GNU Free Documentation License</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">License for copying this manual.
1730 </td></tr>
1731 </table>
1732
1733 <hr>
1734 <a name="GNU-Free-Documentation-License"></a>
1735 <div class="header">
1736 <p>
1737 Up: <a href="#Copying-Information" accesskey="u" rel="up">Copying Information</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
1738 </div>
1739 <a name="GNU-Free-Documentation-License-1"></a>
1740 <h3 class="appendixsec">A.1 GNU Free Documentation License</h3>
1741
1742 <a name="index-FDL_002c-GNU-Free-Documentation-License"></a>
1743
1744 <div align="center">Version 1.3, 3 November 2008
1745 </div>
1746
1747 <div class="display">
1748 <pre class="display">Copyright &copy; 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
1749 <a href="http://fsf.org/">http://fsf.org/</a>
1750
1751 Everyone is permitted to copy and distribute verbatim copies
1752 of this license document, but changing it is not allowed.
1753 </pre></div>
1754
1755 <ol>
1756 <li> PREAMBLE
1757
1758 <p>The purpose of this License is to make a manual, textbook, or other
1759 functional and useful document <em>free</em> in the sense of freedom: to
1760 assure everyone the effective freedom to copy and redistribute it,
1761 with or without modifying it, either commercially or noncommercially.
1762 Secondarily, this License preserves for the author and publisher a way
1763 to get credit for their work, while not being considered responsible
1764 for modifications made by others.
1765 </p>
1766 <p>This License is a kind of &ldquo;copyleft&rdquo;, which means that derivative
1767 works of the document must themselves be free in the same sense.  It
1768 complements the GNU General Public License, which is a copyleft
1769 license designed for free software.
1770 </p>
1771 <p>We have designed this License in order to use it for manuals for free
1772 software, because free software needs free documentation: a free
1773 program should come with manuals providing the same freedoms that the
1774 software does.  But this License is not limited to software manuals;
1775 it can be used for any textual work, regardless of subject matter or
1776 whether it is published as a printed book.  We recommend this License
1777 principally for works whose purpose is instruction or reference.
1778 </p>
1779 </li><li> APPLICABILITY AND DEFINITIONS
1780
1781 <p>This License applies to any manual or other work, in any medium, that
1782 contains a notice placed by the copyright holder saying it can be
1783 distributed under the terms of this License.  Such a notice grants a
1784 world-wide, royalty-free license, unlimited in duration, to use that
1785 work under the conditions stated herein.  The &ldquo;Document&rdquo;, below,
1786 refers to any such manual or work.  Any member of the public is a
1787 licensee, and is addressed as &ldquo;you&rdquo;.  You accept the license if you
1788 copy, modify or distribute the work in a way requiring permission
1789 under copyright law.
1790 </p>
1791 <p>A &ldquo;Modified Version&rdquo; of the Document means any work containing the
1792 Document or a portion of it, either copied verbatim, or with
1793 modifications and/or translated into another language.
1794 </p>
1795 <p>A &ldquo;Secondary Section&rdquo; is a named appendix or a front-matter section
1796 of the Document that deals exclusively with the relationship of the
1797 publishers or authors of the Document to the Document&rsquo;s overall
1798 subject (or to related matters) and contains nothing that could fall
1799 directly within that overall subject.  (Thus, if the Document is in
1800 part a textbook of mathematics, a Secondary Section may not explain
1801 any mathematics.)  The relationship could be a matter of historical
1802 connection with the subject or with related matters, or of legal,
1803 commercial, philosophical, ethical or political position regarding
1804 them.
1805 </p>
1806 <p>The &ldquo;Invariant Sections&rdquo; are certain Secondary Sections whose titles
1807 are designated, as being those of Invariant Sections, in the notice
1808 that says that the Document is released under this License.  If a
1809 section does not fit the above definition of Secondary then it is not
1810 allowed to be designated as Invariant.  The Document may contain zero
1811 Invariant Sections.  If the Document does not identify any Invariant
1812 Sections then there are none.
1813 </p>
1814 <p>The &ldquo;Cover Texts&rdquo; are certain short passages of text that are listed,
1815 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
1816 the Document is released under this License.  A Front-Cover Text may
1817 be at most 5 words, and a Back-Cover Text may be at most 25 words.
1818 </p>
1819 <p>A &ldquo;Transparent&rdquo; copy of the Document means a machine-readable copy,
1820 represented in a format whose specification is available to the
1821 general public, that is suitable for revising the document
1822 straightforwardly with generic text editors or (for images composed of
1823 pixels) generic paint programs or (for drawings) some widely available
1824 drawing editor, and that is suitable for input to text formatters or
1825 for automatic translation to a variety of formats suitable for input
1826 to text formatters.  A copy made in an otherwise Transparent file
1827 format whose markup, or absence of markup, has been arranged to thwart
1828 or discourage subsequent modification by readers is not Transparent.
1829 An image format is not Transparent if used for any substantial amount
1830 of text.  A copy that is not &ldquo;Transparent&rdquo; is called &ldquo;Opaque&rdquo;.
1831 </p>
1832 <p>Examples of suitable formats for Transparent copies include plain
1833 ASCII without markup, Texinfo input format, LaTeX input
1834 format, SGML or XML using a publicly available
1835 DTD, and standard-conforming simple HTML,
1836 PostScript or PDF designed for human modification.  Examples
1837 of transparent image formats include PNG, XCF and
1838 JPG.  Opaque formats include proprietary formats that can be
1839 read and edited only by proprietary word processors, SGML or
1840 XML for which the DTD and/or processing tools are
1841 not generally available, and the machine-generated HTML,
1842 PostScript or PDF produced by some word processors for
1843 output purposes only.
1844 </p>
1845 <p>The &ldquo;Title Page&rdquo; means, for a printed book, the title page itself,
1846 plus such following pages as are needed to hold, legibly, the material
1847 this License requires to appear in the title page.  For works in
1848 formats which do not have any title page as such, &ldquo;Title Page&rdquo; means
1849 the text near the most prominent appearance of the work&rsquo;s title,
1850 preceding the beginning of the body of the text.
1851 </p>
1852 <p>The &ldquo;publisher&rdquo; means any person or entity that distributes copies
1853 of the Document to the public.
1854 </p>
1855 <p>A section &ldquo;Entitled XYZ&rdquo; means a named subunit of the Document whose
1856 title either is precisely XYZ or contains XYZ in parentheses following
1857 text that translates XYZ in another language.  (Here XYZ stands for a
1858 specific section name mentioned below, such as &ldquo;Acknowledgements&rdquo;,
1859 &ldquo;Dedications&rdquo;, &ldquo;Endorsements&rdquo;, or &ldquo;History&rdquo;.)  To &ldquo;Preserve the Title&rdquo;
1860 of such a section when you modify the Document means that it remains a
1861 section &ldquo;Entitled XYZ&rdquo; according to this definition.
1862 </p>
1863 <p>The Document may include Warranty Disclaimers next to the notice which
1864 states that this License applies to the Document.  These Warranty
1865 Disclaimers are considered to be included by reference in this
1866 License, but only as regards disclaiming warranties: any other
1867 implication that these Warranty Disclaimers may have is void and has
1868 no effect on the meaning of this License.
1869 </p>
1870 </li><li> VERBATIM COPYING
1871
1872 <p>You may copy and distribute the Document in any medium, either
1873 commercially or noncommercially, provided that this License, the
1874 copyright notices, and the license notice saying this License applies
1875 to the Document are reproduced in all copies, and that you add no other
1876 conditions whatsoever to those of this License.  You may not use
1877 technical measures to obstruct or control the reading or further
1878 copying of the copies you make or distribute.  However, you may accept
1879 compensation in exchange for copies.  If you distribute a large enough
1880 number of copies you must also follow the conditions in section 3.
1881 </p>
1882 <p>You may also lend copies, under the same conditions stated above, and
1883 you may publicly display copies.
1884 </p>
1885 </li><li> COPYING IN QUANTITY
1886
1887 <p>If you publish printed copies (or copies in media that commonly have
1888 printed covers) of the Document, numbering more than 100, and the
1889 Document&rsquo;s license notice requires Cover Texts, you must enclose the
1890 copies in covers that carry, clearly and legibly, all these Cover
1891 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
1892 the back cover.  Both covers must also clearly and legibly identify
1893 you as the publisher of these copies.  The front cover must present
1894 the full title with all words of the title equally prominent and
1895 visible.  You may add other material on the covers in addition.
1896 Copying with changes limited to the covers, as long as they preserve
1897 the title of the Document and satisfy these conditions, can be treated
1898 as verbatim copying in other respects.
1899 </p>
1900 <p>If the required texts for either cover are too voluminous to fit
1901 legibly, you should put the first ones listed (as many as fit
1902 reasonably) on the actual cover, and continue the rest onto adjacent
1903 pages.
1904 </p>
1905 <p>If you publish or distribute Opaque copies of the Document numbering
1906 more than 100, you must either include a machine-readable Transparent
1907 copy along with each Opaque copy, or state in or with each Opaque copy
1908 a computer-network location from which the general network-using
1909 public has access to download using public-standard network protocols
1910 a complete Transparent copy of the Document, free of added material.
1911 If you use the latter option, you must take reasonably prudent steps,
1912 when you begin distribution of Opaque copies in quantity, to ensure
1913 that this Transparent copy will remain thus accessible at the stated
1914 location until at least one year after the last time you distribute an
1915 Opaque copy (directly or through your agents or retailers) of that
1916 edition to the public.
1917 </p>
1918 <p>It is requested, but not required, that you contact the authors of the
1919 Document well before redistributing any large number of copies, to give
1920 them a chance to provide you with an updated version of the Document.
1921 </p>
1922 </li><li> MODIFICATIONS
1923
1924 <p>You may copy and distribute a Modified Version of the Document under
1925 the conditions of sections 2 and 3 above, provided that you release
1926 the Modified Version under precisely this License, with the Modified
1927 Version filling the role of the Document, thus licensing distribution
1928 and modification of the Modified Version to whoever possesses a copy
1929 of it.  In addition, you must do these things in the Modified Version:
1930 </p>
1931 <ol>
1932 <li> Use in the Title Page (and on the covers, if any) a title distinct
1933 from that of the Document, and from those of previous versions
1934 (which should, if there were any, be listed in the History section
1935 of the Document).  You may use the same title as a previous version
1936 if the original publisher of that version gives permission.
1937
1938 </li><li> List on the Title Page, as authors, one or more persons or entities
1939 responsible for authorship of the modifications in the Modified
1940 Version, together with at least five of the principal authors of the
1941 Document (all of its principal authors, if it has fewer than five),
1942 unless they release you from this requirement.
1943
1944 </li><li> State on the Title page the name of the publisher of the
1945 Modified Version, as the publisher.
1946
1947 </li><li> Preserve all the copyright notices of the Document.
1948
1949 </li><li> Add an appropriate copyright notice for your modifications
1950 adjacent to the other copyright notices.
1951
1952 </li><li> Include, immediately after the copyright notices, a license notice
1953 giving the public permission to use the Modified Version under the
1954 terms of this License, in the form shown in the Addendum below.
1955
1956 </li><li> Preserve in that license notice the full lists of Invariant Sections
1957 and required Cover Texts given in the Document&rsquo;s license notice.
1958
1959 </li><li> Include an unaltered copy of this License.
1960
1961 </li><li> Preserve the section Entitled &ldquo;History&rdquo;, Preserve its Title, and add
1962 to it an item stating at least the title, year, new authors, and
1963 publisher of the Modified Version as given on the Title Page.  If
1964 there is no section Entitled &ldquo;History&rdquo; in the Document, create one
1965 stating the title, year, authors, and publisher of the Document as
1966 given on its Title Page, then add an item describing the Modified
1967 Version as stated in the previous sentence.
1968
1969 </li><li> Preserve the network location, if any, given in the Document for
1970 public access to a Transparent copy of the Document, and likewise
1971 the network locations given in the Document for previous versions
1972 it was based on.  These may be placed in the &ldquo;History&rdquo; section.
1973 You may omit a network location for a work that was published at
1974 least four years before the Document itself, or if the original
1975 publisher of the version it refers to gives permission.
1976
1977 </li><li> For any section Entitled &ldquo;Acknowledgements&rdquo; or &ldquo;Dedications&rdquo;, Preserve
1978 the Title of the section, and preserve in the section all the
1979 substance and tone of each of the contributor acknowledgements and/or
1980 dedications given therein.
1981
1982 </li><li> Preserve all the Invariant Sections of the Document,
1983 unaltered in their text and in their titles.  Section numbers
1984 or the equivalent are not considered part of the section titles.
1985
1986 </li><li> Delete any section Entitled &ldquo;Endorsements&rdquo;.  Such a section
1987 may not be included in the Modified Version.
1988
1989 </li><li> Do not retitle any existing section to be Entitled &ldquo;Endorsements&rdquo; or
1990 to conflict in title with any Invariant Section.
1991
1992 </li><li> Preserve any Warranty Disclaimers.
1993 </li></ol>
1994
1995 <p>If the Modified Version includes new front-matter sections or
1996 appendices that qualify as Secondary Sections and contain no material
1997 copied from the Document, you may at your option designate some or all
1998 of these sections as invariant.  To do this, add their titles to the
1999 list of Invariant Sections in the Modified Version&rsquo;s license notice.
2000 These titles must be distinct from any other section titles.
2001 </p>
2002 <p>You may add a section Entitled &ldquo;Endorsements&rdquo;, provided it contains
2003 nothing but endorsements of your Modified Version by various
2004 parties&mdash;for example, statements of peer review or that the text has
2005 been approved by an organization as the authoritative definition of a
2006 standard.
2007 </p>
2008 <p>You may add a passage of up to five words as a Front-Cover Text, and a
2009 passage of up to 25 words as a Back-Cover Text, to the end of the list
2010 of Cover Texts in the Modified Version.  Only one passage of
2011 Front-Cover Text and one of Back-Cover Text may be added by (or
2012 through arrangements made by) any one entity.  If the Document already
2013 includes a cover text for the same cover, previously added by you or
2014 by arrangement made by the same entity you are acting on behalf of,
2015 you may not add another; but you may replace the old one, on explicit
2016 permission from the previous publisher that added the old one.
2017 </p>
2018 <p>The author(s) and publisher(s) of the Document do not by this License
2019 give permission to use their names for publicity for or to assert or
2020 imply endorsement of any Modified Version.
2021 </p>
2022 </li><li> COMBINING DOCUMENTS
2023
2024 <p>You may combine the Document with other documents released under this
2025 License, under the terms defined in section 4 above for modified
2026 versions, provided that you include in the combination all of the
2027 Invariant Sections of all of the original documents, unmodified, and
2028 list them all as Invariant Sections of your combined work in its
2029 license notice, and that you preserve all their Warranty Disclaimers.
2030 </p>
2031 <p>The combined work need only contain one copy of this License, and
2032 multiple identical Invariant Sections may be replaced with a single
2033 copy.  If there are multiple Invariant Sections with the same name but
2034 different contents, make the title of each such section unique by
2035 adding at the end of it, in parentheses, the name of the original
2036 author or publisher of that section if known, or else a unique number.
2037 Make the same adjustment to the section titles in the list of
2038 Invariant Sections in the license notice of the combined work.
2039 </p>
2040 <p>In the combination, you must combine any sections Entitled &ldquo;History&rdquo;
2041 in the various original documents, forming one section Entitled
2042 &ldquo;History&rdquo;; likewise combine any sections Entitled &ldquo;Acknowledgements&rdquo;,
2043 and any sections Entitled &ldquo;Dedications&rdquo;.  You must delete all
2044 sections Entitled &ldquo;Endorsements.&rdquo;
2045 </p>
2046 </li><li> COLLECTIONS OF DOCUMENTS
2047
2048 <p>You may make a collection consisting of the Document and other documents
2049 released under this License, and replace the individual copies of this
2050 License in the various documents with a single copy that is included in
2051 the collection, provided that you follow the rules of this License for
2052 verbatim copying of each of the documents in all other respects.
2053 </p>
2054 <p>You may extract a single document from such a collection, and distribute
2055 it individually under this License, provided you insert a copy of this
2056 License into the extracted document, and follow this License in all
2057 other respects regarding verbatim copying of that document.
2058 </p>
2059 </li><li> AGGREGATION WITH INDEPENDENT WORKS
2060
2061 <p>A compilation of the Document or its derivatives with other separate
2062 and independent documents or works, in or on a volume of a storage or
2063 distribution medium, is called an &ldquo;aggregate&rdquo; if the copyright
2064 resulting from the compilation is not used to limit the legal rights
2065 of the compilation&rsquo;s users beyond what the individual works permit.
2066 When the Document is included in an aggregate, this License does not
2067 apply to the other works in the aggregate which are not themselves
2068 derivative works of the Document.
2069 </p>
2070 <p>If the Cover Text requirement of section 3 is applicable to these
2071 copies of the Document, then if the Document is less than one half of
2072 the entire aggregate, the Document&rsquo;s Cover Texts may be placed on
2073 covers that bracket the Document within the aggregate, or the
2074 electronic equivalent of covers if the Document is in electronic form.
2075 Otherwise they must appear on printed covers that bracket the whole
2076 aggregate.
2077 </p>
2078 </li><li> TRANSLATION
2079
2080 <p>Translation is considered a kind of modification, so you may
2081 distribute translations of the Document under the terms of section 4.
2082 Replacing Invariant Sections with translations requires special
2083 permission from their copyright holders, but you may include
2084 translations of some or all Invariant Sections in addition to the
2085 original versions of these Invariant Sections.  You may include a
2086 translation of this License, and all the license notices in the
2087 Document, and any Warranty Disclaimers, provided that you also include
2088 the original English version of this License and the original versions
2089 of those notices and disclaimers.  In case of a disagreement between
2090 the translation and the original version of this License or a notice
2091 or disclaimer, the original version will prevail.
2092 </p>
2093 <p>If a section in the Document is Entitled &ldquo;Acknowledgements&rdquo;,
2094 &ldquo;Dedications&rdquo;, or &ldquo;History&rdquo;, the requirement (section 4) to Preserve
2095 its Title (section 1) will typically require changing the actual
2096 title.
2097 </p>
2098 </li><li> TERMINATION
2099
2100 <p>You may not copy, modify, sublicense, or distribute the Document
2101 except as expressly provided under this License.  Any attempt
2102 otherwise to copy, modify, sublicense, or distribute it is void, and
2103 will automatically terminate your rights under this License.
2104 </p>
2105 <p>However, if you cease all violation of this License, then your license
2106 from a particular copyright holder is reinstated (a) provisionally,
2107 unless and until the copyright holder explicitly and finally
2108 terminates your license, and (b) permanently, if the copyright holder
2109 fails to notify you of the violation by some reasonable means prior to
2110 60 days after the cessation.
2111 </p>
2112 <p>Moreover, your license from a particular copyright holder is
2113 reinstated permanently if the copyright holder notifies you of the
2114 violation by some reasonable means, this is the first time you have
2115 received notice of violation of this License (for any work) from that
2116 copyright holder, and you cure the violation prior to 30 days after
2117 your receipt of the notice.
2118 </p>
2119 <p>Termination of your rights under this section does not terminate the
2120 licenses of parties who have received copies or rights from you under
2121 this License.  If your rights have been terminated and not permanently
2122 reinstated, receipt of a copy of some or all of the same material does
2123 not give you any rights to use it.
2124 </p>
2125 </li><li> FUTURE REVISIONS OF THIS LICENSE
2126
2127 <p>The Free Software Foundation may publish new, revised versions
2128 of the GNU Free Documentation License from time to time.  Such new
2129 versions will be similar in spirit to the present version, but may
2130 differ in detail to address new problems or concerns.  See
2131 <a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>.
2132 </p>
2133 <p>Each version of the License is given a distinguishing version number.
2134 If the Document specifies that a particular numbered version of this
2135 License &ldquo;or any later version&rdquo; applies to it, you have the option of
2136 following the terms and conditions either of that specified version or
2137 of any later version that has been published (not as a draft) by the
2138 Free Software Foundation.  If the Document does not specify a version
2139 number of this License, you may choose any version ever published (not
2140 as a draft) by the Free Software Foundation.  If the Document
2141 specifies that a proxy can decide which future versions of this
2142 License can be used, that proxy&rsquo;s public statement of acceptance of a
2143 version permanently authorizes you to choose that version for the
2144 Document.
2145 </p>
2146 </li><li> RELICENSING
2147
2148 <p>&ldquo;Massive Multiauthor Collaboration Site&rdquo; (or &ldquo;MMC Site&rdquo;) means any
2149 World Wide Web server that publishes copyrightable works and also
2150 provides prominent facilities for anybody to edit those works.  A
2151 public wiki that anybody can edit is an example of such a server.  A
2152 &ldquo;Massive Multiauthor Collaboration&rdquo; (or &ldquo;MMC&rdquo;) contained in the
2153 site means any set of copyrightable works thus published on the MMC
2154 site.
2155 </p>
2156 <p>&ldquo;CC-BY-SA&rdquo; means the Creative Commons Attribution-Share Alike 3.0
2157 license published by Creative Commons Corporation, a not-for-profit
2158 corporation with a principal place of business in San Francisco,
2159 California, as well as future copyleft versions of that license
2160 published by that same organization.
2161 </p>
2162 <p>&ldquo;Incorporate&rdquo; means to publish or republish a Document, in whole or
2163 in part, as part of another Document.
2164 </p>
2165 <p>An MMC is &ldquo;eligible for relicensing&rdquo; if it is licensed under this
2166 License, and if all works that were first published under this License
2167 somewhere other than this MMC, and subsequently incorporated in whole
2168 or in part into the MMC, (1) had no cover texts or invariant sections,
2169 and (2) were thus incorporated prior to November 1, 2008.
2170 </p>
2171 <p>The operator of an MMC Site may republish an MMC contained in the site
2172 under CC-BY-SA on the same site at any time before August 1, 2009,
2173 provided the MMC is eligible for relicensing.
2174 </p>
2175 </li></ol>
2176
2177 <a name="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></a>
2178 <h3 class="heading">ADDENDUM: How to use this License for your documents</h3>
2179
2180 <p>To use this License in a document you have written, include a copy of
2181 the License in the document and put the following copyright and
2182 license notices just after the title page:
2183 </p>
2184 <div class="smallexample">
2185 <pre class="smallexample">  Copyright (C)  <var>year</var>  <var>your name</var>.
2186   Permission is granted to copy, distribute and/or modify this document
2187   under the terms of the GNU Free Documentation License, Version 1.3
2188   or any later version published by the Free Software Foundation;
2189   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
2190   Texts.  A copy of the license is included in the section entitled ``GNU
2191   Free Documentation License''.
2192 </pre></div>
2193
2194 <p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
2195 replace the &ldquo;with&hellip;Texts.&rdquo; line with this:
2196 </p>
2197 <div class="smallexample">
2198 <pre class="smallexample">    with the Invariant Sections being <var>list their titles</var>, with
2199     the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts
2200     being <var>list</var>.
2201 </pre></div>
2202
2203 <p>If you have Invariant Sections without Cover Texts, or some other
2204 combination of the three, merge those two alternatives to suit the
2205 situation.
2206 </p>
2207 <p>If your document contains nontrivial examples of program code, we
2208 recommend releasing these examples in parallel under your choice of
2209 free software license, such as the GNU General Public License,
2210 to permit their use in free software.
2211 </p>
2212
2213 <hr>
2214 <a name="Concept-Index"></a>
2215 <div class="header">
2216 <p>
2217 Next: <a href="#Function-and-Data-Index" accesskey="n" rel="next">Function and Data Index</a>, Previous: <a href="#Copying-Information" accesskey="p" rel="prev">Copying Information</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
2218 </div>
2219 <a name="Concept-Index-1"></a>
2220 <h2 class="unnumbered">Concept Index</h2>
2221
2222 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
2223  &nbsp;
2224 <a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
2225  &nbsp;
2226 <a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
2227  &nbsp;
2228 <a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
2229  &nbsp;
2230 <a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>
2231  &nbsp;
2232 <a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
2233  &nbsp;
2234 <a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
2235  &nbsp;
2236 </td></tr></table>
2237 <table class="index-cp" border="0">
2238 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
2239 <tr><td colspan="4"> <hr></td></tr>
2240 <tr><th><a name="Concept-Index_cp_letter-A">A</a></th><td></td><td></td></tr>
2241 <tr><td></td><td valign="top"><a href="#index-ASN_002e1-schema">ASN.1 schema</a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-syntax">ASN.1 syntax</a></td></tr>
2242 <tr><td></td><td valign="top"><a href="#index-asn1Coding-program">asn1Coding program</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-asn1Coding">Invoking asn1Coding</a></td></tr>
2243 <tr><td></td><td valign="top"><a href="#index-asn1Decoding-program">asn1Decoding program</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-asn1Decoding">Invoking asn1Decoding</a></td></tr>
2244 <tr><td></td><td valign="top"><a href="#index-asn1Parser-program">asn1Parser program</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Invoking-asn1Parser">Invoking asn1Parser</a></td></tr>
2245 <tr><td colspan="4"> <hr></td></tr>
2246 <tr><th><a name="Concept-Index_cp_letter-F">F</a></th><td></td><td></td></tr>
2247 <tr><td></td><td valign="top"><a href="#index-FDL_002c-GNU-Free-Documentation-License">FDL, GNU Free Documentation License</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a></td></tr>
2248 <tr><td></td><td valign="top"><a href="#index-Future-developments">Future developments</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Future-developments">Future developments</a></td></tr>
2249 <tr><td colspan="4"> <hr></td></tr>
2250 <tr><th><a name="Concept-Index_cp_letter-H">H</a></th><td></td><td></td></tr>
2251 <tr><td></td><td valign="top"><a href="#index-Header-file-libtasn1_002eh">Header file libtasn1.h</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Library-Notes">Library Notes</a></td></tr>
2252 <tr><td colspan="4"> <hr></td></tr>
2253 <tr><th><a name="Concept-Index_cp_letter-M">M</a></th><td></td><td></td></tr>
2254 <tr><td></td><td valign="top"><a href="#index-Main-type-asn1_005fnode">Main type asn1_node</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Library-Notes">Library Notes</a></td></tr>
2255 <tr><td colspan="4"> <hr></td></tr>
2256 <tr><th><a name="Concept-Index_cp_letter-P">P</a></th><td></td><td></td></tr>
2257 <tr><td></td><td valign="top"><a href="#index-Porting">Porting</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Introduction">Introduction</a></td></tr>
2258 <tr><td colspan="4"> <hr></td></tr>
2259 <tr><th><a name="Concept-Index_cp_letter-S">S</a></th><td></td><td></td></tr>
2260 <tr><td></td><td valign="top"><a href="#index-Supported-ASN_002e1-types_002c-list-of">Supported ASN.1 types, list of</a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-syntax">ASN.1 syntax</a></td></tr>
2261 <tr><td colspan="4"> <hr></td></tr>
2262 <tr><th><a name="Concept-Index_cp_letter-T">T</a></th><td></td><td></td></tr>
2263 <tr><td></td><td valign="top"><a href="#index-threads">threads</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Introduction">Introduction</a></td></tr>
2264 <tr><td colspan="4"> <hr></td></tr>
2265 </table>
2266 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a>
2267  &nbsp;
2268 <a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a>
2269  &nbsp;
2270 <a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a>
2271  &nbsp;
2272 <a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a>
2273  &nbsp;
2274 <a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a>
2275  &nbsp;
2276 <a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a>
2277  &nbsp;
2278 <a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a>
2279  &nbsp;
2280 </td></tr></table>
2281
2282 <hr>
2283 <a name="Function-and-Data-Index"></a>
2284 <div class="header">
2285 <p>
2286 Previous: <a href="#Concept-Index" accesskey="p" rel="prev">Concept Index</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Concept-Index" title="Index" rel="index">Index</a>]</p>
2287 </div>
2288 <a name="Function-and-Data-Index-1"></a>
2289 <h2 class="unnumbered">Function and Data Index</h2>
2290
2291 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Function-and-Data-Index_fn_letter-A"><b>A</b></a>
2292  &nbsp;
2293 </td></tr></table>
2294 <table class="index-fn" border="0">
2295 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
2296 <tr><td colspan="4"> <hr></td></tr>
2297 <tr><th><a name="Function-and-Data-Index_fn_letter-A">A</a></th><td></td><td></td></tr>
2298 <tr><td></td><td valign="top"><a href="#index-asn1_005farray2tree"><code>asn1_array2tree</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2299 <tr><td></td><td valign="top"><a href="#index-asn1_005fbit_005fder"><code>asn1_bit_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2300 <tr><td></td><td valign="top"><a href="#index-asn1_005fcheck_005fversion"><code>asn1_check_version</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Auxilliary-functions">Auxilliary functions</a></td></tr>
2301 <tr><td></td><td valign="top"><a href="#index-asn1_005fcopy_005fnode"><code>asn1_copy_node</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2302 <tr><td></td><td valign="top"><a href="#index-asn1_005fcreate_005felement"><code>asn1_create_element</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2303 <tr><td></td><td valign="top"><a href="#index-asn1_005fdecode_005fsimple_005fber"><code>asn1_decode_simple_ber</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2304 <tr><td></td><td valign="top"><a href="#index-asn1_005fdecode_005fsimple_005fder"><code>asn1_decode_simple_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2305 <tr><td></td><td valign="top"><a href="#index-asn1_005fdelete_005felement"><code>asn1_delete_element</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2306 <tr><td></td><td valign="top"><a href="#index-asn1_005fdelete_005fstructure"><code>asn1_delete_structure</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2307 <tr><td></td><td valign="top"><a href="#index-asn1_005fdelete_005fstructure2"><code>asn1_delete_structure2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2308 <tr><td></td><td valign="top"><a href="#index-asn1_005fder_005fcoding"><code>asn1_der_coding</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2309 <tr><td></td><td valign="top"><a href="#index-asn1_005fder_005fdecoding"><code>asn1_der_decoding</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2310 <tr><td></td><td valign="top"><a href="#index-asn1_005fder_005fdecoding2"><code>asn1_der_decoding2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2311 <tr><td></td><td valign="top"><a href="#index-asn1_005fder_005fdecoding_005felement"><code>asn1_der_decoding_element</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2312 <tr><td></td><td valign="top"><a href="#index-asn1_005fder_005fdecoding_005fstartEnd"><code>asn1_der_decoding_startEnd</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2313 <tr><td></td><td valign="top"><a href="#index-asn1_005fdup_005fnode"><code>asn1_dup_node</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2314 <tr><td></td><td valign="top"><a href="#index-asn1_005fencode_005fsimple_005fder"><code>asn1_encode_simple_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2315 <tr><td></td><td valign="top"><a href="#index-asn1_005fexpand_005fany_005fdefined_005fby"><code>asn1_expand_any_defined_by</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2316 <tr><td></td><td valign="top"><a href="#index-asn1_005fexpand_005foctet_005fstring"><code>asn1_expand_octet_string</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2317 <tr><td></td><td valign="top"><a href="#index-asn1_005ffind_005fnode"><code>asn1_find_node</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Auxilliary-functions">Auxilliary functions</a></td></tr>
2318 <tr><td></td><td valign="top"><a href="#index-asn1_005ffind_005fstructure_005ffrom_005foid"><code>asn1_find_structure_from_oid</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2319 <tr><td></td><td valign="top"><a href="#index-asn1_005fget_005fbit_005fder"><code>asn1_get_bit_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2320 <tr><td></td><td valign="top"><a href="#index-asn1_005fget_005flength_005fber"><code>asn1_get_length_ber</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2321 <tr><td></td><td valign="top"><a href="#index-asn1_005fget_005flength_005fder"><code>asn1_get_length_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2322 <tr><td></td><td valign="top"><a href="#index-asn1_005fget_005fobject_005fid_005fder"><code>asn1_get_object_id_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2323 <tr><td></td><td valign="top"><a href="#index-asn1_005fget_005foctet_005fder"><code>asn1_get_octet_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2324 <tr><td></td><td valign="top"><a href="#index-asn1_005fget_005ftag_005fder"><code>asn1_get_tag_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2325 <tr><td></td><td valign="top"><a href="#index-asn1_005flength_005fder"><code>asn1_length_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2326 <tr><td></td><td valign="top"><a href="#index-asn1_005fnumber_005fof_005felements"><code>asn1_number_of_elements</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2327 <tr><td></td><td valign="top"><a href="#index-asn1_005foctet_005fder"><code>asn1_octet_der</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DER-functions">DER functions</a></td></tr>
2328 <tr><td></td><td valign="top"><a href="#index-asn1_005fparser2array"><code>asn1_parser2array</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-schema-functions">ASN.1 schema functions</a></td></tr>
2329 <tr><td></td><td valign="top"><a href="#index-asn1_005fparser2tree"><code>asn1_parser2tree</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-schema-functions">ASN.1 schema functions</a></td></tr>
2330 <tr><td></td><td valign="top"><a href="#index-asn1_005fperror"><code>asn1_perror</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-handling-functions">Error handling functions</a></td></tr>
2331 <tr><td></td><td valign="top"><a href="#index-asn1_005fprint_005fstructure"><code>asn1_print_structure</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2332 <tr><td></td><td valign="top"><a href="#index-asn1_005fread_005fnode_005fvalue"><code>asn1_read_node_value</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2333 <tr><td></td><td valign="top"><a href="#index-asn1_005fread_005ftag"><code>asn1_read_tag</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2334 <tr><td></td><td valign="top"><a href="#index-asn1_005fread_005fvalue"><code>asn1_read_value</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2335 <tr><td></td><td valign="top"><a href="#index-asn1_005fread_005fvalue_005ftype"><code>asn1_read_value_type</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2336 <tr><td></td><td valign="top"><a href="#index-asn1_005fstrerror"><code>asn1_strerror</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Error-handling-functions">Error handling functions</a></td></tr>
2337 <tr><td></td><td valign="top"><a href="#index-asn1_005fwrite_005fvalue"><code>asn1_write_value</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASN_002e1-field-functions">ASN.1 field functions</a></td></tr>
2338 <tr><td colspan="4"> <hr></td></tr>
2339 </table>
2340 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Function-and-Data-Index_fn_letter-A"><b>A</b></a>
2341  &nbsp;
2342 </td></tr></table>
2343
2344 <hr>
2345
2346
2347
2348 </body>
2349 </html>