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

Macros

#define KSI_Signature_parse(ctx, raw, raw_len, sig)   KSI_Signature_parseWithPolicy(ctx, raw, raw_len, KSI_VERIFICATION_POLICY_INTERNAL, NULL, sig)
 
#define KSI_Signature_signAggregated(ctx, rootHash, rootLevel, signature)   KSI_Signature_signAggregatedWithPolicy(ctx, rootHash, rootLevel, KSI_VERIFICATION_POLICY_INTERNAL, NULL, signature)
 
#define KSI_Signature_extend(signature, ctx, pubRec, extended)   KSI_Signature_extendWithPolicy(signature, ctx, pubRec, KSI_VERIFICATION_POLICY_INTERNAL, NULL, extended)
 
#define KSI_Signature_extendTo(signature, ctx, to, extended)   KSI_Signature_extendToWithPolicy(signature, ctx, to, KSI_VERIFICATION_POLICY_INTERNAL, NULL, extended)
 

Typedefs

typedef struct
KSI_VerificationResult_st 
KSI_VerificationResult
 
typedef struct
KSI_VerificationStepResult_st 
KSI_VerificationStepResult
 
typedef enum
KSI_VerificationStep_en 
KSI_VerificationStep
 

Enumerations

enum  KSI_VerificationStep_en {
  KSI_VERIFY_NONE = 0, KSI_VERIFY_DOCUMENT = 0x01, KSI_VERIFY_AGGRCHAIN_INTERNALLY = 0x02, KSI_VERIFY_AGGRCHAIN_WITH_CALENDAR_CHAIN = 0x04,
  KSI_VERIFY_CALCHAIN_INTERNALLY = 0x08, KSI_VERIFY_CALCHAIN_WITH_CALAUTHREC = 0x10, KSI_VERIFY_CALCHAIN_WITH_PUBLICATION = 0x20, KSI_VERIFY_CALCHAIN_ONLINE = 0x40,
  KSI_VERIFY_CALAUTHREC_WITH_SIGNATURE = 0x80, KSI_VERIFY_PUBFILE_SIGNATURE = 0x100, KSI_VERIFY_PUBLICATION_WITH_PUBFILE = 0x200, KSI_VERIFY_PUBLICATION_WITH_PUBSTRING = 0x400
}
 

Functions

void KSI_Signature_free (KSI_Signature *signature)
 
int KSI_Signature_clone (const KSI_Signature *sig, KSI_Signature **clone)
 
int KSI_Signature_parseWithPolicy (KSI_CTX *ctx, const unsigned char *raw, size_t raw_len, const KSI_Policy *policy, KSI_VerificationContext *context, KSI_Signature **sig)
 
int KSI_Signature_serialize (const KSI_Signature *sig, unsigned char **raw, size_t *raw_len)
 
int KSI_Signature_signAggregatedWithPolicy (KSI_CTX *ctx, KSI_DataHash *rootHash, KSI_uint64_t rootLevel, const KSI_Policy *policy, KSI_VerificationContext *context, KSI_Signature **signature)
 
int KSI_Signature_signAggregationChain (KSI_CTX *ctx, int level, KSI_AggregationHashChain *chn, KSI_Signature **signature)
 
int KSI_Signature_extendWithPolicy (const KSI_Signature *signature, KSI_CTX *ctx, const KSI_PublicationRecord *pubRec, const KSI_Policy *policy, KSI_VerificationContext *context, KSI_Signature **extended)
 
int KSI_Signature_extendToWithPolicy (const KSI_Signature *signature, KSI_CTX *ctx, KSI_Integer *to, const KSI_Policy *policy, KSI_VerificationContext *context, KSI_Signature **extended)
 
int KSI_Signature_getDocumentHash (const KSI_Signature *sig, KSI_DataHash **hsh)
 
int KSI_Signature_getSigningTime (const KSI_Signature *sig, KSI_Integer **signTime)
 
int KSI_Signature_getAggregationHashChainIdentity (const KSI_Signature *sig, KSI_HashChainLinkIdentityList **identity)
 
int KSI_Signature_getPublicationRecord (const KSI_Signature *sig, KSI_PublicationRecord **pubRec)
 
int KSI_Signature_getCalendarAuthRec (const KSI_Signature *sig, KSI_CalendarAuthRec **calendarAuthRec)
 
int KSI_createSignRequest (KSI_CTX *ctx, KSI_DataHash *hsh, int lvl, KSI_AggregationReq **request)
 
int KSI_createExtendRequest (KSI_CTX *ctx, KSI_Integer *start, KSI_Integer *end, KSI_ExtendReq **request)
 
int KSI_Signature_replacePublicationRecord (KSI_Signature *sig, KSI_PublicationRecord *pubRec)
 
int KSI_Signature_getPublicationInfo (const KSI_Signature *sig, KSI_DataHash **pubHsh, KSI_Utf8String **pubStr, time_t *pubDate, KSI_LIST(KSI_Utf8String)**pubRefs, KSI_LIST(KSI_Utf8String)**repUrls)
 
KSI_SignatureKSI_Signature_ref (KSI_Signature *o)
 
int KSI_VerificationResult_init (KSI_VerificationResult *info, KSI_CTX *ctx)
 
int KSI_VerificationResult_reset (KSI_VerificationResult *info)
 

Detailed Description

At the highest level of abstraction, a KSI Blockchain signature consists of a hash chain linking the signed document to the root hash value of the aggregation tree, followed by another hash chain linking the root hash value of the aggregation tree to the published trust anchor.

Macro Definition Documentation

#define KSI_Signature_extend (   signature,
  ctx,
  pubRec,
  extended 
)    KSI_Signature_extendWithPolicy(signature, ctx, pubRec, KSI_VERIFICATION_POLICY_INTERNAL, NULL, extended)
#define KSI_Signature_extendTo (   signature,
  ctx,
  to,
  extended 
)    KSI_Signature_extendToWithPolicy(signature, ctx, to, KSI_VERIFICATION_POLICY_INTERNAL, NULL, extended)
#define KSI_Signature_parse (   ctx,
  raw,
  raw_len,
  sig 
)    KSI_Signature_parseWithPolicy(ctx, raw, raw_len, KSI_VERIFICATION_POLICY_INTERNAL, NULL, sig)
#define KSI_Signature_signAggregated (   ctx,
  rootHash,
  rootLevel,
  signature 
)    KSI_Signature_signAggregatedWithPolicy(ctx, rootHash, rootLevel, KSI_VERIFICATION_POLICY_INTERNAL, NULL, signature)

Typedef Documentation

typedef struct KSI_VerificationResult_st KSI_VerificationResult

This type keeps track of all the performed verification steps (KSI_VerificationStep_en) and their results.

Enumeration of all KSI signature (KSI_Signature) available verification steps.

typedef struct KSI_VerificationStepResult_st KSI_VerificationStepResult

This type holds a concrete result for a single verification step (KSI_VerificationStep_en).

Enumeration Type Documentation

Enumeration of all KSI signature (KSI_Signature) available verification steps.

Enumerator
KSI_VERIFY_NONE 
KSI_VERIFY_DOCUMENT 

Check if signature input hash and document hash match.

KSI_VERIFY_AGGRCHAIN_INTERNALLY 

Verify the aggregation chain internally.

KSI_VERIFY_AGGRCHAIN_WITH_CALENDAR_CHAIN 

Check if calendar chain matches aggregation chain

KSI_VERIFY_CALCHAIN_INTERNALLY 

Verify calendar chain internally.

KSI_VERIFY_CALCHAIN_WITH_CALAUTHREC 

Verify calendar chain using calendar auth record.

KSI_VERIFY_CALCHAIN_WITH_PUBLICATION 

Verify calendar chain with publication.

KSI_VERIFY_CALCHAIN_ONLINE 

Verify signature against online calendar

KSI_VERIFY_CALAUTHREC_WITH_SIGNATURE 

OK!verify that calendar authentication record signature is correct

KSI_VERIFY_PUBFILE_SIGNATURE 

check publication file signature

KSI_VERIFY_PUBLICATION_WITH_PUBFILE 

Check if publication record is stored in KSI Trust provider

KSI_VERIFY_PUBLICATION_WITH_PUBSTRING 

Check if publication record equals to publication string

Function Documentation

int KSI_createExtendRequest ( KSI_CTX ctx,
KSI_Integer start,
KSI_Integer end,
KSI_ExtendReq **  request 
)
int KSI_createSignRequest ( KSI_CTX ctx,
KSI_DataHash hsh,
int  lvl,
KSI_AggregationReq **  request 
)
int KSI_Signature_clone ( const KSI_Signature sig,
KSI_Signature **  clone 
)

Creates a clone of the signature object.

Parameters
[in]sigSignature to be cloned.
[out]clonePointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_Signature_extendToWithPolicy ( const KSI_Signature signature,
KSI_CTX ctx,
KSI_Integer to,
const KSI_Policy policy,
KSI_VerificationContext context,
KSI_Signature **  extended 
)

Extends the signature to a given time to. If to is equal to NULL, the signature is extended to the head of the extender. The extended signature is verified with the provided policy and context.

Parameters
[in]signatureKSI signature to be extended.
[in]ctxKSI context.
[in]toUTC time to extend to.
[in]policyVerification policy.
[in]contextVerification context.
[out]extendedPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
Extending to a specific time will remove calendar auth record and publication record.
int KSI_Signature_extendWithPolicy ( const KSI_Signature signature,
KSI_CTX ctx,
const KSI_PublicationRecord pubRec,
const KSI_Policy policy,
KSI_VerificationContext context,
KSI_Signature **  extended 
)

This function extends the signature to the given publication pubRec. If pubRec is NULL the signature is extended to the head of the calendar database. This function requires access to a working KSI extender or it will fail with an error. The extended signature is verified with the provided policy and context.

Parameters
[in]signatureKSI signature to be extended.
[in]ctxKSI context.
[in]pubRecPublication record.
[in]policyVerification policy.
[in]contextVerification context.
[out]extendedPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output signature is independent of the input signature and needs to be freed using KSI_Signature_free.
void KSI_Signature_free ( KSI_Signature signature)

Free the signature object.

Parameters
[in]signatureSignature object.
int KSI_Signature_getAggregationHashChainIdentity ( const KSI_Signature sig,
KSI_HashChainLinkIdentityList **  identity 
)

Function for getting a list of the identities present in all aggregation hash chains. The identities in the list are ordered - the higher-aggregator identity is before lower-aggregator identity.

Parameters
[in]sigKSI signature.
[out]identityPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_Signature_getCalendarAuthRec ( const KSI_Signature sig,
KSI_CalendarAuthRec **  calendarAuthRec 
)

Accessor method for the calendar authentication record.

Parameters
[in]sigSignature
[out]calendarAuthRecPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_Signature_getDocumentHash ( const KSI_Signature sig,
KSI_DataHash **  hsh 
)

Access method for the signed document hash as a KSI_DataHash object.

Parameters
[in]sigKSI signature.
[out]hshPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output hash hsh may not be freed by the caller.
int KSI_Signature_getPublicationInfo ( const KSI_Signature sig,
KSI_DataHash **  pubHsh,
KSI_Utf8String **  pubStr,
time_t *  pubDate,
KSI_LIST(KSI_Utf8String)**  pubRefs,
KSI_LIST(KSI_Utf8String)**  repUrls 
)

Function for getting publication information from an extended signature.

Parameters
[in]sigExtended signature including publication record.
[out]pubHshPublication hash.
[out]pubStrPublication data converted into a base-32 encoded string.
[out]pubDatePublicatoin date
[out]pubRefsPublication references.
[out]repUrlsPublication URL repositories.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output memory has to be freed by the caller
See also
KSI_DataHash_free, KSI_Utf8String_free, KSI_Utf8StringList_free
int KSI_Signature_getPublicationRecord ( const KSI_Signature sig,
KSI_PublicationRecord **  pubRec 
)

Accessor method for the published data. If the signature does not have a publication record the pubRec will be set to NULL.

Parameters
[in]sigKSI signature.
[out]pubRecPointer to receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_Signature_getSigningTime ( const KSI_Signature sig,
KSI_Integer **  signTime 
)

Access method for the signing time. The signTime is expressed as the number of seconds since 1970-01-01 00:00:00 UTC.

Parameters
[in]sigKSI signature.
[out]signTimePointer to the receiving variable.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_Signature_parseWithPolicy ( KSI_CTX ctx,
const unsigned char *  raw,
size_t  raw_len,
const KSI_Policy policy,
KSI_VerificationContext context,
KSI_Signature **  sig 
)

Parses a KSI signature from raw buffer and verifies it with the provided policy and context. The raw buffer may be freed after this function finishes. To reserialize the signature use KSI_Signature_serialize.

Parameters
[in]ctxKSI context.
[in]rawPointer to the raw signature.
[in]raw_lenLength of the raw signature.
[in]policyVerification policy.
[in]contextVerification context.
[out]sigPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
KSI_Signature* KSI_Signature_ref ( KSI_Signature o)
  • Increases the inner reference count of that object. *
    Parameters
    [in]oPointer to KSI_Signature *
    Returns
    Returns the input pointer on success or NULL on error. *
    See also
    KSI_Signature_free
int KSI_Signature_replacePublicationRecord ( KSI_Signature sig,
KSI_PublicationRecord pubRec 
)

Replaces the existing publication record of the signature.

Parameters
[in]sigKSI signature.
[in]pubRecPublication record.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_Signature_serialize ( const KSI_Signature sig,
unsigned char **  raw,
size_t *  raw_len 
)

This function serializes the signature object into raw data. To deserialize it again use KSI_Signature_parse.

Parameters
[in]sigSignature object.
[out]rawPointer to the pointer to output buffer.
[out]raw_lenPointer to the length of the buffer variable.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The output memory buffer belongs to the caller and needs to be freed by the caller using KSI_free.
int KSI_Signature_signAggregatedWithPolicy ( KSI_CTX ctx,
KSI_DataHash rootHash,
KSI_uint64_t  rootLevel,
const KSI_Policy policy,
KSI_VerificationContext context,
KSI_Signature **  signature 
)

This function signs the given root hash value (rootHash) with the aggregation level (rootLevel) of a locally aggregated hash tree. This function requires access to a working aggregaton and fails if it is not accessible. The signature is verified with the provided policy and context.

Parameters
[in]ctxKSI context.
[in]rootHashRoot value of the hash tree.
[in]rootLevelLevel of the root node (0 =< x <= 0xff).
[in]policyVerification policy.
[in]contextVerification context.
[out]signaturePointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_createSignature, KSI_Signature_create, KSI_Signature_free.
int KSI_Signature_signAggregationChain ( KSI_CTX ctx,
int  level,
KSI_AggregationHashChain chn,
KSI_Signature **  signature 
)

This function creates a new signature using the aggrehation hash chain as the input. The aggregation hash chain will be included in the signature itself.

Parameters
[in]ctxKSI context.
[in]levelThe level of the input hash of the aggregation hash chain.
[in]chnAggregation hash chain.
[out]signaturePointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
Note
The function does not consume the aggregation hash chain - the caller must free the resource.
int KSI_VerificationResult_init ( KSI_VerificationResult info,
KSI_CTX ctx 
)

Initializes the KSI_VerificationResult object.

Parameters
[in]infoPointer to KSI_VerificationResult.
[in]ctxKSI context.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_VerificationResult_reset ( KSI_VerificationResult info)

Reset the value of KSI_VerificationResult.

Parameters
[in]infoPointer to KSI_VerificationResult.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).