Guardtime KSI c SDK
Functions
TLV Manipulation

Functions

int KSI_TLV_new (KSI_CTX *ctx, unsigned tag, int isLenient, int isForward, KSI_TLV **tlv)
 
int KSI_TLV_fromString (KSI_CTX *ctx, unsigned tag, int isLenient, int isForward, char *str, KSI_TLV **tlv)
 
int KSI_TLV_parseBlob (KSI_CTX *ctx, const unsigned char *data, size_t data_length, KSI_TLV **tlv)
 
int KSI_TLV_parseBlob2 (KSI_CTX *ctx, unsigned char *data, size_t data_length, int ownMemory, KSI_TLV **tlv)
 
int KSI_TLV_getRawValue (KSI_TLV *tlv, const unsigned char **buf, size_t *len)
 
int KSI_TLV_getInteger (KSI_TLV *tlv, KSI_Integer **value)
 
int KSI_TLV_getUInt64Value (const KSI_TLV *tlv, KSI_uint64_t *val)
 
int KSI_TLV_getNestedList (KSI_TLV *tlv, KSI_LIST(KSI_TLV)**list)
 
void KSI_TLV_free (KSI_TLV *tlv)
 
int KSI_TLV_isNonCritical (const KSI_TLV *tlv)
 
int KSI_TLV_isForward (const KSI_TLV *tlv)
 
unsigned KSI_TLV_getTag (const KSI_TLV *tlv)
 
int KSI_TLV_serialize_ex (const KSI_TLV *tlv, unsigned char *buf, size_t buf_size, size_t *len)
 
int KSI_TLV_serialize (const KSI_TLV *tlv, unsigned char **buf, size_t *buf_len)
 
int KSI_TLV_serializePayload (const KSI_TLV *tlv, unsigned char *buf, size_t *len)
 
int KSI_TLV_replaceNestedTlv (KSI_TLV *parentTlv, KSI_TLV *oldTlv, KSI_TLV *newTlv)
 
int KSI_TLV_appendNestedTlv (KSI_TLV *target, KSI_TLV *tlv)
 
int KSI_TLV_writeBytes (const KSI_TLV *tlv, unsigned char *buf, size_t buf_size, size_t *buf_len, int opt)
 
char * KSI_TLV_toString (const KSI_TLV *tlv, char *buffer, size_t buffer_len)
 
int KSI_TLV_clone (const KSI_TLV *tlv, KSI_TLV **clone)
 
int KSI_TLV_setRawValue (KSI_TLV *tlv, const void *data, size_t data_len)
 
size_t KSI_TLV_getAbsoluteOffset (const KSI_TLV *tlv)
 
size_t KSI_TLV_getRelativeOffset (const KSI_TLV *tlv)
 
 KSI_DEFINE_GET_CTX (KSI_TLV)
 

Detailed Description

Most KSI objects use a type-length-value (TLV) encoding scheme. The TLV scheme is used to encode both the KSI data structures and also protocol data units (PDUs) for transferring them between the entities during the signature generation process. The values are octet strings of given lengths that carry information to be interpreted as specified by the types. The value part of an encoded object may contain nested TLV objects.

For space efficiency, two TLV encodings are used:

Smaller objects are encoded as TLV8 for lower overhead. A TLV8 type has local significance and identifies the encapsulated structure in the context where it is used. A TLV16 type < 256 has still local significance, but may be used to encode data that needs 16-bit length. A TLV16 type >= 256 has global significance and identifies the encapsulated structure in the context of the whole signature generation system.

TLV8 and TLV16 are distinguished by the `16-Bit' flag in the first octet of the type field.

Function Documentation

KSI_DEFINE_GET_CTX ( KSI_TLV  )
int KSI_TLV_appendNestedTlv ( KSI_TLV target,
KSI_TLV tlv 
)

This function appends a nested TLV to the target TLV as the last element in the internal list.

 \param[in] target          Target TLV where to add the new value as nested TLV.
 \param[in] tlv                     The TLV to be appended.
int KSI_TLV_clone ( const KSI_TLV tlv,
KSI_TLV **  clone 
)

This functions makes an identical copy of a TLV by serializing, parsing the serialized value and restoring the internal structure.

Parameters
[in]tlvThe TLV object to be cloned.
[out]clonePointer to the receiving pointer of the cloned value.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
void KSI_TLV_free ( KSI_TLV tlv)

Destructor for a TLV object.

Parameters
[in]tlvTLV to be freed.
int KSI_TLV_fromString ( KSI_CTX ctx,
unsigned  tag,
int  isLenient,
int  isForward,
char *  str,
KSI_TLV **  tlv 
)

This function creates a new TLV and initializes its payload with the given string str. The NUL terminator is included in the payload.

Parameters
[in]ctxKSI context.
[in]tagNumeric TLV tag.
[in]isLenientValue of the lenient-flag (1 or 0).
[in]isForwardValue of the forward-flag (1 or 0).
[in]strNUL terminated string value.
[out]tlvPointer to the output variable.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
size_t KSI_TLV_getAbsoluteOffset ( const KSI_TLV tlv)

Returns the absolute offset of the TLV object in the source raw data. If the TLV object is created using KSI_TLV_new, the offset is 0.

Parameters
[in]tlvThe TLV object.
Returns
The absolute offset of the TLV object.
int KSI_TLV_getInteger ( KSI_TLV tlv,
KSI_Integer **  value 
)

Integer value accessor method.

Parameters
[in]tlvTLV from where to extract the value.
[out]valuePointer to pointer of the integer value.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
int KSI_TLV_getNestedList ( KSI_TLV tlv,
KSI_LIST(KSI_TLV)**  list 
)

This function returns the list of nested elements of the TLV. The list is ordered and will be serialized in this order. The list may not be freed by the caller.

Parameters
[in]tlvThe composite TLV object.
[out]listPointer to the receiving list pointer.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
int KSI_TLV_getRawValue ( KSI_TLV tlv,
const unsigned char **  buf,
size_t *  len 
)

This function extracts the binary data from the TLV.

Parameters
[in]tlvTLV from where to extract the value.
[out]bufPointer to output pointer.
[out]lenLength of the raw value.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
size_t KSI_TLV_getRelativeOffset ( const KSI_TLV tlv)

Returns the relative offset of the TLV object in the source raw data. (i.e. if this is a nested TLV object, the offset is calculated only within the payload of the parent TLV object)If the TLV object is created using KSI_TLV_new, the offset is 0.

Parameters
[in]tlvThe TLV object.
Returns
The absolute offset of the TLV object.
unsigned KSI_TLV_getTag ( const KSI_TLV tlv)

This is an access method for the TLV numeric type.

Parameters
[in]tlvTLV.
Returns
Numeric value of the TLV type.
int KSI_TLV_getUInt64Value ( const KSI_TLV tlv,
KSI_uint64_t val 
)

This function extracts the unsigned 64 bit integer value.

Parameters
[in]tlvTLV from where to extract the value.
[out]valPointer to output variable.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
int KSI_TLV_isForward ( const KSI_TLV tlv)

This is an access method for the TLV forward-flag.

Parameters
[in]tlvTLV.
Returns
1 if the forward-flag is set, 0 otherwise.
int KSI_TLV_isNonCritical ( const KSI_TLV tlv)

This is an access method for the TLV lenient-flag.

Parameters
[in]tlvTLV.
Returns
1 if the lenient-flag is set, 0 otherwise.
int KSI_TLV_new ( KSI_CTX ctx,
unsigned  tag,
int  isLenient,
int  isForward,
KSI_TLV **  tlv 
)

This function creates an new TLV.

Parameters
[in]ctxKSI context.
[in]tagNumeric TLV tag.
[in]isLenientValue of the lenient-flag (1 or 0).
[in]isForwardValue of the forward-flag (1 or 0).
[out]tlvPointer to the output variable.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
int KSI_TLV_parseBlob ( KSI_CTX ctx,
const unsigned char *  data,
size_t  data_length,
KSI_TLV **  tlv 
)

Parses a memory area and creates a new TLV.

Parameters
[in]ctxKSI context.
[in]dataPointer to memory to be parsed.
[in]data_lengthLength of the buffer.
[out]tlvPointer to the output variable.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
int KSI_TLV_parseBlob2 ( KSI_CTX ctx,
unsigned char *  data,
size_t  data_length,
int  ownMemory,
KSI_TLV **  tlv 
)

Parses a raw TLV into a KSI_TLV.

Parameters
[in]ctxKSI context.
[in]dataPointer to the raw TLV.
[in]data_lengthLength of the raw data.
[in]ownMemoryDetermines if the data pointer should be owned by the new TLV (1) or not (0).
[out]tlvPointer to the receiving pointer.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
int KSI_TLV_replaceNestedTlv ( KSI_TLV parentTlv,
KSI_TLV oldTlv,
KSI_TLV newTlv 
)

Replaces a nested TLV.

Parameters
[in]parentTlvPointer to the parent TLV.
[in]oldTlvPointer to the previous TLV to be replaced.
[in]newTlvPointer to the replacement TLV.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
Note
The oldTlv will be freed.
int KSI_TLV_serialize ( const KSI_TLV tlv,
unsigned char **  buf,
size_t *  buf_len 
)

This function serialises the TLV value into a buffer. The output buffer value has to be freed (see KSI_free) by the caller.

Parameters
[in]tlvTLV to be serialized.
[out]bufPointer to the receiving buffer pointer.
[out]buf_lenPointer to the receiving buffer length variable.
int KSI_TLV_serialize_ex ( const KSI_TLV tlv,
unsigned char *  buf,
size_t  buf_size,
size_t *  len 
)

This function serialises the tlv into a given buffer with len bytes of free space.

Parameters
[in]tlvTLV.
[in]bufPointer to buffer.
[in]buf_sizeSize of the buffer.
[out]lenLength of the serialized data.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
int KSI_TLV_serializePayload ( const KSI_TLV tlv,
unsigned char *  buf,
size_t *  len 
)

This function serialises the tlv payload into a given buffer with len bytes of free space.

Parameters
[in]tlvTLV.
[in]bufPointer to buffer.
[in,out]lenLength of the buffer, after execution its value will be the length of the serialized TLV.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
int KSI_TLV_setRawValue ( KSI_TLV tlv,
const void *  data,
size_t  data_len 
)

Set a raw value to the TLV object.

Parameters
[in]tlvThe TLV object.
[in]dataPointer to the raw data.
[in]data_lenLength of the raw data.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
char* KSI_TLV_toString ( const KSI_TLV tlv,
char *  buffer,
size_t  buffer_len 
)

This function creates a human readable representation of the TLV object.

Parameters
[in]tlvThe TLV object.
[in]bufferPointer to variable receiving the string.
[in]buffer_lenLength of the buffer.
Returns
On success returns KSI_OK, otherwise a status code is returned (see KSI_StatusCode).
int KSI_TLV_writeBytes ( const KSI_TLV tlv,
unsigned char *  buf,
size_t  buf_size,
size_t *  buf_len,
int  opt 
)