path: root/doc/texi/element.c.texi

@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