Guardtime KSI c SDK
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Typedefs | Functions
KSI Signature Builder

Typedefs

typedef struct
KSI_SignatureBuilder_st 
KSI_SignatureBuilder
 

Functions

int KSI_SignatureBuilder_openFromSignature (const KSI_Signature *sig, KSI_SignatureBuilder **builder)
 
int KSI_SignatureBuilder_openFromAggregationResp (const KSI_AggregationResp *resp, KSI_SignatureBuilder **builder)
 
int KSI_SignatureBuilder_open (KSI_CTX *ctx, KSI_SignatureBuilder **builder)
 
int KSI_SignatureBuilder_close (KSI_SignatureBuilder *builder, KSI_uint64_t rootLevel, KSI_Signature **sig)
 
void KSI_SignatureBuilder_free (KSI_SignatureBuilder *builder)
 
int KSI_SignatureBuilder_setCalendarHashChain (KSI_SignatureBuilder *builder, KSI_CalendarHashChain *cal)
 
int KSI_SignatureBuilder_applyCalendarHashChain (KSI_SignatureBuilder *builder, KSI_CalendarHashChain *cal)
 
int KSI_SignatureBuilder_addAggregationChain (KSI_SignatureBuilder *builder, KSI_AggregationHashChain *aggr)
 
int KSI_SignatureBuilder_appendAggregationChain (KSI_SignatureBuilder *builder, KSI_AggregationHashChain *aggr)
 
int KSI_SignatureBuilder_createSignatureWithAggregationChain (KSI_SignatureBuilder *builder, KSI_AggregationHashChain *aggr, KSI_Signature **sig)
 
int KSI_SignatureBuilder_setAggregationChainStartLevel (KSI_SignatureBuilder *builder, KSI_uint64_t lvl)
 
int KSI_SignatureBuilder_setCalendarAuthRecord (KSI_SignatureBuilder *builder, KSI_CalendarAuthRec *calAuth)
 
int KSI_SignatureBuilder_setPublication (KSI_SignatureBuilder *builder, KSI_PublicationRecord *pub)
 
int KSI_SignatureBuilder_setRFC3161 (KSI_SignatureBuilder *builder, KSI_RFC3161 *rfc3161)
 

Detailed Description

The signature builder is used to create a signature object from components. The interface will verify the signature internally before returning it to the caller.

Typedef Documentation

typedef struct KSI_SignatureBuilder_st KSI_SignatureBuilder

Signature builder object.

Function Documentation

int KSI_SignatureBuilder_addAggregationChain ( KSI_SignatureBuilder builder,
KSI_AggregationHashChain aggr 
)

This function adds an aggregation chain to the signature.

Parameters
[in]builderPointer to the builder.
[in]aggrAggregation chain.
Note
It is the responsibility of the caller to free the input parameters after use.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_SignatureBuilder_appendAggregationChain ( KSI_SignatureBuilder builder,
KSI_AggregationHashChain aggr 
)

This function appends the aggregation chain to the signature. The difference between KSI_SignatureBuilder_addAggregationChain is that chain is appended to the beggining of the chain list and aggregation time and chain index are updated.

Parameters
[in]builderPointer to the builder.
[in]aggrAggregation hash chain.
Note
It is the responsibility of the caller to free the input parameters after use.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_SignatureBuilder_setAggregationChainStartLevel for setting aggregation chain initialial level.
int KSI_SignatureBuilder_applyCalendarHashChain ( KSI_SignatureBuilder builder,
KSI_CalendarHashChain cal 
)

This function applies the calendar hash chain of the signature. It will replace the existing calendar hash chain if present and remove calendar hash chain authentication record or publication recond. A use case is to apply an extended calendar hash chain to a KSI signature.

Parameters
[in]builderPointer to the builder.
[in]calCalendar chain.
Note
It is the responsibility of the caller to free the input parameters after use.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_SignatureBuilder_openFromSignature to initialize builder with a KSI KSI Signature.
int KSI_SignatureBuilder_close ( KSI_SignatureBuilder builder,
KSI_uint64_t  rootLevel,
KSI_Signature **  sig 
)

If the signature is set up properly and the resulting signature is internally verifiable, then the function closes the signature builder and returns via output parameter the resulting signature.

Parameters
[in]builderPointer to signature builder.
[in]rootLevelThe level of the input hash (usually 0). This is used only for the verification.
[out]sigPointer to the receiving pointer.
Note
The caller must also call KSI_SignatureBuilder_free on the builder object.
It is the responsibility of the caller to free the resulting signature object.
See also
KSI_SignatureBuilder_free, KSI_Signature_free.
Returns
status code (KSI_OK when operation succeeded, KSI_INVALID_STATE when the building of the signature is in an invalid state, otherwise an error code).
int KSI_SignatureBuilder_createSignatureWithAggregationChain ( KSI_SignatureBuilder builder,
KSI_AggregationHashChain aggr,
KSI_Signature **  sig 
)

This function appends the aggregation chain to the signature and returns the appended signature. To use this interface, first open a signature builder from a signature (KSI_SignatureBuilder_openFromSignature), then get as many appended signatures as needed and finally free the signature builder (KSI_SignatureBuilder_free).

Parameters
[in]builderPointer to the builder.
[in]aggrAggregation hash chain.
[out]sigPointer to the receiving pointer.
Note
It is the responsibility of the caller to free the input parameters after use.
There is no need to close the signature builder after use.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_SignatureBuilder_setAggregationChainStartLevel for setting aggregation chain initialial level.
void KSI_SignatureBuilder_free ( KSI_SignatureBuilder builder)

Cleanup method for the builder.

Parameters
[in]builderPointer to the builder.
int KSI_SignatureBuilder_open ( KSI_CTX ctx,
KSI_SignatureBuilder **  builder 
)

Creates a new instance of the signature builder.

Parameters
[in]ctxThe KSI context.
[out]builderPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_SignatureBuilder_close, KSI_SignatureBuilder_free
int KSI_SignatureBuilder_openFromAggregationResp ( const KSI_AggregationResp resp,
KSI_SignatureBuilder **  builder 
)

Creates a new instance of the signature builder. The builder is initialized with the aggregation response resp.

Parameters
[in]respAggregation response.
[out]builderPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
It is users responsibility to verify the resulting singature.
It is the responsibility of the caller to free the input parameters after use.
See also
KSI_Signature_verifyWithPolicy
int KSI_SignatureBuilder_openFromSignature ( const KSI_Signature sig,
KSI_SignatureBuilder **  builder 
)

Creates a new instance of the signature builder. The builder is initialized with a copy of the input signature sig.

Parameters
[in]sigKSI signature instance.
[out]builderPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
It is the responsibility of the caller to free the input parameters after use.
int KSI_SignatureBuilder_setAggregationChainStartLevel ( KSI_SignatureBuilder builder,
KSI_uint64_t  lvl 
)

This functions sets initialial level (input hash level value) for an appendable aggregation hash chain. It should be used in case the aggregation chain input hash level is not nil. Eg. the input hash is a root hash of an aggregation chain (eg. a result of local aggregation).

Parameters
[in]builderPointer to the builder.
[in]lvlThe initial level of this hash chain.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
If applicable, the level value must be set prior to appending the corresponding hash chain.
See also
KSI_SignatureBuilder_appendAggregationChain for prepending a localy aggregated Data Hashing chains.
KSI_SignatureBuilder_createSignatureWithAggregationChain for constructing multible signatures from a local aggregation root KSI Signature.
KSI_TreeLeafHandle_getAggregationChain
int KSI_SignatureBuilder_setCalendarAuthRecord ( KSI_SignatureBuilder builder,
KSI_CalendarAuthRec calAuth 
)

This function sets the calendar authentication record of the signature.

Parameters
[in]builderPointer to the builder.
[in]calAuthCalendar chain authentication record.
Note
It is the responsibility of the caller to free the input parameters after use.
Calling this function more than once on a signature builder results in an error.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_SignatureBuilder_setCalendarHashChain ( KSI_SignatureBuilder builder,
KSI_CalendarHashChain cal 
)

This function sets the calendar hash chain of the signature.

Parameters
[in]builderPointer to the builder.
[in]calCalendar chain.
Note
Calling this function more than once on a signature builder results in an error.
It is the responsibility of the caller to free the input parameters after use.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_SignatureBuilder_setPublication ( KSI_SignatureBuilder builder,
KSI_PublicationRecord pub 
)

This function sets the publication record of the signature.

Parameters
[in]builderPointer to the builder.
[in]pubPublication record.
Note
Calling this function more than once on a signature builder results in an error.
It is the responsibility of the caller to free the input parameters after use.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_SignatureBuilder_setRFC3161 ( KSI_SignatureBuilder builder,
KSI_RFC3161 rfc3161 
)

This function sets the RFC3161 record of the signature.

Parameters
[in]builderPointer to the builder.
[in]rfc3161RFC3161 record.
Note
Calling this function more than once on a signature builder results in an error.
It is the responsibility of the caller to free the input parameters after use.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).