← Back to branch summary

~ubuntu-branches/ubuntu/precise/libtasn1-3/precise-updates

« back to all changes in this revision

Viewing changes to doc/libtasn1.html

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Metzler
  • Date: 2010-03-15 19:16:34 UTC
  • mfrom: (1.2.5 upstream) (6.1.3 sid)
  • Revision ID: james.westby@ubuntu.com-20100315191634-015aowhjrrvlwjnm
http://bugs.debian.org/554343
* New upstream version.
* Do not run test-suite when cross compiling. Closes: #554343

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/libtasn1.html
1
1
<html lang="en">
2
2
<head>
3
 
<title>GNU Libtasn1 2.4</title>
 
3
<title>GNU Libtasn1 2.5</title>
4
4
<meta http-equiv="Content-Type" content="text/html">
5
 
<meta name="description" content="GNU Libtasn1 2.4">
 
5
<meta name="description" content="GNU Libtasn1 2.5">
6
6
<meta name="generator" content="makeinfo 4.13">
7
7
<link title="Top" rel="top" href="#Top">
8
8
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
9
9
<!--
10
10
This manual is for GNU Libtasn1
11
 
(version 2.4, 18 January 2010),
 
11
(version 2.5, 18 January 2010),
12
12
which is a library for Abstract Syntax Notation One (ASN.1) and
13
13
Distinguish Encoding Rules (DER) manipulation.
14
14
 
79
79
--></style>
80
80
</head>
81
81
<body>
82
 
<h1 class="settitle">GNU Libtasn1 2.4</h1>
 
82
<h1 class="settitle">GNU Libtasn1 2.5</h1>
83
83
<div class="contents">
84
84
<h2>Table of Contents</h2>
85
85
<ul>
128
128
<h2 class="unnumbered">Libtasn1</h2>
129
129
 
130
130
<p>This manual is for GNU Libtasn1
131
 
(version 2.4, 18 January 2010),
 
131
(version 2.5, 18 January 2010),
132
132
which is a library for Abstract Syntax Notation One (ASN.1) and
133
133
Distinguish Encoding Rules (DER) manipulation.
134
134
 
535
535
        <p><var>errorDescription</var>: return the error description or an empty
536
536
string if success.
537
537
 
538
 
        <p>Creates the structures needed to manage the definitions included
539
 
in *FILE_NAME file.
540
 
 
541
 
        <p><strong>Returns:</strong>
542
 
<strong>ASN1_SUCCESS:</strong> The file has a correct syntax and every identifier
543
 
is known.
544
 
 
545
 
        <p><strong>ASN1_ELEMENT_NOT_EMPTY:</strong> *POINTER not ASN1_TYPE_EMPTY.
546
 
 
547
 
        <p><strong>ASN1_FILE_NOT_FOUND:</strong> An error occured while opening FILE_NAME.
548
 
 
549
 
        <p><strong>ASN1_SYNTAX_ERROR:</strong> The syntax is not correct.
550
 
 
551
 
        <p><strong>ASN1_IDENTIFIER_NOT_FOUND:</strong> In the file there is an identifier that
552
 
is not defined.
553
 
 
554
 
        <p><strong>ASN1_NAME_TOO_LONG:</strong> In the file there is an identifier whith more
555
 
than ASN1_MAX_NAME_SIZE characters. 
556
 
</p></blockquote></div>
 
538
        <p>Function used to start the parse algorithm.  Creates the structures
 
539
needed to manage the definitions included in <code>file_name</code> file.
 
540
 
 
541
        <p><strong>Returns:</strong> </p></blockquote></div>
557
542
 
558
543
<h4 class="subheading">asn1_parser2array</h4>
559
544
 
572
557
        <p><var>errorDescription</var>: return the error description or an empty
573
558
string if success.
574
559
 
575
 
        <p>Creates a file containing a C vector to use to manage the
576
 
definitions included in *INPUTFILENAME file. If *INPUTFILENAME is
577
 
"/aa/bb/xx.yy" and OUTPUTFILENAME is NULL, the file created is
578
 
"/aa/bb/xx_asn1_tab.c".  If VECTORNAME is NULL the vector name
 
560
        <p>Function that generates a C structure from an ASN1 file.  Creates a
 
561
file containing a C vector to use to manage the definitions
 
562
included in <code>inputFileName</code> file. If <code>inputFileName</code> is
 
563
"/aa/bb/xx.yy" and <code>outputFileName</code> is <code>NULL</code>, the file created is
 
564
"/aa/bb/xx_asn1_tab.c".  If <code>vectorName</code> is <code>NULL</code> the vector name
579
565
will be "xx_asn1_tab".
580
566
 
581
 
        <p><strong>Returns:</strong>
582
 
<strong>ASN1_SUCCESS:</strong> The file has a correct syntax and every identifier
583
 
is known.
584
 
 
585
 
        <p><strong>ASN1_FILE_NOT_FOUND:</strong> An error occured while opening FILE_NAME.
586
 
 
587
 
        <p><strong>ASN1_SYNTAX_ERROR:</strong> The syntax is not correct.
588
 
 
589
 
        <p><strong>ASN1_IDENTIFIER_NOT_FOUND:</strong> In the file there is an identifier that
590
 
is not defined.
591
 
 
592
 
        <p><strong>ASN1_NAME_TOO_LONG:</strong> In the file there is an identifier whith more
593
 
than ASN1_MAX_NAME_SIZE characters. 
594
 
</p></blockquote></div>
 
567
        <p><strong>Returns:</strong> </p></blockquote></div>
595
568
 
596
569
<div class="node">
597
570
<a name="ASN.1-field-functions"></a>
621
594
        <p>Creates the structures needed to manage the ASN.1 definitions. 
622
595
<code>array</code> is a vector created by <code>asn1_parser2array()</code>.
623
596
 
624
 
        <p><strong>Returns:</strong>
625
 
<strong>ASN1_SUCCESS:</strong> Structure created correctly.
626
 
 
627
 
        <p><strong>ASN1_ELEMENT_NOT_EMPTY:</strong> *<code>definitions</code> not ASN1_TYPE_EMPTY.
628
 
 
629
 
        <p><strong>ASN1_IDENTIFIER_NOT_FOUND:</strong> In the file there is an identifier that
630
 
is not defined (see <code>errorDescription</code> for more information).
631
 
 
632
 
        <p><strong>ASN1_ARRAY_ERROR:</strong> The array pointed by <code>array</code> is wrong. 
633
 
</p></blockquote></div>
 
597
        <p><strong>Returns:</strong> </p></blockquote></div>
634
598
 
635
599
<h4 class="subheading">asn1_delete_structure</h4>
636
600
 
643
607
        <p>Deletes the structure *<code>structure</code>.  At the end, *<code>structure</code> is set
644
608
to ASN1_TYPE_EMPTY.
645
609
 
646
 
        <p><strong>Returns:</strong>
647
 
<strong>ASN1_SUCCESS:</strong> Everything OK.
648
 
 
649
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> *<code>structure</code> was ASN1_TYPE_EMPTY. 
650
 
</p></blockquote></div>
 
610
        <p><strong>Returns:</strong> </p></blockquote></div>
651
611
 
652
612
<h4 class="subheading">asn1_delete_element</h4>
653
613
 
662
622
 
663
623
        <p>Deletes the element named *<code>element_name</code> inside *<code>structure</code>.
664
624
 
665
 
        <p><strong>Returns:</strong>
666
 
<strong>ASN1_SUCCESS:</strong> Everything OK.
667
 
 
668
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> The name element was not found. 
669
 
</p></blockquote></div>
 
625
        <p><strong>Returns:</strong> </p></blockquote></div>
670
626
 
671
627
<h4 class="subheading">asn1_create_element</h4>
672
628
 
684
640
        <p>Creates a structure of type <code>source_name</code>.  Example using
685
641
"pkix.asn":
686
642
 
687
 
        <p>rc = asn1_create_element(cert_def, "PKIX1.Certificate",
688
 
certptr);
689
 
 
690
 
        <p><strong>Returns:</strong>
691
 
<strong>ASN1_SUCCESS:</strong> Creation OK.
692
 
 
693
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> SOURCE_NAME isn't known
694
 
</p></blockquote></div>
 
643
        <p>rc = asn1_create_element(cert_def, "PKIX1.Certificate", certptr);
 
644
 
 
645
        <p><strong>Returns:</strong> </p></blockquote></div>
695
646
 
696
647
<h4 class="subheading">asn1_print_structure</h4>
697
648
 
728
679
        <p>Counts the number of elements of a sub-structure called NAME with
729
680
names equal to "?1","?2", ...
730
681
 
731
 
        <p><strong>Returns:</strong>
732
 
<strong>ASN1_SUCCESS:</strong> Creation OK.
733
 
 
734
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> NAME isn't known.
735
 
 
736
 
        <p><strong>ASN1_GENERIC_ERROR:</strong> Pointer num equal to NULL. 
737
 
</p></blockquote></div>
 
682
        <p><strong>Returns:</strong> </p></blockquote></div>
738
683
 
739
684
<h4 class="subheading">asn1_find_structure_from_oid</h4>
740
685
 
748
693
 
749
694
        <p>Search the structure that is defined just after an OID definition.
750
695
 
751
 
        <p><strong>Returns:</strong> NULL when OIDVALUE not found, otherwise the pointer to a
752
 
constant string that contains the element name defined just
753
 
after the OID. 
 
696
        <p><strong>Returns:</strong> <code>NULL</code> when <code>oidValue</code> not found, otherwise the pointer to a
 
697
constant string that contains the element name defined just after
 
698
the OID. 
754
699
</p></blockquote></div>
755
700
 
756
701
<h4 class="subheading">asn1_copy_node</h4>
769
714
 
770
715
        <p>Create a deep copy of a ASN1_TYPE variable.
771
716
 
772
 
        <p><strong>Return value:</strong> Return ASN1_SUCCESS on success. 
 
717
        <p><strong>Return value:</strong> Return <code>ASN1_SUCCESS</code> on success. 
773
718
</p></blockquote></div>
774
719
 
775
720
<h4 class="subheading">asn1_write_value</h4>
880
825
        <p>result=asn1_write_value(cert,
881
826
"tbsCertificate.subject.rdnSequence.?LAST", "NEW", 1);
882
827
 
883
 
        <p><strong>Returns:</strong>
884
 
<strong>ASN1_SUCCESS:</strong> Set value OK.
885
 
 
886
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> NAME is not a valid element.
887
 
 
888
 
        <p><strong>ASN1_VALUE_NOT_VALID:</strong> VALUE has a wrong format. 
889
 
</p></blockquote></div>
 
828
        <p><strong>Returns:</strong> </p></blockquote></div>
890
829
 
891
830
<h4 class="subheading">asn1_read_value</h4>
892
831
 
949
888
        <p><strong>ANY:</strong> If NAME indicates an any type, VALUE will indicate the DER
950
889
encoding of the structure actually used.
951
890
 
952
 
        <p><strong>Returns:</strong>
953
 
<strong>ASN1_SUCCESS:</strong> Set value OK.
954
 
 
955
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> NAME is not a valid element.
956
 
 
957
 
        <p><strong>ASN1_VALUE_NOT_FOUND:</strong> There isn't any value for the element selected.
958
 
 
959
 
        <p><strong>ASN1_MEM_ERROR:</strong> The value vector isn't big enough to store the result. 
960
 
In this case LEN will contain the number of bytes needed. 
961
 
</p></blockquote></div>
 
891
        <p><strong>Returns:</strong> </p></blockquote></div>
962
892
 
963
893
<h4 class="subheading">asn1_read_tag</h4>
964
894
 
980
910
<code>ASN1_CLASS_UNIVERSAL</code>, <code>ASN1_CLASS_PRIVATE</code> or
981
911
<code>ASN1_CLASS_CONTEXT_SPECIFIC</code>.
982
912
 
983
 
        <p><strong>Returns:</strong>
984
 
<strong>ASN1_SUCCESS:</strong> Set value OK.
985
 
 
986
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> NAME is not a valid element. 
987
 
</p></blockquote></div>
 
913
        <p><strong>Returns:</strong> </p></blockquote></div>
988
914
 
989
915
<div class="node">
990
916
<a name="DER-functions"></a>
1069
995
        <p>Creates the DER encoding for the NAME structure (inside *POINTER
1070
996
structure).
1071
997
 
1072
 
        <p><strong>Returns:</strong>
1073
 
<strong>ASN1_SUCCESS:</strong> DER encoding OK.
1074
 
 
1075
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> NAME is not a valid element.
1076
 
 
1077
 
        <p><strong>ASN1_VALUE_NOT_FOUND:</strong> There is an element without a value.
1078
 
 
1079
 
        <p><strong>ASN1_MEM_ERROR:</strong> <code>ider</code> vector isn't big enough. Also in this case
1080
 
LEN will contain the length needed. 
1081
 
</p></blockquote></div>
 
998
        <p><strong>Returns:</strong> </p></blockquote></div>
1082
999
 
1083
1000
<h4 class="subheading">asn1_get_length_der</h4>
1084
1001
 
1116
1033
 
1117
1034
        <p>Decode the class and TAG from DER code.
1118
1035
 
1119
 
        <p><strong>Return value:</strong> Returns ASN1_SUCCESS on success, or an error. 
 
1036
        <p><strong>Return value:</strong> Returns <code>ASN1_SUCCESS</code> on success, or an error. 
1120
1037
</p></blockquote></div>
1121
1038
 
1122
1039
<h4 class="subheading">asn1_get_length_ber</h4>
1161
1078
 
1162
1079
        <p>Extract an OCTET SEQUENCE from DER data.
1163
1080
 
1164
 
        <p><strong>Return value:</strong> Returns ASN1_SUCCESS on success, or an error. 
 
1081
        <p><strong>Return value:</strong> Returns <code>ASN1_SUCCESS</code> on success, or an error. 
1165
1082
</p></blockquote></div>
1166
1083
 
1167
1084
<h4 class="subheading">asn1_get_bit_der</h4>
1184
1101
 
1185
1102
        <p>Extract a BIT SEQUENCE from DER data.
1186
1103
 
1187
 
        <p><strong>Return value:</strong> Return ASN1_SUCCESS on success, or an error. 
 
1104
        <p><strong>Return value:</strong> Return <code>ASN1_SUCCESS</code> on success, or an error. 
1188
1105
</p></blockquote></div>
1189
1106
 
1190
1107
<h4 class="subheading">asn1_der_decoding</h4>
1208
1125
procedure, the *ELEMENT is deleted and set equal to
1209
1126
<code>ASN1_TYPE_EMPTY</code>.
1210
1127
 
1211
 
        <p><strong>Returns:</strong>
1212
 
<strong>ASN1_SUCCESS:</strong> DER encoding OK.
1213
 
 
1214
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> ELEMENT is ASN1_TYPE_EMPTY.
1215
 
 
1216
 
        <p>ASN1_TAG_ERROR,ASN1_DER_ERROR: The der encoding doesn't match
1217
 
the structure NAME. *ELEMENT deleted. 
1218
 
</p></blockquote></div>
 
1128
        <p><strong>Returns:</strong> </p></blockquote></div>
1219
1129
 
1220
1130
<h4 class="subheading">asn1_der_decoding_element</h4>
1221
1131
 
1241
1151
decoding procedure, the *STRUCTURE is deleted and set equal to
1242
1152
<code>ASN1_TYPE_EMPTY</code>.
1243
1153
 
1244
 
        <p><strong>Returns:</strong>
1245
 
<strong>ASN1_SUCCESS:</strong> DER encoding OK.
1246
 
 
1247
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> ELEMENT is ASN1_TYPE_EMPTY or
1248
 
elementName == NULL.
1249
 
 
1250
 
        <p>ASN1_TAG_ERROR,ASN1_DER_ERROR: The der encoding doesn't match
1251
 
the structure STRUCTURE. *ELEMENT deleted. 
1252
 
</p></blockquote></div>
 
1154
        <p><strong>Returns:</strong> </p></blockquote></div>
1253
1155
 
1254
1156
<h4 class="subheading">asn1_der_decoding_startEnd</h4>
1255
1157
 
1272
1174
(<code>ider</code>[*end])
1273
1175
 
1274
1176
        <p>Find the start and end point of an element in a DER encoding
1275
 
string. I mean that if you have a der encoding and you have
1276
 
already used the function "asn1_der_decoding" to fill a structure,
1277
 
it may happen that you want to find the piece of string concerning
1278
 
an element of the structure.
 
1177
string. I mean that if you have a der encoding and you have already
 
1178
used the function "asn1_der_decoding" to fill a structure, it may
 
1179
happen that you want to find the piece of string concerning an
 
1180
element of the structure.
1279
1181
 
1280
1182
        <p><strong>Example:</strong> the sequence "tbsCertificate" inside an X509 certificate.
1281
1183
 
1282
 
        <p><strong>Returns:</strong>
1283
 
<strong>ASN1_SUCCESS:</strong> DER encoding OK.
1284
 
 
1285
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> ELEMENT is ASN1_TYPE EMPTY or
1286
 
NAME_ELEMENT is not a valid element.
1287
 
 
1288
 
        <p>ASN1_TAG_ERROR,ASN1_DER_ERROR: the der encoding doesn't match
1289
 
the structure ELEMENT. 
1290
 
</p></blockquote></div>
 
1184
        <p><strong>Returns:</strong> </p></blockquote></div>
1291
1185
 
1292
1186
<h4 class="subheading">asn1_expand_any_defined_by</h4>
1293
1187
 
1300
1194
        <p><var>element</var>: pointer to an ASN1 structure
1301
1195
 
1302
1196
        <p>Expands every "ANY DEFINED BY" element of a structure created from
1303
 
a DER decoding process (asn1_der_decoding function). The element ANY
1304
 
must be defined by an OBJECT IDENTIFIER. The type used to expand
1305
 
the element ANY is the first one following the definition of
 
1197
a DER decoding process (asn1_der_decoding function). The element
 
1198
ANY must be defined by an OBJECT IDENTIFIER. The type used to
 
1199
expand the element ANY is the first one following the definition of
1306
1200
the actual value of the OBJECT IDENTIFIER.
1307
1201
 
1308
 
        <p><strong>Returns:</strong>
1309
 
<strong>ASN1_SUCCESS:</strong> Substitution OK.
1310
 
 
1311
 
        <p><strong>ASN1_ERROR_TYPE_ANY:</strong> Some "ANY DEFINED BY" element couldn't be
1312
 
expanded due to a problem in OBJECT_ID -&gt; TYPE association.
1313
 
 
1314
 
        <p>other errors: Result of der decoding process. 
1315
 
</p></blockquote></div>
 
1202
        <p><strong>Returns:</strong> </p></blockquote></div>
1316
1203
 
1317
1204
<h4 class="subheading">asn1_expand_octet_string</h4>
1318
1205
 
1329
1216
        <p><var>objectName</var>: name of the OBJECT IDENTIFIER field to use to define
1330
1217
the type for expansion.
1331
1218
 
1332
 
        <p>Expands an "OCTET STRING" element of a structure created from a
1333
 
DER decoding process (asn1_der_decoding function). The type used
1334
 
for expansion is the first one following the definition of the
1335
 
actual value of the OBJECT IDENTIFIER indicated by OBJECTNAME.
1336
 
 
1337
 
        <p><strong>Returns:</strong>
1338
 
<strong>ASN1_SUCCESS:</strong> Substitution OK.
1339
 
 
1340
 
        <p><strong>ASN1_ELEMENT_NOT_FOUND:</strong> OBJECTNAME or OCTETNAME are not correct.
1341
 
 
1342
 
        <p><strong>ASN1_VALUE_NOT_VALID:</strong> Wasn't possible to find the type to use
1343
 
for expansion.
1344
 
 
1345
 
        <p>other errors: result of der decoding process. 
1346
 
</p></blockquote></div>
 
1219
        <p>Expands an "OCTET STRING" element of a structure created from a DER
 
1220
decoding process (asn1_der_decoding function). The type used for
 
1221
expansion is the first one following the definition of the actual
 
1222
value of the OBJECT IDENTIFIER indicated by OBJECTNAME.
 
1223
 
 
1224
        <p><strong>Returns:</strong> </p></blockquote></div>
1347
1225
 
1348
1226
<div class="node">
1349
1227
<a name="Error-handling-functions"></a>
1364
1242
&mdash; Function: void <b>asn1_perror</b> (<var>asn1_retCode error</var>)<var><a name="index-asn1_005fperror-38"></a></var><br>
1365
1243
<blockquote><p><var>error</var>: is an error returned by a libtasn1 function.
1366
1244
 
1367
 
        <p>This function is like <code>perror()</code>.  The only difference is that it
1368
 
accepts an error returned by a libtasn1 function.
 
1245
        <p>Prints a string to stderr with a description of an error.  This
 
1246
function is like <code>perror()</code>.  The only difference is that it accepts
 
1247
an error returned by a libtasn1 function.
1369
1248
 
1370
1249
        <p>This function replaces <code>libtasn1_perror()</code> in older libtasn1.
1371
1250
 
1380
1259
&mdash; Function: const char * <b>asn1_strerror</b> (<var>asn1_retCode error</var>)<var><a name="index-asn1_005fstrerror-39"></a></var><br>
1381
1260
<blockquote><p><var>error</var>: is an error returned by a libtasn1 function.
1382
1261
 
1383
 
        <p>This function is similar to strerror.  The only difference is that
1384
 
it accepts an error (number) returned by a libtasn1 function.
 
1262
        <p>Returns a string with a description of an error.  This function is
 
1263
similar to strerror.  The only difference is that it accepts an
 
1264
error (number) returned by a libtasn1 function.
1385
1265
 
1386
1266
        <p>This function replaces <code>libtasn1_strerror()</code> in older libtasn1.
1387
1267
 
1399
1279
&mdash; Function: void <b>libtasn1_perror</b> (<var>asn1_retCode error</var>)<var><a name="index-libtasn1_005fperror-40"></a></var><br>
1400
1280
<blockquote><p><var>error</var>: is an error returned by a libtasn1 function.
1401
1281
 
1402
 
        <p>This function is like <code>perror()</code>. The only difference is that it
1403
 
accepts an error returned by a libtasn1 function.
 
1282
        <p>Prints a string to stderr with a description of an error.  This
 
1283
function is like <code>perror()</code>. The only difference is that it accepts
 
1284
an error returned by a libtasn1 function.
1404
1285
 
1405
1286
        <p><strong>Deprecated:</strong> Use <code>asn1_perror()</code> instead. 
1406
1287
</p></blockquote></div>
1413
1294
&mdash; Function: const char * <b>libtasn1_strerror</b> (<var>asn1_retCode error</var>)<var><a name="index-libtasn1_005fstrerror-41"></a></var><br>
1414
1295
<blockquote><p><var>error</var>: is an error returned by a libtasn1 function.
1415
1296
 
1416
 
        <p>This function is similar to strerror.  The only difference is that
1417
 
it accepts an error (number) returned by a libtasn1 function.
 
1297
        <p>Returns a string with a description of an error.  This function is
 
1298
similar to strerror.  The only difference is that it accepts an
 
1299
error (number) returned by a libtasn1 function.
1418
1300
 
1419
1301
        <p><strong>Returns:</strong> Pointer to static zero-terminated string describing error
1420
1302
code.