1 files changed, 286 insertions, 0 deletions
diff --git a/doc/texi/element.c.texi b/doc/texi/element.c.texi
new file mode 100644
index 0000000..6e40405
--- /dev/null
+++ b/doc/texi/element.c.texi
@@ -0,0 +1,286 @@
+@subheading asn1_write_value
+@anchor{asn1_write_value}
+@deftypefun {int} {asn1_write_value} (asn1_node @var{node_root}, const char * @var{name}, const void * @var{ivalue}, int @var{len})
+@var{node_root}: pointer to a structure
+
+@var{name}: the name of the element inside the structure that you want to set.
+
+@var{ivalue}: vector used to specify the value to set. If len is >0,
+VALUE must be a two's complement form integer.  if len=0 *VALUE
+must be a null terminated string with an integer value.
+
+@var{len}: number of bytes of *value to use to set the value:
+value[0]..value[len-1] or 0 if value is a null terminated string
+
+Set the value of one element inside a structure.
+
+If an element is OPTIONAL and you want to delete it, you must use
+the value=NULL and len=0.  Using "pkix.asn":
+
+result=asn1_write_value(cert, "tbsCertificate.issuerUniqueID",
+NULL, 0);
+
+Description for each type:
+
+@strong{INTEGER:} VALUE must contain a two's complement form integer.
+
+value[0]=0xFF ,               len=1 -> integer=-1.
+value[0]=0xFF value[1]=0xFF , len=2 -> integer=-1.
+value[0]=0x01 ,               len=1 -> integer= 1.
+value[0]=0x00 value[1]=0x01 , len=2 -> integer= 1.
+value="123"                 , len=0 -> integer= 123.
+
+@strong{ENUMERATED:} As INTEGER (but only with not negative numbers).
+
+@strong{BOOLEAN:} VALUE must be the null terminated string "TRUE" or
+"FALSE" and LEN != 0.
+
+value="TRUE" , len=1 -> boolean=TRUE.
+value="FALSE" , len=1 -> boolean=FALSE.
+
+OBJECT IDENTIFIER: VALUE must be a null terminated string with
+each number separated by a dot (e.g. "1.2.3.543.1").  LEN != 0.
+
+value="1 2 840 10040 4 3" , len=1 -> OID=dsa-with-sha.
+
+@strong{UTCTime:} VALUE must be a null terminated string in one of these
+formats: "YYMMDDhhmmssZ", "YYMMDDhhmmssZ",
+"YYMMDDhhmmss+hh'mm'", "YYMMDDhhmmss-hh'mm'",
+"YYMMDDhhmm+hh'mm'", or "YYMMDDhhmm-hh'mm'".  LEN != 0.
+
+value="9801011200Z" , len=1 -> time=Jannuary 1st, 1998
+at 12h 00m Greenwich Mean Time
+
+@strong{GeneralizedTime:} VALUE must be in one of this format:
+"YYYYMMDDhhmmss.sZ", "YYYYMMDDhhmmss.sZ",
+"YYYYMMDDhhmmss.s+hh'mm'", "YYYYMMDDhhmmss.s-hh'mm'",
+"YYYYMMDDhhmm+hh'mm'", or "YYYYMMDDhhmm-hh'mm'" where ss.s
+indicates the seconds with any precision like "10.1" or "01.02".
+LEN != 0
+
+value="2001010112001.12-0700" , len=1 -> time=Jannuary
+1st, 2001 at 12h 00m 01.12s Pacific Daylight Time
+
+OCTET STRING: VALUE contains the octet string and LEN is the
+number of octets.
+
+value="$\backslash$x01$\backslash$x02$\backslash$x03" ,
+len=3 -> three bytes octet string
+
+@strong{GeneralString:} VALUE contains the generalstring and LEN is the
+number of octets.
+
+value="$\backslash$x01$\backslash$x02$\backslash$x03" ,
+len=3 -> three bytes generalstring
+
+BIT STRING: VALUE contains the bit string organized by bytes and
+LEN is the number of bits.
+
+value="$\backslash$xCF" , len=6 -> bit string="110011" (six
+bits)
+
+@strong{CHOICE:} if NAME indicates a choice type, VALUE must specify one of
+the alternatives with a null terminated string. LEN != 0. Using
+"pkix.asn"\:
+
+result=asn1_write_value(cert,
+"certificate1.tbsCertificate.subject", "rdnSequence",
+1);
+
+@strong{ANY:} VALUE indicates the der encoding of a structure.  LEN != 0.
+
+SEQUENCE OF: VALUE must be the null terminated string "NEW" and
+LEN != 0. With this instruction another element is appended in
+the sequence. The name of this element will be "?1" if it's the
+first one, "?2" for the second and so on.
+
+Using "pkix.asn"\:
+
+result=asn1_write_value(cert,
+"certificate1.tbsCertificate.subject.rdnSequence", "NEW", 1);
+
+SET OF: the same as SEQUENCE OF.  Using "pkix.asn":
+
+result=asn1_write_value(cert,
+"tbsCertificate.subject.rdnSequence.?LAST", "NEW", 1);
+
+@strong{Returns:} @code{ASN1_SUCCESS}  if the value was set,
+@code{ASN1_ELEMENT_NOT_FOUND}  if  @code{name} is not a valid element, and
+@code{ASN1_VALUE_NOT_VALID}  if  @code{ivalue} has a wrong format.
+@end deftypefun
+
+@subheading asn1_read_value
+@anchor{asn1_read_value}
+@deftypefun {int} {asn1_read_value} (asn1_node @var{root}, const char * @var{name}, void * @var{ivalue}, int * @var{len})
+@var{root}: pointer to a structure.
+
+@var{name}: the name of the element inside a structure that you want to read.
+
+@var{ivalue}: vector that will contain the element's content, must be a
+pointer to memory cells already allocated (may be @code{NULL} ).
+
+@var{len}: number of bytes of *value: value[0]..value[len-1]. Initialy
+holds the sizeof value.
+
+Returns the value of one element inside a structure. 
+If an element is OPTIONAL and this returns
+@code{ASN1_ELEMENT_NOT_FOUND} , it means that this element wasn't present
+in the der encoding that created the structure.  The first element
+of a SEQUENCE_OF or SET_OF is named "?1". The second one "?2" and
+so on. If the  @code{root} provided is a node to specific sequence element,
+then the keyword "?CURRENT" is also acceptable and indicates the
+current sequence element of this node.
+
+Note that there can be valid values with length zero. In these case
+this function will succeed and  @code{len} will be zero.
+
+@strong{INTEGER:} VALUE will contain a two's complement form integer.
+
+integer=-1  -> value[0]=0xFF , len=1.
+integer=1   -> value[0]=0x01 , len=1.
+
+@strong{ENUMERATED:} As INTEGER (but only with not negative numbers).
+
+@strong{BOOLEAN:} VALUE will be the null terminated string "TRUE" or
+"FALSE" and LEN=5 or LEN=6.
+
+OBJECT IDENTIFIER: VALUE will be a null terminated string with
+each number separated by a dot (i.e. "1.2.3.543.1").
+
+LEN = strlen(VALUE)+1
+
+@strong{UTCTime:} VALUE will be a null terminated string in one of these
+formats: "YYMMDDhhmmss+hh'mm'" or "YYMMDDhhmmss-hh'mm'".
+LEN=strlen(VALUE)+1.
+
+@strong{GeneralizedTime:} VALUE will be a null terminated string in the
+same format used to set the value.
+
+OCTET STRING: VALUE will contain the octet string and LEN will be
+the number of octets.
+
+@strong{GeneralString:} VALUE will contain the generalstring and LEN will
+be the number of octets.
+
+BIT STRING: VALUE will contain the bit string organized by bytes
+and LEN will be the number of bits.
+
+@strong{CHOICE:} If NAME indicates a choice type, VALUE will specify the
+alternative selected.
+
+@strong{ANY:} If NAME indicates an any type, VALUE will indicate the DER
+encoding of the structure actually used.
+
+@strong{Returns:} @code{ASN1_SUCCESS}  if value is returned,
+@code{ASN1_ELEMENT_NOT_FOUND}  if  @code{name} is not a valid element,
+@code{ASN1_VALUE_NOT_FOUND}  if there isn't any value for the element
+selected, and @code{ASN1_MEM_ERROR}  if The value vector isn't big enough
+to store the result, and in this case  @code{len} will contain the number of
+bytes needed.
+@end deftypefun
+
+@subheading asn1_read_value_type
+@anchor{asn1_read_value_type}
+@deftypefun {int} {asn1_read_value_type} (asn1_node @var{root}, const char * @var{name}, void * @var{ivalue}, int * @var{len}, unsigned int * @var{etype})
+@var{root}: pointer to a structure.
+
+@var{name}: the name of the element inside a structure that you want to read.
+
+@var{ivalue}: vector that will contain the element's content, must be a
+pointer to memory cells already allocated (may be @code{NULL} ).
+
+@var{len}: number of bytes of *value: value[0]..value[len-1]. Initialy
+holds the sizeof value.
+
+@var{etype}: The type of the value read (ASN1_ETYPE)
+
+Returns the type and value of one element inside a structure. 
+If an element is OPTIONAL and this returns
+@code{ASN1_ELEMENT_NOT_FOUND} , it means that this element wasn't present
+in the der encoding that created the structure.  The first element
+of a SEQUENCE_OF or SET_OF is named "?1". The second one "?2" and
+so on. If the  @code{root} provided is a node to specific sequence element,
+then the keyword "?CURRENT" is also acceptable and indicates the
+current sequence element of this node.
+
+Note that there can be valid values with length zero. In these case
+this function will succeed and  @code{len} will be zero.
+
+@strong{INTEGER:} VALUE will contain a two's complement form integer.
+
+integer=-1  -> value[0]=0xFF , len=1.
+integer=1   -> value[0]=0x01 , len=1.
+
+@strong{ENUMERATED:} As INTEGER (but only with not negative numbers).
+
+@strong{BOOLEAN:} VALUE will be the null terminated string "TRUE" or
+"FALSE" and LEN=5 or LEN=6.
+
+OBJECT IDENTIFIER: VALUE will be a null terminated string with
+each number separated by a dot (i.e. "1.2.3.543.1").
+
+LEN = strlen(VALUE)+1
+
+@strong{UTCTime:} VALUE will be a null terminated string in one of these
+formats: "YYMMDDhhmmss+hh'mm'" or "YYMMDDhhmmss-hh'mm'".
+LEN=strlen(VALUE)+1.
+
+@strong{GeneralizedTime:} VALUE will be a null terminated string in the
+same format used to set the value.
+
+OCTET STRING: VALUE will contain the octet string and LEN will be
+the number of octets.
+
+@strong{GeneralString:} VALUE will contain the generalstring and LEN will
+be the number of octets.
+
+BIT STRING: VALUE will contain the bit string organized by bytes
+and LEN will be the number of bits.
+
+@strong{CHOICE:} If NAME indicates a choice type, VALUE will specify the
+alternative selected.
+
+@strong{ANY:} If NAME indicates an any type, VALUE will indicate the DER
+encoding of the structure actually used.
+
+@strong{Returns:} @code{ASN1_SUCCESS}  if value is returned,
+@code{ASN1_ELEMENT_NOT_FOUND}  if  @code{name} is not a valid element,
+@code{ASN1_VALUE_NOT_FOUND}  if there isn't any value for the element
+selected, and @code{ASN1_MEM_ERROR}  if The value vector isn't big enough
+to store the result, and in this case  @code{len} will contain the number of
+bytes needed.
+@end deftypefun
+
+@subheading asn1_read_tag
+@anchor{asn1_read_tag}
+@deftypefun {int} {asn1_read_tag} (asn1_node @var{root}, const char * @var{name}, int * @var{tagValue}, int * @var{classValue})
+@var{root}: pointer to a structure
+
+@var{name}: the name of the element inside a structure.
+
+@var{tagValue}: variable that will contain the TAG value.
+
+@var{classValue}: variable that will specify the TAG type.
+
+Returns the TAG and the CLASS of one element inside a structure.
+CLASS can have one of these constants: @code{ASN1_CLASS_APPLICATION} ,
+@code{ASN1_CLASS_UNIVERSAL} , @code{ASN1_CLASS_PRIVATE}  or
+@code{ASN1_CLASS_CONTEXT_SPECIFIC} .
+
+@strong{Returns:} @code{ASN1_SUCCESS}  if successful, @code{ASN1_ELEMENT_NOT_FOUND}  if
+ @code{name} is not a valid element.
+@end deftypefun
+
+@subheading asn1_read_node_value
+@anchor{asn1_read_node_value}
+@deftypefun {int} {asn1_read_node_value} (asn1_node @var{node}, asn1_data_node_st * @var{data})
+@var{node}: pointer to a node.
+
+@var{data}: a point to a asn1_data_node_st
+
+Returns the value a data node inside a asn1_node structure.
+The data returned should be handled as constant values.
+
+@strong{Returns:} @code{ASN1_SUCCESS}  if the node exists.
+@end deftypefun
+