Guardtime KSI c SDK
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
policy.h File Reference
#include "types.h"
#include "ksi.h"
#include "common.h"

Go to the source code of this file.

Data Structures

struct  KSI_VerificationContext_st
 
struct  KSI_RuleVerificationResult_st
 
struct  KSI_RuleVerificationResult_list_st
 
struct  KSI_PolicyVerificationResult_st
 
struct  KSI_Rule_st
 

Macros

#define KSI_VERIFICATION_ERROR_CODE_LIST
 
#define KSI_VERIFICATION_ERROR_CODE_DEPRECATED_LIST
 
#define _(type, code, offset, cor, desc)   KSI_VER_ERR_##type##_##code = (offset + code),
 
#define _(type, code, offset, cor, desc)   KSI_ENUM_DEPRECATED(KSI_VER_ERR_##type##_##code, Removed from verfication process!),
 
#define KSI_RuleVerificationResultList_append(lst, o)   KSI_APPLY_TO_NOT_NULL((lst), append, ((lst), (o)))
 
#define KSI_RuleVerificationResultList_remove(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), removeElement, ((lst), (pos), (o)))
 
#define KSI_RuleVerificationResultList_indexOf(lst, o, i)   KSI_APPLY_TO_NOT_NULL((lst), indexOf, ((lst), (o), (i)))
 
#define KSI_RuleVerificationResultList_insertAt(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), insertAt, ((lst), (pos), (o)))
 
#define KSI_RuleVerificationResultList_replaceAt(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), replaceAt, ((lst), (pos), (o)))
 
#define KSI_RuleVerificationResultList_elementAt(lst, pos, o)   KSI_APPLY_TO_NOT_NULL((lst), elementAt, ((lst), (pos), (o)))
 
#define KSI_RuleVerificationResultList_length(lst)   (((lst) != NULL && (lst)->length != NULL) ? (lst)->length((lst)) : 0)
 
#define KSI_RuleVerificationResultList_find(lst, o, f, i)   KSI_APPLY_TO_NOT_NULL((lst), find, ((lst), (o), (f), (i)))
 
#define KSI_TlvElementList_sort(lst, cmp)   KSI_APPLY_TO_NOT_NULL((lst), sort, ((lst), (cmp)))
 
#define KSI_TlvElementList_foldl(lst, foldCtx, foldFn)   (((lst) != NULL) ? (((lst)->foldl != NULL) ? ((lst)->foldl((lst), (foldCtx), (foldFn))) : KSI_INVALID_STATE) : KSI_OK)
 
#define KSI_TlvElementList_find(lst, o, f, i)   KSI_APPLY_TO_NOT_NULL((lst), find, ((lst), (o), (f), (i)))
 

Typedefs

typedef enum
KSI_VerificationResultCode_en 
KSI_VerificationResultCode
 
typedef enum
KSI_VerificationErrorCode_en 
KSI_VerificationErrorCode
 
typedef struct
KSI_RuleVerificationResult_st 
KSI_RuleVerificationResult
 
typedef struct
KSI_RuleVerificationResult_list_st 
KSI_RuleVerificationResultList
 
typedef enum RuleType_en KSI_RuleType
 
typedef struct KSI_Rule_st KSI_Rule
 

Enumerations

enum  KSI_VerificationResultCode_en { KSI_VER_RES_OK = 0x00, KSI_VER_RES_NA = 0x01, KSI_VER_RES_FAIL = 0x02 }
 
enum  KSI_VerificationErrorCode_en { KSI_VER_ERR_NONE = 0x00, __NOF_VER_ERRORS }
 
enum  RuleType_en { KSI_RULE_TYPE_BASIC, KSI_RULE_TYPE_COMPOSITE_AND, KSI_RULE_TYPE_COMPOSITE_OR }
 

Functions

int KSI_RuleVerificationResultList_new (KSI_RuleVerificationResultList **list)
 
void KSI_RuleVerificationResultList_free (KSI_RuleVerificationResultList *list)
 
void KSI_RuleVerificationResult_clean (KSI_RuleVerificationResult *result)
 
int KSI_RuleVerificationResult_init (KSI_RuleVerificationResult *result)
 
const char * KSI_VerificationErrorCode_toString (int errorCode)
 
int KSI_VerificationErrorCode_fromString (const char *errCodeStr)
 
const char * KSI_Policy_getErrorString (int errorCode)
 
int KSI_Policy_create (KSI_CTX *ctx, const KSI_Rule *rules, const char *name, KSI_Policy **policy)
 
int KSI_Policy_clone (KSI_CTX *ctx, const KSI_Policy *policy, KSI_Policy **clone)
 
int KSI_Policy_setFallback (KSI_CTX *ctx, KSI_Policy *policy, const KSI_Policy *fallback)
 
int KSI_SignatureVerifier_verify (const KSI_Policy *policy, KSI_VerificationContext *context, KSI_PolicyVerificationResult **result)
 
void KSI_Policy_free (KSI_Policy *policy)
 
void KSI_PolicyVerificationResult_free (KSI_PolicyVerificationResult *result)
 
void KSI_VerificationContext_clean (KSI_VerificationContext *context)
 
int KSI_VerificationContext_init (KSI_VerificationContext *context, KSI_CTX *ctx)
 

Variables

const KSI_PolicyKSI_VERIFICATION_POLICY_EMPTY
 
const KSI_PolicyKSI_VERIFICATION_POLICY_INTERNAL
 
const KSI_PolicyKSI_VERIFICATION_POLICY_CALENDAR_BASED
 
const KSI_PolicyKSI_VERIFICATION_POLICY_KEY_BASED
 
const KSI_PolicyKSI_VERIFICATION_POLICY_PUBLICATIONS_FILE_BASED
 
const KSI_PolicyKSI_VERIFICATION_POLICY_USER_PUBLICATION_BASED
 
const KSI_PolicyKSI_VERIFICATION_POLICY_GENERAL
 

Macro Definition Documentation

#define _ (   type,
  code,
  offset,
  cor,
  desc 
)    KSI_VER_ERR_##type##_##code = (offset + code),
#define _ (   type,
  code,
  offset,
  cor,
  desc 
)    KSI_ENUM_DEPRECATED(KSI_VER_ERR_##type##_##code, Removed from verfication process!),
#define KSI_RuleVerificationResultList_append (   lst,
 
)    KSI_APPLY_TO_NOT_NULL((lst), append, ((lst), (o)))
#define KSI_RuleVerificationResultList_elementAt (   lst,
  pos,
 
)    KSI_APPLY_TO_NOT_NULL((lst), elementAt, ((lst), (pos), (o)))
#define KSI_RuleVerificationResultList_find (   lst,
  o,
  f,
 
)    KSI_APPLY_TO_NOT_NULL((lst), find, ((lst), (o), (f), (i)))
#define KSI_RuleVerificationResultList_indexOf (   lst,
  o,
 
)    KSI_APPLY_TO_NOT_NULL((lst), indexOf, ((lst), (o), (i)))
#define KSI_RuleVerificationResultList_insertAt (   lst,
  pos,
 
)    KSI_APPLY_TO_NOT_NULL((lst), insertAt, ((lst), (pos), (o)))
#define KSI_RuleVerificationResultList_length (   lst)    (((lst) != NULL && (lst)->length != NULL) ? (lst)->length((lst)) : 0)
#define KSI_RuleVerificationResultList_remove (   lst,
  pos,
 
)    KSI_APPLY_TO_NOT_NULL((lst), removeElement, ((lst), (pos), (o)))
#define KSI_RuleVerificationResultList_replaceAt (   lst,
  pos,
 
)    KSI_APPLY_TO_NOT_NULL((lst), replaceAt, ((lst), (pos), (o)))
#define KSI_TlvElementList_find (   lst,
  o,
  f,
 
)    KSI_APPLY_TO_NOT_NULL((lst), find, ((lst), (o), (f), (i)))
#define KSI_TlvElementList_foldl (   lst,
  foldCtx,
  foldFn 
)    (((lst) != NULL) ? (((lst)->foldl != NULL) ? ((lst)->foldl((lst), (foldCtx), (foldFn))) : KSI_INVALID_STATE) : KSI_OK)
#define KSI_TlvElementList_sort (   lst,
  cmp 
)    KSI_APPLY_TO_NOT_NULL((lst), sort, ((lst), (cmp)))
#define KSI_VERIFICATION_ERROR_CODE_DEPRECATED_LIST
Value:
/*Type Code Offset StrCode Description*/\
_(KEY, 1, 0x400, "KEY-01", "Certificate not found") /* Deprecated in 3.19 */ \
#define _(type, code, offset, cor, desc)
Definition: policy.h:122
#define KSI_VERIFICATION_ERROR_CODE_LIST

Helper macro containing a list of KSI signature verification error codes.

Typedef Documentation

typedef struct KSI_Rule_st KSI_Rule
typedef enum RuleType_en KSI_RuleType

Enumeration of all KSI policy (KSI_Policy) verification error codes.

Enumeration of all KSI policy (KSI_Policy) verification result codes.

Enumeration Type Documentation

Enumeration of all KSI policy (KSI_Policy) verification error codes.

Enumerator
KSI_VER_ERR_NONE 

No error.

__NOF_VER_ERRORS 

Enumeration of all KSI policy (KSI_Policy) verification result codes.

Enumerator
KSI_VER_RES_OK 

Verification succeeded, which means there's a way to prove the correctness of the signature.

KSI_VER_RES_NA 

Verification not possible, which means there is not enough data to prove or disprove the correctness of the signature.

KSI_VER_RES_FAIL 

Verification failed, which means the signature is definitely invalid or the document does not match with the signature.

Enumerator
KSI_RULE_TYPE_BASIC 

Basic rule type means that the rule pointer in KSI_Rule is a pointer to a verifying function. If the rule type is KSI_RULE_TYPE_BASIC, it calls the verifying function and examines the verification result of this function. If the function returns KSI_OK and verification result is KSI_VER_RES_OK, it continues with the next rule in the array and does so until it encounters the final empty rule. In this case the verification is successful. If at some point any of the functions does not return KSI_OK or the verification result is not KSI_VER_RES_OK, the verification fails and no more rules are processed.

KSI_RULE_TYPE_COMPOSITE_AND 

Composite rule type means that the rule pointer in KSI_Rule is not a function pointer (as was the case with the basic rule type), but instead a pointer to another array of rules. The array of rules can contain both basic and composite rules, meaning that composite rules can be nested. The composite rule is also verified in a linear fashion until a rule fails, or until all rules including the last one are successful. AND-type rule result must be successful for the verification to continue. If an AND-type rule fails, the whole rule array of which it is part of, fails as well (no further rules are verified).

KSI_RULE_TYPE_COMPOSITE_OR 

Composite rule type means that the rule pointer in KSI_Rule is not a function pointer (as was the case with the basic rule type), but instead a pointer to another array of rules. The array of rules can contain both basic and composite rules, meaning that composite rules can be nested. The composite rule is also verified in a linear fashion until a rule fails, or until all rules including the last one are successful. If an OR-type rule is successfully verified, further rules in the rule array are skipped and the whole rule of which the OR-type rule is part of, is considered successfully verified.

Function Documentation

int KSI_Policy_clone ( KSI_CTX ctx,
const KSI_Policy policy,
KSI_Policy **  clone 
)

Clones a predefined KSI_Policy, allowing the user to change the default fallback policy later. User gets ownership of the cloned policy and is responsible for freeing the policy.

Parameters
[in]ctxKSI context.
[in]policyPolicy to be cloned.
[out]clonePointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_Policy_setFallback, KSI_SignatureVerifier_verify, KSI_Policy_free
int KSI_Policy_create ( KSI_CTX ctx,
const KSI_Rule rules,
const char *  name,
KSI_Policy **  policy 
)

Creates a policy based on user defined rules. User gets ownership of the policy and is responsible for freeing the policy later with KSI_Policy_free. As the policy owner, the user is free to set a fallback policy with KSI_Policy_setFallback.

Parameters
[in]ctxKSI context.
[in]rulesPointer to user defined rules to be assigned to the policy.
[in]nameName to be given to the policy.
[out]policyPointer to the receiving pointer.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_Policy_free, KSI_SignatureVerifier_verify, KSI_Policy_setFallback
void KSI_Policy_free ( KSI_Policy policy)

Frees a user created or cloned KSI_Policy object. Predefined policies cannot be freed. The function does not free any potential fallback policy objects which the user must free separately.

Parameters
[in]policy
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_Policy_create, KSI_Policy_clone
const char* KSI_Policy_getErrorString ( int  errorCode)

Function to convert a KSI_VerificationErrorCode value to a human readable string value.

Parameters
[in]errorCodeKSI_VerificationErrorCode value.
Returns
A pointer to a statically allocated string value. This pointer may not be freed by the caller.
int KSI_Policy_setFallback ( KSI_CTX ctx,
KSI_Policy policy,
const KSI_Policy fallback 
)

Sets a fallback policy for a primary policy. The primary policy must be owned by the user, so it can be either a user created or cloned policy, but not a predefined policy.

Parameters
[in]ctxKSI context.
[in]policyPrimary policy to be secured with a fallback policy.
[in]fallbackFallback policy.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_Policy_create, KSI_Policy_clone, KSI_SignatureVerifier_verify, KSI_Policy_free
void KSI_PolicyVerificationResult_free ( KSI_PolicyVerificationResult result)

Frees the verification result object.

Parameters
[in]resultList of verification results to be freed.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_SignatureVerifier_verify
void KSI_RuleVerificationResult_clean ( KSI_RuleVerificationResult result)

Frees allocated resources in the result object.

Parameters
[in]resultVerification result to be cleaned.
See also
KSI_RuleVerificationResult_init
int KSI_RuleVerificationResult_init ( KSI_RuleVerificationResult result)

Initializes the result with default values.

Parameters
[in]resultThe verification result.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_RuleVerificationResult_clean
void KSI_RuleVerificationResultList_free ( KSI_RuleVerificationResultList list)
int KSI_RuleVerificationResultList_new ( KSI_RuleVerificationResultList **  list)
int KSI_SignatureVerifier_verify ( const KSI_Policy policy,
KSI_VerificationContext context,
KSI_PolicyVerificationResult **  result 
)

Verifies a KSI signature (provided in context) according to specified policy. If the verification fails with KSI_VER_RES_NA or KSI_VER_RES_FAIL and a fallback policy has been set with KSI_Policy_setFallback, the verification continues according to the fallback policy. A list of verification results is created into result, containing the result and error codes for the primary policy and potential fallback policies. The user is responsible for freeing the result object with KSI_PolicyVerificationResult_free.

Parameters
[in]policyPolicy to be verified.
[in]contextContext for verifying the policy.
[out]resultList of verification results
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_Policy_setFallback, KSI_PolicyVerificationResult_free
void KSI_VerificationContext_clean ( KSI_VerificationContext context)

Frees the temporary data in the context object.

Parameters
[in]contextVerification context to be cleaned.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
See also
KSI_VerificationContext_init
int KSI_VerificationContext_init ( KSI_VerificationContext context,
KSI_CTX ctx 
)

Initializes the context with default values.

Parameters
[in]contextThe verification context.
[in]ctxThe KSI context.
Returns
status code (KSI_OK, when operation succeeded, otherwise an error code).
int KSI_VerificationErrorCode_fromString ( const char *  errCodeStr)

Get KSI_VerificationErrorCode from its string representation.

Parameters
[in]errCodeStrC string.
Returns
KSI_VerificationErrorCode value. If not found KSI_VER_ERR_NONE is returned.
const char* KSI_VerificationErrorCode_toString ( int  errorCode)

Get KSI_VerificationErrorCode string representation.

Parameters
[in]errorCodeKSI_VerificationErrorCode value.
Returns
A pointer to a statically allocated string value. This pointer may not be freed by the caller.

Variable Documentation

const KSI_Policy* KSI_VERIFICATION_POLICY_CALENDAR_BASED
const KSI_Policy* KSI_VERIFICATION_POLICY_EMPTY
const KSI_Policy* KSI_VERIFICATION_POLICY_GENERAL
const KSI_Policy* KSI_VERIFICATION_POLICY_INTERNAL
const KSI_Policy* KSI_VERIFICATION_POLICY_KEY_BASED
const KSI_Policy* KSI_VERIFICATION_POLICY_PUBLICATIONS_FILE_BASED
const KSI_Policy* KSI_VERIFICATION_POLICY_USER_PUBLICATION_BASED