### ASN.1 Assignments Example

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Invoking-asn1Coding.html

An example of an ASN.1 assignments file. This file provides values for the structures defined in the ASN.1 definitions file.

```asn
dp MYPKIX1.Dss-Sig-Value

r 42
s 47
other.x 66
other.y y1
other.y.y1 15
z (NULL)
```

--------------------------------

### ASN.1 Definitions Example

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Invoking-asn1Coding.html

An example of an ASN.1 definitions file. This file specifies the structure of the data, including sequences and choices.

```asn
MYPKIX1 { } 

DEFINITIONS IMPLICIT TAGS ::=

BEGIN

OtherStruct ::= SEQUENCE {
     x       INTEGER,
     y       CHOICE {
         y1 INTEGER,
         y2 OCTET STRING }
}

Dss-Sig-Value ::= SEQUENCE {
     r       INTEGER,
     s       INTEGER,
     other   OtherStruct,
     z       INTEGER OPTIONAL
}

END
```

--------------------------------

### Example asn1Decoding Invocation

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Invoking-asn1Decoding.html

Demonstrates how to invoke asn1Decoding to decode DER data. This example assumes 'pkix.asn' contains ASN.1 definitions, 'assign.out' is the DER encoded file, and 'PKIX1.Dss-Sig-Value' is the ASN.1 type to decode.

```bash
$ asn1Decoding pkix.asn assign.out PKIX1.Dss-Sig-Value
```

--------------------------------

### Invoking asn1Coding Command

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Invoking-asn1Coding.html

Example command to run asn1Coding with specified ASN.1 definition and assignment files to generate a DER encoding.

```bash
$ asn1Coding pkix.asn assign.asn1
```

--------------------------------

### ASN.1 Definitions Example

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Example of ASN.1 definitions including SEQUENCE and CHOICE types. This file is used by asn1Coding and asn1Decoding utilities.

```asn
MYPKIX1 { }

DEFINITIONS IMPLICIT TAGS ::=

BEGIN

OtherStruct ::= SEQUENCE {
     x       INTEGER,
     y       CHOICE {
         y1 INTEGER,
         y2 OCTET STRING }
}

Dss-Sig-Value ::= SEQUENCE {
     r       INTEGER,
     s       INTEGER,
     other   OtherStruct,
     z       INTEGER OPTIONAL
}

END
```

--------------------------------

### ASN.1 Assignments for CHOICE Root Element

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Invoking-asn1Coding.html

Example of an assignments file when the root element is a CHOICE type. It shows how to specify the root element itself and then the chosen field.

```asn
elt PKIX1Implicit88.GeneralName

''      dNSName
dNSName example.org
```

--------------------------------

### ASN.1 Definition Example

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Naming.html

This ASN.1 definition illustrates a SEQUENCE with nested types. Accessing elements uses a dot notation, e.g., 'Example.Group.id'.

```asn
      Example { 1 2 3 4 } 

      DEFINITIONS EXPLICIT TAGS ::=

      BEGIN

      Group ::= SEQUENCE {
         id   OBJECT IDENTIFIER,
         value  Value
      }

      Value ::= SEQUENCE {
         value1  INTEGER,
         value2  BOOLEAN
      }

      END


```

--------------------------------

### asn1_der_decoding_startEnd

Source: https://www.gnu.org/software/libtasn1/manual/html_node/DER-functions.html

Finds the start and end positions of a named element within a DER encoding.

```APIDOC
## asn1_der_decoding_startEnd

### Description
Locates the start and end byte positions of a specific element (`name_element`) within a DER encoding (`ider`). This is useful for extracting sub-parts of a decoded structure, such as 'tbsCertificate' within an X509 certificate.

### Function Signature
`int asn1_der_decoding_startEnd(asn1_node element, const void *ider, int ider_len, const char *name_element, int *start, int *end)`

### Parameters
- **element** (`asn1_node`) - Pointer to an ASN.1 element.
- **ider** (`const void *`) - Buffer containing the DER encoding.
- **ider_len** (`int`) - Length of the DER encoding buffer.
- **name_element** (`const char *`) - The name of the element to find.
- **start** (`int *`) - Pointer to an integer where the starting position of the element will be stored.
- **end** (`int *`) - Pointer to an integer where the ending position of the element will be stored.

### Returns
- `ASN1_SUCCESS` if the start and end positions are found.
- `ASN1_ELEMENT_NOT_FOUND` if `element` is empty or `name_element` is invalid.
- `ASN1_TAG_ERROR` or `ASN1_DER_ERROR` if the DER encoding does not match the element.
```

--------------------------------

### asn1_der_decoding_startEnd

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Finds the start and end positions of a specific element within a DER encoding string. This is useful for extracting sub-parts of a decoded structure.

```APIDOC
## asn1_der_decoding_startEnd

### Description
Find the start and end point of an element in a DER encoding string. If you have a der encoding and you have already used the function ‘asn1_der_decoding()’ to fill a structure, it may happen that you want to find the piece of string concerning an element of the structure.

### Parameters
#### Path Parameters
- **ELEMENT** (asn1_node) - pointer to an ASN1 element
- **IDER** (const void *) - vector that contains the DER encoding.
- **IDER_LEN** (int) - number of bytes of * ‘ider’ : ‘ider’ [0].. ‘ider’ [len-1]
- **NAME_ELEMENT** (const char *) - an element of NAME structure.
- **START** (int *) - the position of the first byte of NAME_ELEMENT decoding (‘ider’ [*start])
- **END** (int *) - the position of the last byte of NAME_ELEMENT decoding (‘ider’ [*end])

### Returns
- ‘ASN1_SUCCESS’ if DER encoding OK
- ‘ASN1_ELEMENT_NOT_FOUND’ if ELEMENT is ‘asn1_node’ EMPTY or ‘name_element’ is not a valid element
- ‘ASN1_TAG_ERROR’ or ‘ASN1_DER_ERROR’ if the der encoding doesn't match the structure ELEMENT
```

--------------------------------

### asn1Parser Usage and Options

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Invoking-asn1Parser.html

This displays the command-line usage and available options for the asn1Parser utility. Use it to understand how to invoke the parser and specify its behavior, such as output file or array name.

```bash
Usage: asn1Parser [OPTION] FILE
Read FILE with ASN.1 definitions and generate
a C array that is used with libtasn1 functions.

Mandatory arguments to long options are mandatory for short options too.
  -c, --check           checks the syntax only
  -o, --output=FILE     output file
  -n, --name=NAME       array name
  -h, --help            display this help and exit
  -v, --version         output version information and exit

Report bugs to: help-libtasn1@gnu.org
GNU Libtasn1 home page: <https://www.gnu.org/software/libtasn1/>
General help using GNU software: <https://www.gnu.org/gethelp/>


```

--------------------------------

### asn1Coding Usage Information

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Invoking-asn1Coding.html

Displays the command-line usage and available options for the asn1Coding utility. Use this to understand how to invoke the tool and its parameters.

```bash
Usage: asn1Coding [OPTION] DEFINITIONS ASSIGNMENTS
Generates a DER encoding of ASN.1 DEFINITIONS file
and ASSIGNMENTS file with value assignments.

Mandatory arguments to long options are mandatory for short options too.
  -c, --check           checks the syntax only
  -o, --output=FILE     output file
  -h, --help            display this help and exit
  -v, --version         output version information and exit

Report bugs to: help-libtasn1@gnu.org
GNU Libtasn1 home page: <https://www.gnu.org/software/libtasn1/>
General help using GNU software: <https://www.gnu.org/gethelp/>
```

--------------------------------

### asn1_find_node

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Searches for an ASN.1 element by name within a structure, starting from a given node. Names can be hierarchical, separated by dots.

```APIDOC
## asn1_find_node

### Description
Searches for an element called ‘name’ starting from ‘pointer’ . The name is composed by different identifiers separated by dots. When * ‘pointer’ has a name, the first identifier must be the name of * ‘pointer’ , otherwise it must be the name of one child of * ‘pointer’ .

### Parameters
- **POINTER** (asn1_node_const) - NODE_ASN element pointer.
- **NAME** (const char *) - Null-terminated string with the element's name to find.

### Returns
The search result, or ‘NULL’ if not found.
```

--------------------------------

### asn1Decoding Usage

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Invoking-asn1Decoding.html

Displays the usage instructions and available options for the asn1Decoding command-line utility. Use this to understand the command's parameters and flags.

```bash
Usage: asn1Decoding [OPTION] DEFINITIONS ENCODED ASN1TYPE
Decodes DER data in ENCODED file, for the ASN1TYPE element
described in ASN.1 DEFINITIONS file, and print decoded structures.

  -b, --benchmark       perform a benchmark on decoding
  -s, --strict          use strict DER decoding
  -t, --no-time-strict  use strict DER decoding but not in time fields
  -h, --help            display this help and exit
  -v, --version         output version information and exit

Report bugs to: help-libtasn1@gnu.org
GNU Libtasn1 home page: <https://www.gnu.org/software/libtasn1/>
General help using GNU software: <https://www.gnu.org/gethelp/>
```

--------------------------------

### Clone Libtasn1 Sources with Git

Source: https://www.gnu.org/software/libtasn1

Use this command to check out the Libtasn1 source code from its GitLab repository.

```bash
$ git clone https://gitlab.com/gnutls/libtasn1.git

```

--------------------------------

### Run asn1Coding command

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Command to generate a DER encoding file using asn1Coding with specified definition and assignment files. The output is a binary file.

```bash
$asn1Coding pkix.asn assign.asn1
```

--------------------------------

### Initialize asn1_node Variable

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Library-Notes.html

Use the `NULL` constant for initializing `asn1_node` variables. This is a common practice for variable initialization in C.

```c
asn1_node definitions = NULL;
```

--------------------------------

### Valid ASN.1 Type Declaration

Source: https://www.gnu.org/software/libtasn1/manual/html_node/ASN_002e1-syntax.html

Demonstrates the correct syntax for declaring an ASN.1 type, ensuring the '::=' token is separated.

```asn
   Version ::= INTEGER

```

--------------------------------

### Create ASN.1 Element

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Use this function to create a new ASN.1 structure of a specified type. Ensure the type is defined within the provided definitions.

```c
rc = asn1_create_element(cert_def, "PKIX1.Certificate", certptr);
```

--------------------------------

### asn1_create_element

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Creates a structure of a specified type. It takes a pointer to the definitions, the name of the type, and a pointer to the structure to be created. Returns ASN1_SUCCESS on success or ASN1_ELEMENT_NOT_FOUND if the source name is unknown.

```APIDOC
## Function: int asn1_create_element (asn1_node_const DEFINITIONS, const char * SOURCE_NAME, asn1_node * ELEMENT)

### Description
Creates a structure of type ‘source_name’. Example using "pkix.asn":

rc = asn1_create_element(cert_def, "PKIX1.Certificate", certptr);

### Parameters
*   **DEFINITIONS**: pointer to the structure returned by "parser_asn1" function
*   **SOURCE_NAME**: the name of the type of the new structure (must be inside p_structure).
*   **ELEMENT**: pointer to the structure created.

### Returns
*   ‘ASN1_SUCCESS’ if creation OK
*   ‘ASN1_ELEMENT_NOT_FOUND’ if ‘source_name’ is not known.
```

--------------------------------

### asn1_check_version

Source: https://www.gnu.org/software/libtasn1/manual/html_node/Auxiliary-functions.html

Verifies if the running libtasn1 library meets a specified minimum version. It returns the library's version string if the check passes or if no version is requested.

```APIDOC
## asn1_check_version

### Description
Checks if the library version is at least the `req_version`. Returns the library's version string on success or if `req_version` is `NULL`.

### Function Signature
`const char *` **asn1_check_version** `(const char * req_version)`

### Parameters
#### Path Parameters
- **req_version** (`const char *`): The minimum required version string, or `NULL` to skip the check and return the current version.

### Returns
- `const char *`: The version string of the run-time library, or `NULL` if the library does not meet the `req_version`.
```

--------------------------------

### Standard GFDL Notice

Source: https://www.gnu.org/software/libtasn1/manual/html_node/GNU-Free-Documentation-License.html

Use this notice when applying the GFDL to your document. It grants permission for copying, distribution, and modification under the terms of GFDL v1.3 or later, with no invariant sections, front-cover texts, or back-cover texts.

```text
  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

```

--------------------------------

### asn1Coding command-line usage

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Use asn1Coding to generate a DER encoding from ASN.1 definitions and assignments files. Options include syntax checking and specifying the output file.

```bash
Usage: asn1Coding [OPTION] DEFINITIONS ASSIGNMENTS
Generates a DER encoding of ASN.1 DEFINITIONS file
and ASSIGNMENTS file with value assignments.

Mandatory arguments to long options are mandatory for short options too.
  -c, --check           checks the syntax only
  -o, --output=FILE     output file
  -h, --help            display this help and exit
  -v, --version         output version information and exit
```

--------------------------------

### asn1_array2tree

Source: https://www.gnu.org/software/libtasn1/manual/html_node/ASN_002e1-field-functions.html

Creates the structures needed to manage ASN.1 definitions from an array.

```APIDOC
## asn1_array2tree

### Description
Creates the structures needed to manage the ASN.1 definitions. `array` is a vector created by `asn1_parser2array()`.

### Parameters
- **array** (const asn1_static_node *) - Specifies the array that contains ASN.1 declarations.
- **definitions** (asn1_node *) - Returns the pointer to the structure created by ARRAY ASN.1 declarations.
- **errorDescription** (char *) - Returns the error description.

### Returns
- `ASN1_SUCCESS` if structure was created correctly.
- `ASN1_ELEMENT_NOT_EMPTY` if `definitions` not NULL.
- `ASN1_IDENTIFIER_NOT_FOUND` if in the file there is an identifier that is not defined (see `errorDescription` for more information).
- `ASN1_ARRAY_ERROR` if the array pointed by `array` is wrong.
```

--------------------------------

### asn1Decoding command-line usage

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Use asn1Decoding to generate an ASN.1 structure from definitions and a DER encoded file. Options include benchmarking and strict DER decoding.

```bash
Usage: asn1Decoding [OPTION] DEFINITIONS ENCODED ASN1TYPE
Decodes DER data in ENCODED file, for the ASN1TYPE element
described in ASN.1 DEFINITIONS file, and print decoded structures.

  -b, --benchmark       perform a benchmark on decoding
  -s, --strict          use strict DER decoding
  -t, --no-time-strict  use strict DER decoding but not in time fields
  -h, --help            display this help and exit
  -v, --version         output version information and exit
```

--------------------------------

### asn1_print_structure

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Prints the structure's tree to a specified output file descriptor. It takes a pointer to the output file, the structure to visit, an element name, and a mode to control the verbosity of the output.

```APIDOC
## Function: void asn1_print_structure (FILE * OUT, asn1_node_const STRUCTURE, const char * NAME, int MODE)

### Description
Prints on the ‘out’ file descriptor the structure's tree starting from the ‘name’ element inside the structure ‘structure’.

### Parameters
*   **OUT**: pointer to the output file (e.g. stdout).
*   **STRUCTURE**: pointer to the structure that you want to visit.
*   **NAME**: an element of the structure
*   **MODE**: specify how much of the structure to print, can be ‘ASN1_PRINT_NAME’ , ‘ASN1_PRINT_NAME_TYPE’ , ‘ASN1_PRINT_NAME_TYPE_VALUE’ , or ‘ASN1_PRINT_ALL’ .
```

--------------------------------

### Print ASN.1 Structure

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Prints a portion or all of an ASN.1 structure to a specified output file. The MODE parameter controls the verbosity of the output.

```c
asn1_print_structure(stdout, cert_def, "PKIX1.Certificate", ASN1_PRINT_ALL);
```

--------------------------------

### asn1Parser command-line usage

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Use asn1Parser to read ASN.1 definitions and generate a C array for libtasn1 functions. Options include checking syntax, specifying output file, and naming the array.

```bash
Usage: asn1Parser [OPTION] FILE
Read FILE with ASN.1 definitions and generate
a C array that is used with libtasn1 functions.

Mandatory arguments to long options are mandatory for short options too.
  -c, --check           checks the syntax only
  -o, --output=FILE     output file
  -n, --name=NAME       array name
  -h, --help            display this help and exit
  -v, --version         output version information and exit
```

--------------------------------

### GFDL Notice with Cover Texts

Source: https://www.gnu.org/software/libtasn1/manual/html_node/GNU-Free-Documentation-License.html

Adapt this notice if your document includes Invariant Sections, Front-Cover Texts, and Back-Cover Texts. Replace the standard text with this to specify the content of these sections.

```text
    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

```

--------------------------------

### Duplicate ASN.1 Node

Source: https://www.gnu.org/software/libtasn1/manual/html_node/ASN_002e1-field-functions.html

Creates a deep copy of an ASN.1 node. Ensure the source node and its name are valid. Returns NULL on failure.

```c
asn1_node asn1_dup_node(asn1_node_const src, const char * src_name);
```

--------------------------------

### Reading a GeneralString

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

GeneralString is read directly into `ivalue`, with `len` indicating the number of octets.

```c
/* VALUE will contain the generalstring and LEN will be the number of octets. */
```

--------------------------------

### asn1_expand_any_defined_by

Source: https://www.gnu.org/software/libtasn1/manual/html_node/DER-functions.html

Expands 'ANY DEFINED BY' elements within a DER-decoded structure.

```APIDOC
## asn1_expand_any_defined_by

### Description
Expands 'ANY DEFINED BY' elements in a structure that was populated using `asn1_der_decoding()`. The expansion type is determined by the OBJECT IDENTIFIER associated with the 'ANY' element.

### Function Signature
`int asn1_expand_any_defined_by(asn1_node_const definitions, asn1_node *element)`

### Parameters
- **definitions** (`asn1_node_const`) - ASN.1 definitions.
- **element** (`asn1_node *`) - Pointer to the ASN.1 structure containing the 'ANY DEFINED BY' element.

### Returns
- `ASN1_SUCCESS` if the expansion is successful.
- `ASN1_ERROR_TYPE_ANY` if an 'ANY DEFINED BY' element cannot be expanded due to an issue with the OBJECT_ID to TYPE association.
- Other error codes may be returned depending on DER decoding issues.
```

--------------------------------

### Duplicate ASN.1 Node

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Creates an exact duplicate of a given ASN.1 node, returning a pointer to the new structure. Returns NULL on failure.

```c
asn1_node new_cert = asn1_dup_node(cert, "tbsCertificate");
```

--------------------------------

### Reading a BIT STRING

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

BIT STRING content is read into `ivalue` organized by bytes, and `len` specifies the total number of bits.

```c
/* VALUE will contain the bit string organized by bytes and LEN will be the number of bits. */
```

--------------------------------

### Appending an Element to a SET OF

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Similar to 'SEQUENCE OF', use 'NEW' to append an element to a 'SET OF' type. The last appended element can be referenced using '?LAST'.

```c
result=asn1_write_value(cert,
"tbsCertificate.subject.rdnSequence.?LAST", "NEW", 1);
```

--------------------------------

### Deep Copy ASN.1 Node

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Creates a deep copy of an ASN.1 node. The destination node must be pre-allocated using asn1_create_element.

```c
asn1_copy_node(cert, "tbsCertificate.subject", cert_def, "Name");
```

--------------------------------

### asn1_copy_node

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Creates a deep copy of an ASN1 node. Requires the destination node to be expanded using asn1_create_element(). Returns ASN1_SUCCESS on success.

```APIDOC
## Function: int asn1_copy_node (asn1_node DST, const char * DST_NAME, asn1_node_const SRC, const char * SRC_NAME)

### Description
Create a deep copy of a asn1_node variable. That function requires ‘dst’ to be expanded using ‘asn1_create_element()’.

### Parameters
*   **DST**: Destination asn1 node.
*   **DST_NAME**: Field name in destination node.
*   **SRC**: Source asn1 node.
*   **SRC_NAME**: Field name in source node.

### Returns
*   Return ‘ASN1_SUCCESS’ on success.
```

--------------------------------

### Reading a CHOICE Type

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

When reading a CHOICE type, `ivalue` will indicate the specific alternative that was selected.

```c
/* If NAME indicates a choice type, VALUE will specify the alternative selected. */
```

--------------------------------

### Reading an OCTET STRING

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

For OCTET STRING, `ivalue` contains the octet string itself, and `len` is the number of octets.

```c
/* VALUE will contain the octet string and LEN will be the number of octets. */
```

--------------------------------

### asn1_parser2tree

Source: https://www.gnu.org/software/libtasn1/manual/html_node/ASN_002e1-schema-functions.html

Parses ASN.1 declarations from a file into a tree structure. It initializes the necessary structures to manage the definitions within the specified file.

```APIDOC
## asn1_parser2tree

### Description
Parses ASN.1 declarations from a file into a tree structure. It initializes the necessary structures to manage the definitions within the specified file.

### Function Signature
`int asn1_parser2tree(const char * file, asn1_node * definitions, char * error_desc)`

### Parameters
#### Path Parameters
- **file** (const char *) - Specifies the path and name of the file containing ASN.1 declarations.
- **definitions** (asn1_node *) - Returns a pointer to the structure created from the file's ASN.1 declarations.
- **error_desc** (char *) - Returns an error description or an empty string upon success.

### Returns
- `ASN1_SUCCESS`: If the file has correct syntax and all identifiers are known.
- `ASN1_ELEMENT_NOT_EMPTY`: If `definitions` is not `NULL`.
- `ASN1_FILE_NOT_FOUND`: If an error occurred while opening the file.
- `ASN1_SYNTAX_ERROR`: If the syntax is incorrect.
- `ASN1_IDENTIFIER_NOT_FOUND`: If an identifier in the file is not defined.
- `ASN1_NAME_TOO_LONG`: If an identifier in the file exceeds `ASN1_MAX_NAME_SIZE` characters.
```

--------------------------------

### Reading an ANY Type

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

For an ANY type, `ivalue` will contain the DER encoding of the structure that was actually used.

```c
/* If NAME indicates an any type, VALUE will indicate the DER encoding of the structure actually used. */
```

--------------------------------

### Reading a BOOLEAN Value

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

For BOOLEAN types, `ivalue` will be a null-terminated string, either "TRUE" or "FALSE". The `len` will be 5 or 6 respectively.

```c
/* VALUE will be the null terminated string "TRUE" or "FALSE" and LEN=5 or LEN=6. */
```

--------------------------------

### Appending an Element to a SEQUENCE OF

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

When dealing with 'SEQUENCE OF' types, use 'NEW' as the value to append a new element. The element will be named sequentially (e.g., '?1', '?2').

```c
result=asn1_write_value(cert,
"certificate1.tbsCertificate.subject.rdnSequence", "NEW", 1);
```

--------------------------------

### asn1_parser2array

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Generates a C structure (a C vector) from an ASN.1 file, which can be used to manage the definitions. It takes input and output filenames, and a vector name as parameters.

```APIDOC
## Function: int asn1_parser2array (const char * INPUTFILENAME, const char * OUTPUTFILENAME, const char * VECTORNAME, char * ERROR_DESC)

### Description
Generates a C structure, specifically a C vector, from an ASN.1 file. This C vector is then used to manage the definitions contained within the input ASN.1 file. The output is written to a specified file.

### Parameters
#### Path Parameters
- **INPUTFILENAME** (const char *) - The path and name of the file containing ASN.1 declarations.
- **OUTPUTFILENAME** (const char *) - The path and name of the file where the C vector definition will be written. If NULL, a default name is generated based on the input filename.
- **VECTORNAME** (const char *) - The name to be used for the C vector. If NULL, a default name is generated.
- **ERROR_DESC** (char *) - A buffer to store any error description if the process fails, or an empty string on success.

### Returns
- **ASN1_SUCCESS**: If the file has correct syntax and all identifiers are known.
- **ASN1_FILE_NOT_FOUND**: If an error occurred while opening the input file.
- **ASN1_SYNTAX_ERROR**: If the syntax of the ASN.1 file is incorrect.
- **ASN1_IDENTIFIER_NOT_FOUND**: If an identifier in the file is not defined.
- **ASN1_NAME_TOO_LONG**: If an identifier in the file exceeds ASN1_MAX_NAME_SIZE characters.
```

--------------------------------

### Find ASN.1 Structure by OID

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Searches ASN.1 definitions for a structure associated with a given Object Identifier (OID).

```c
const char *name = asn1_find_structure_from_oid(cert_def, "1.3.6.1.5.5.7.0.1");
```

--------------------------------

### asn1_array2tree

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Creates structures for managing ASN.1 definitions from an array, typically generated by `asn1_parser2array`. It returns success or an error code.

```APIDOC
## Function: int asn1_array2tree (const asn1_static_node * ARRAY, asn1_node * DEFINITIONS, char * ERRORDESCRIPTION)

### Description
Initializes and creates the necessary data structures to manage ASN.1 definitions, using a pre-existing array (often generated by `asn1_parser2array`).

### Parameters
#### Path Parameters
- **ARRAY** (const asn1_static_node *) - A pointer to the array containing ASN.1 declarations.
- **DEFINITIONS** (asn1_node *) - A pointer to a structure that will be populated with the created ASN.1 definitions.
- **ERRORDESCRIPTION** (char *) - A buffer to store any error description if the creation fails.

### Returns
- **ASN1_SUCCESS**: If the structure was created correctly.
- **ASN1_ELEMENT_NOT_EMPTY**: If the 'definitions' pointer is not NULL.
- **ASN1_IDENTIFIER_NOT_FOUND**: If an identifier within the array is not defined.
- **ASN1_ARRAY_ERROR**: If the provided array is invalid or corrupted.
```

--------------------------------

### Reading an INTEGER Value

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

When reading an INTEGER, the `ivalue` buffer will contain the two's complement form of the integer. The `len` parameter indicates the number of bytes.

```c
/* integer=-1 -> value[0]=0xFF , len=1.  integer=1 -> value[0]=0x01 , len=1. */
```

--------------------------------

### asn1_copy_node

Source: https://www.gnu.org/software/libtasn1/manual/html_node/ASN_002e1-field-functions.html

Creates a deep copy of an ASN.1 node.

```APIDOC
## asn1_copy_node

### Description
Creates a deep copy of an `asn1_node` variable. This function requires `dst` to be expanded using `asn1_create_element()`.

### Parameters
- **dst** (asn1_node) - Destination asn1 node.
- **dst_name** (const char *) - Field name in the destination node.
- **src** (asn1_node_const) - Source asn1 node.
- **src_name** (const char *) - Field name in the source node.

### Returns
- `ASN1_SUCCESS` on success.
```

--------------------------------

### asn1_create_element

Source: https://www.gnu.org/software/libtasn1/manual/html_node/ASN_002e1-field-functions.html

Creates a new ASN.1 structure of a specified type.

```APIDOC
## asn1_create_element

### Description
Creates a structure of type `source_name`. Example using "pkix.asn": `rc = asn1_create_element(cert_def, "PKIX1.Certificate", certptr);`

### Parameters
- **definitions** (asn1_node_const) - Pointer to the structure returned by "parser_asn1" function.
- **source_name** (const char *) - The name of the type of the new structure (must be inside p_structure).
- **element** (asn1_node *) - Pointer to the structure created.

### Returns
- `ASN1_SUCCESS` if creation is OK.
- `ASN1_ELEMENT_NOT_FOUND` if `source_name` is not known.
```

--------------------------------

### asn1_expand_any_defined_by

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Expands 'ANY DEFINED BY' elements within an ASN.1 structure. This function requires the 'ANY' element to be defined by an OBJECT IDENTIFIER.

```APIDOC
## asn1_expand_any_defined_by

### Description
Expands every "ANY DEFINED BY" element of a structure created from a DER decoding process (asn1_der_decoding function). The element ANY must be defined by an OBJECT IDENTIFIER. The type used to expand the element ANY is the first one following the definition of the actual value of the OBJECT IDENTIFIER.

### Parameters
#### Path Parameters
- **DEFINITIONS** (asn1_node_const) - ASN1 definitions
- **ELEMENT** (asn1_node *) - pointer to an ASN1 structure

### Returns
- ‘ASN1_SUCCESS’ if Substitution OK
- ‘ASN1_ERROR_TYPE_ANY’ if some "ANY DEFINED BY" element couldn't be expanded due to a problem in OBJECT_ID -> TYPE association, or other error codes depending on DER decoding.
```

--------------------------------

### asn1_dup_node

Source: https://www.gnu.org/software/libtasn1/manual/html_node/ASN_002e1-field-functions.html

Creates a deep copy of an ASN.1 node structure. It duplicates the provided ASN.1 node, ensuring an exact copy of the structure is returned. Returns NULL on failure.

```APIDOC
## asn1_dup_node

### Description
Creates a deep copy of an ASN.1 node structure.

### Parameters
#### Path Parameters
- **src** (asn1_node_const) - Source ASN.1 node.
- **src_name** (const char *) - Field name in the source node.

### Returns
- **asn1_node**: A deep copy of the source ASN.1 node, or NULL on failure.
```

--------------------------------

### asn1_parser2array

Source: https://www.gnu.org/software/libtasn1/manual/html_node/ASN_002e1-schema-functions.html

Generates a C structure (a C vector) from an ASN.1 file, which can be used to manage the definitions. It creates a C file containing this vector.

```APIDOC
## asn1_parser2array

### Description
Generates a C structure (a C vector) from an ASN.1 file, which can be used to manage the definitions. It creates a C file containing this vector.

### Function Signature
`int asn1_parser2array(const char * inputFileName, const char * outputFileName, const char * vectorName, char * error_desc)`

### Parameters
#### Path Parameters
- **inputFileName** (const char *) - Specifies the path and name of the file containing ASN.1 declarations.
- **outputFileName** (const char *) - Specifies the path and name of the file that will contain the C vector definition. If `NULL`, the file created will be based on `inputFileName` (e.g., `/aa/bb/xx.yy` becomes `/aa/bb/xx_asn1_tab.c`).
- **vectorName** (const char *) - Specifies the name of the C vector. If `NULL`, the vector name will default to `xx_asn1_tab` based on the input file name.
- **error_desc** (char *) - Returns an error description or an empty string upon success.

### Returns
- `ASN1_SUCCESS`: If the file has correct syntax and all identifiers are known.
- `ASN1_FILE_NOT_FOUND`: If an error occurred while opening `inputFileName`.
- `ASN1_SYNTAX_ERROR`: If the syntax is incorrect.
- `ASN1_IDENTIFIER_NOT_FOUND`: If an identifier in the file is not defined.
- `ASN1_NAME_TOO_LONG`: If an identifier in the file exceeds `ASN1_MAX_NAME_SIZE` characters.
```

--------------------------------

### asn1_parser2tree

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Parses ASN.1 declarations from a file and creates a tree structure to manage them. It returns success or an error code indicating issues like file not found, syntax errors, or undefined identifiers.

```APIDOC
## Function: int asn1_parser2tree (const char * FILE, asn1_node * DEFINITIONS, char * ERROR_DESC)

### Description
Parses ASN.1 declarations from a specified file and builds an internal tree structure for managing these definitions. It also provides an error description upon completion.

### Parameters
#### Path Parameters
- **FILE** (const char *) - The path and name of the file containing ASN.1 declarations.
- **DEFINITIONS** (asn1_node *) - A pointer to a structure that will hold the parsed ASN.1 declarations.
- **ERROR_DESC** (char *) - A buffer to store any error description if the parsing fails, or an empty string on success.

### Returns
- **ASN1_SUCCESS**: If the file has correct syntax and all identifiers are known.
- **ASN1_ELEMENT_NOT_EMPTY**: If the 'definitions' pointer is not NULL.
- **ASN1_FILE_NOT_FOUND**: If an error occurred while opening the specified file.
- **ASN1_SYNTAX_ERROR**: If the syntax of the ASN.1 file is incorrect.
- **ASN1_IDENTIFIER_NOT_FOUND**: If an identifier in the file is not defined.
- **ASN1_NAME_TOO_LONG**: If an identifier in the file exceeds ASN1_MAX_NAME_SIZE characters.
```

--------------------------------

### Writing an RDN Sequence to a Certificate

Source: https://www.gnu.org/software/libtasn1/manual/libtasn1.txt

Use `asn1_write_value` to set the 'rdnSequence' field within a certificate's subject. Ensure the certificate object and the name are valid.

```c
result=asn1_write_value(cert,
"certificate1.tbsCertificate.subject", "rdnSequence", 1);
```