Documentation ¶
Overview ¶
Package pdu defines the KSI data structures and provides their manipulation methods.
Index ¶
- Constants
- func LevelAdd(l, r byte) (byte, error)
- func LevelSubtract(l, r byte) (byte, error)
- type AggrAck
- type AggrChainInit
- type AggrReq
- type AggrResp
- func (r *AggrResp) AggregationChainList() ([]*AggregationChain, error)
- func (r *AggrResp) CalendarAuthRec() (*CalendarAuthRec, error)
- func (r *AggrResp) CalendarChain() (*CalendarChain, error)
- func (r *AggrResp) Err() error
- func (r *AggrResp) ErrorMsg() (string, error)
- func (r *AggrResp) PublicationRec() (*PublicationRec, error)
- func (r *AggrResp) RFC3161() (*RFC3161, error)
- func (r *AggrResp) RequestID() (uint64, error)
- func (r *AggrResp) Status() (uint64, error)
- type AggregationChain
- func (c *AggregationChain) Aggregate(startLevel byte) (hash.Imprint, byte, error)
- func (c *AggregationChain) AggregationAlgo() (hash.Algorithm, error)
- func (c *AggregationChain) AggregationTime() (time.Time, error)
- func (c *AggregationChain) CalculateShape() (uint64, error)
- func (c *AggregationChain) ChainIndex() ([]uint64, error)
- func (c *AggregationChain) ChainLinks() ([]*ChainLink, error)
- func (c *AggregationChain) Identity() (HashChainLinkIdentityList, error)
- func (c *AggregationChain) InputData() ([]byte, error)
- func (c *AggregationChain) InputHash() (hash.Imprint, error)
- func (c *AggregationChain) String() string
- type AggregationChainBuilder
- func (b *AggregationChainBuilder) AddChainLink(isLeft bool, lvlCorrection byte, siblingData LinkSiblingDataSetter) error
- func (b *AggregationChainBuilder) AdjustLevelCorrection(calc LevelCalculator, lvl byte) error
- func (b *AggregationChainBuilder) Build() (*AggregationChain, error)
- func (b *AggregationChainBuilder) PrependChainIndex(i []uint64) error
- func (b *AggregationChainBuilder) SetAggregationTime(t time.Time) error
- type AggregationChainList
- type AggregationReqSetting
- type AggregatorPdu
- type AggregatorReq
- func (r *AggregatorReq) AggregationReq() (*AggrReq, error)
- func (r *AggregatorReq) Clone() (*AggregatorReq, error)
- func (r *AggregatorReq) Config() (*Config, error)
- func (r *AggregatorReq) Context() context.Context
- func (r *AggregatorReq) Encode() ([]byte, error)
- func (r *AggregatorReq) HMAC() (hash.Imprint, error)
- func (r *AggregatorReq) Header() (*Header, error)
- func (r *AggregatorReq) SetHeader(hdr *Header) error
- func (r *AggregatorReq) UpdateHMAC(alg hash.Algorithm, key string) error
- func (r *AggregatorReq) UpdateRequestID(id uint64) error
- func (r *AggregatorReq) WithContext(ctx context.Context) *AggregatorReq
- type AggregatorResp
- func (r *AggregatorResp) AggregationResp() (*AggrResp, error)
- func (r *AggregatorResp) Clone() (*AggregatorResp, error)
- func (r *AggregatorResp) Config() (*Config, error)
- func (r *AggregatorResp) Decode(raw []byte) error
- func (r *AggregatorResp) Encode() ([]byte, error)
- func (r *AggregatorResp) Err() error
- func (r *AggregatorResp) SetConfig(c *Config) error
- func (r *AggregatorResp) Verify(alg hash.Algorithm, key string) error
- type CalendarAuthRec
- type CalendarChain
- func (c *CalendarChain) Aggregate() (hash.Imprint, error)
- func (c *CalendarChain) AggregationTime() (time.Time, error)
- func (c *CalendarChain) CalculateAggregationTime() (time.Time, error)
- func (c *CalendarChain) ChainLinks() ([]*ChainLink, error)
- func (c *CalendarChain) InputHash() (hash.Imprint, error)
- func (c *CalendarChain) PublicationTime() (time.Time, error)
- func (c *CalendarChain) RightLinkMatch(l *CalendarChain) error
- func (c *CalendarChain) String() string
- func (c *CalendarChain) VerifyCompatibility(with *CalendarChain) error
- type CertificateRecord
- type ChainLink
- func (l *ChainLink) FromTlv(objTlv *tlv.Tlv) error
- func (l *ChainLink) Identity() (*HashChainLinkIdentity, error)
- func (l *ChainLink) IsLeft() (bool, error)
- func (l *ChainLink) LegacyID() (*LegacyID, error)
- func (l *ChainLink) LevelCorrection() (uint64, error)
- func (l *ChainLink) MetaData() (*MetaData, error)
- func (l *ChainLink) SiblingHash() (hash.Imprint, error)
- func (l *ChainLink) String() string
- func (l *ChainLink) ToTlv(enc *tlv.Encoder) (*tlv.Tlv, error)
- type ChainLinkList
- type Config
- func (c *Config) AggrAlgo() (hash.Algorithm, error)
- func (c *Config) AggrPeriod() (uint64, error)
- func (c *Config) CalFirst() (uint64, error)
- func (c *Config) CalLast() (uint64, error)
- func (c *Config) Consolidate(cfg *Config, limits ConfigLimits, logic ConfigConsStrategy) error
- func (c *Config) MaxLevel() (byte, error)
- func (c *Config) MaxReq() (uint64, error)
- func (c *Config) ParentURI() ([]string, error)
- func (c *Config) String() string
- type ConfigConsStrategy
- type ConfigLimits
- type Error
- type ExtReq
- type ExtResp
- type ExtenderPdu
- type ExtenderReq
- func (r *ExtenderReq) Clone() (*ExtenderReq, error)
- func (r *ExtenderReq) Config() (*Config, error)
- func (r *ExtenderReq) Context() context.Context
- func (r *ExtenderReq) Encode() ([]byte, error)
- func (r *ExtenderReq) ExtendingReq() (*ExtReq, error)
- func (r *ExtenderReq) HMAC() (hash.Imprint, error)
- func (r *ExtenderReq) Header() (*Header, error)
- func (r *ExtenderReq) SetHeader(hdr *Header) error
- func (r *ExtenderReq) UpdateHMAC(alg hash.Algorithm, key string) error
- func (r *ExtenderReq) UpdateRequestID(id uint64) error
- func (r *ExtenderReq) WithContext(ctx context.Context) *ExtenderReq
- type ExtenderResp
- func (r *ExtenderResp) Clone() (*ExtenderResp, error)
- func (r *ExtenderResp) Config() (*Config, error)
- func (r *ExtenderResp) Decode(raw []byte) error
- func (r *ExtenderResp) Encode() ([]byte, error)
- func (r *ExtenderResp) Err() error
- func (r *ExtenderResp) ExtendingResp() (*ExtResp, error)
- func (r *ExtenderResp) SetConfig(c *Config) error
- func (r *ExtenderResp) Verify(alg hash.Algorithm, key string) error
- type ExtendingReqSetting
- type HashChainLinkIdentity
- func (id *HashChainLinkIdentity) ClientID() (string, error)
- func (id *HashChainLinkIdentity) MachineID() (string, error)
- func (id *HashChainLinkIdentity) RequestTime() (uint64, error)
- func (id *HashChainLinkIdentity) SequenceNr() (uint64, error)
- func (id *HashChainLinkIdentity) String() string
- func (id *HashChainLinkIdentity) Type() HashChainLinkIdentityType
- type HashChainLinkIdentityList
- type HashChainLinkIdentityType
- type Header
- type LegacyID
- type LevelCalculator
- type LinkSiblingDataSetter
- type MetaData
- func (m *MetaData) ClientID() (string, error)
- func (m *MetaData) Encode() ([]byte, error)
- func (m *MetaData) EncodeToTlv() (*tlv.Tlv, error)
- func (m *MetaData) FromTlv(objTlv *tlv.Tlv) error
- func (m *MetaData) HasPadding() bool
- func (m *MetaData) MachineID() (string, error)
- func (m *MetaData) ReqTime() (uint64, error)
- func (m *MetaData) SequenceNr() (uint64, error)
- func (m *MetaData) String() string
- func (m *MetaData) ToTlv(enc *tlv.Encoder) (*tlv.Tlv, error)
- type MetaDataOptional
- type PublicationData
- func (p *PublicationData) Base32() (string, error)
- func (p *PublicationData) Bytes() ([]byte, error)
- func (p *PublicationData) Equal(u *PublicationData) bool
- func (p *PublicationData) PublicationTime() (time.Time, error)
- func (p *PublicationData) PublishedHash() (hash.Imprint, error)
- func (p *PublicationData) String() string
- type PublicationDataBuilder
- type PublicationRec
- type PublicationRecOptional
- type PublicationsHeader
- type RFC3161
- func (r *RFC3161) AggregationTime() (time.Time, error)
- func (r *RFC3161) ChainIndex() ([]uint64, error)
- func (r *RFC3161) InputData() ([]byte, error)
- func (r *RFC3161) InputHash() (hash.Imprint, error)
- func (r *RFC3161) OutputHash(algorithm hash.Algorithm) (hash.Imprint, error)
- func (r *RFC3161) SigAttrAlgo() (hash.Algorithm, error)
- func (r *RFC3161) TstInfoAlgo() (hash.Algorithm, error)
- type RequestHeaderFunc
- type SignatureData
Constants ¶
const ( // TreeMaxLevel is the maximum height of a tree. TreeMaxLevel byte = 0xff // MaxSize is the maximum size in bytes of a PDU. MaxSize = 0xffff + 4 )
Variables ¶
This section is empty.
Functions ¶
func LevelAdd ¶
LevelAdd is aggregation chain level correction calculation strategy for summing provided values. The sum of the value must not exceed maximum tree level.
func LevelSubtract ¶
LevelSubtract is aggregation chain level correction calculation strategy for subtracting the value r from l. Value l must be greater than r, otherwise an error is returned.
Types ¶
type AggrAck ¶
type AggrAck struct {
// contains filtered or unexported fields
}
AggrAck is a client that can send acknowledgment requests to a server to verify if the server is reachable, and to estimate network latency for tuning its own aggregation schedule. The client sends a request message where the payload contains the 'aggregator acknowledgment request' record, optionally containing the time when client sent the request (according to client's local clock) in the 'request time' field. The server should respond immediately (without waiting for the end of its aggregation round) with an 'aggregator acknowledgment' message where all applicable fields are populated as follows:
- 'request time': the same value as in the corresponding client request, if present there;
- 'receipt time': the time when the request was received (according to server's local clock). If an aggregation request was received in the same PDU as the acknowledgment request, the 'request time' metadata field of the generated aggregation hash chain will have the same value as the 'receipt time' of the acknowledgment;
- 'acknowledgment time': the time when the acknowledgment was generated (according to server's local clock). Present only if it substantially differs from 'receipt time' (added at the discretion of the server's implementation);
- 'aggregation delay': the time from receiving the client's request to the end of the server's current aggregation round in milliseconds;
- 'aggregation period': duration of server's aggregation round in milliseconds;
- 'aggregation drift': the drift of the server's aggregation schedule in milliseconds. Normally the server would start a new aggregation round every time the number of milliseconds since 1970-01-01T00:00:00Z is evenly divisible by 'aggregation period'. To compensate for network latency and better align its aggregation schedule with its parents, the server instead starts a new round when the division yields 'aggregation drift' as the remainder.
type AggrChainInit ¶
type AggrChainInit func(*aggregationChainBuilder) error
AggrChainInit is initializer for AggregationChainBuilder.
func BuildFromAggregationChain ¶
func BuildFromAggregationChain(aggrChain *AggregationChain) AggrChainInit
BuildFromAggregationChain will initialize AggregationChainBuilder with specified AggregationChain. Builder operations will not affect original input aggregation hash chain.
func BuildFromImprint ¶
func BuildFromImprint(aggrAlgo hash.Algorithm, inputHash hash.Imprint) AggrChainInit
BuildFromImprint will initialize AggregationChainBuilder with aggregation hash algorithm and input hash.
type AggrReq ¶
type AggrReq struct {
// contains filtered or unexported fields
}
AggrReq is an aggregation request message containing following data fields:
- 'request identifier': a number used to establish a relation between the request and the corresponding responses;
- 'request hash': either a hash value of the data to be signed or the root hash value of the client's aggregation tree;
- 'request level': the level value of the aggregation tree node from which the 'request hash' comes, or absent if 'request hash' is a direct hash of client data (not an aggregation result).
func (*AggrReq) RequestHash ¶
RequestHash returns aggregation request document hash. In case the request hash is missing, an error is returned.
func (*AggrReq) RequestLevel ¶
RequestLevel returns aggregation request input hash level. In case the aggregation request is missing, 0 is returned.
type AggrResp ¶
type AggrResp struct {
// contains filtered or unexported fields
}
AggrResp is a server's reaction to an aggregation request message. There may be several responses associated with an aggregation request. The responses can be matched to a request using the 'request identifier' field. An aggregator response message has the following data fields:
- 'request identifier': normally the same value as in the corresponding client request, with the following exceptions:
- if the request identifier was missing in the client request, the server responds with an INVALID PAYLOAD error with the request identifier set to 0. Clients should avoid using 0 as a request identifier to prevent confusion with this placeholder value;
- if the request identifier in the client request was too long, it is truncated to contain as many least significant bits as the server can handle;
- handling of simultaneous requests with equal identifiers is implementation-defined. Possible actions include ignoring the condition and responding to all requests, treating the requests as duplicates and only responding to one of them, etc;
- 'status': a status code, where 0 means success and non-zero value is an error code;
- 'error message': an optional free-form error message;
- 'KSI item': a part of a KSI signature. There may be several KSI items in one aggregator response.
func (*AggrResp) AggregationChainList ¶
func (r *AggrResp) AggregationChainList() ([]*AggregationChain, error)
AggregationChainList returns aggregation chain list. If not present, an error is returned.
func (*AggrResp) CalendarAuthRec ¶
func (r *AggrResp) CalendarAuthRec() (*CalendarAuthRec, error)
CalendarAuthRec returns calendar authentication record. If not present, nil is returned.
func (*AggrResp) CalendarChain ¶
func (r *AggrResp) CalendarChain() (*CalendarChain, error)
CalendarChain returns calendar hash chain. If not present, nil is returned.
func (*AggrResp) Err ¶
Err returns aggregation response error if present, otherwise nil is returned.
func (*AggrResp) ErrorMsg ¶
ErrorMsg returns aggregation response error message. See also (AggrResp).Status().
func (*AggrResp) PublicationRec ¶
func (r *AggrResp) PublicationRec() (*PublicationRec, error)
PublicationRec returns publication record. If not present, nil is returned.
type AggregationChain ¶
type AggregationChain struct {
// contains filtered or unexported fields
}
AggregationChain is the aggregation hash chain structure consisting of the following fields:
- 'aggregation time': the completion time of the aggregation round from which the hash chain starts;
- 'chain index': a location pointer. Bit-strings that indicate the location of the component in a hash tree. The bits represent the path from the root of the tree to the location of a hash value as a sequence of moves from a parent node in the tree to either the left or right child (bit values 0 and 1, respectively);
- 'input hash' and an optional 'input data': the input for the computation specified by the hash chain;
- 'aggregation algorithm': the one-octet identifier of the hash function used to compute the output hash values of the link structures;
- 'chain links': a sequence of left and right 'chain link' structures.
func (*AggregationChain) Aggregate ¶
Aggregate aggregates the aggregation hash chain. The 'startLevel' parameter is the level of the first chain link. Returns the resulting root hash and aggregation chain height.
func (*AggregationChain) AggregationAlgo ¶
func (c *AggregationChain) AggregationAlgo() (hash.Algorithm, error)
AggregationAlgo returns aggregation chain aggregation algorithm. If algorithm is not present, an error is returned.
func (*AggregationChain) AggregationTime ¶
func (c *AggregationChain) AggregationTime() (time.Time, error)
AggregationTime returns aggregation chain aggregation time. If time is not present, an error is returned.
func (*AggregationChain) CalculateShape ¶
func (c *AggregationChain) CalculateShape() (uint64, error)
CalculateShape represents the shape of the aggregation chain as a bit-field. The bits represent the path from the root of the tree to the location of a hash value as a sequence of moves from a parent node in the tree to either the left or right child (bit values 0 and 1, respectively). Each bit sequence starts with a 1-bit to make sure no left most 0-bits are lost.
func (*AggregationChain) ChainIndex ¶
func (c *AggregationChain) ChainIndex() ([]uint64, error)
ChainIndex returns aggregation chain index. If chain index is not present, an error is returned.
func (*AggregationChain) ChainLinks ¶
func (c *AggregationChain) ChainLinks() ([]*ChainLink, error)
ChainLinks returns aggregation chain links. If links are not present, an error is returned.
func (*AggregationChain) Identity ¶
func (c *AggregationChain) Identity() (HashChainLinkIdentityList, error)
Identity returns aggregation hash chain identity. The returned list consists of individual hash chain link identities. The identities in the list are ordered - the higher-link identity is before lower-link identity.
func (*AggregationChain) InputData ¶
func (c *AggregationChain) InputData() ([]byte, error)
InputData returns aggregation chain input data. If data is not present, nil is returned.
func (*AggregationChain) InputHash ¶
func (c *AggregationChain) InputHash() (hash.Imprint, error)
InputHash returns aggregation chain input hash. If hash is not present, an error is returned.
func (*AggregationChain) String ¶
func (c *AggregationChain) String() string
String implements the Stringer interface. Returns an empty string in case of an error.
type AggregationChainBuilder ¶
type AggregationChainBuilder struct {
// contains filtered or unexported fields
}
AggregationChainBuilder provides the ability for constructing aggregation chains.
func NewAggregationChainBuilder ¶
func NewAggregationChainBuilder(init AggrChainInit) (*AggregationChainBuilder, error)
NewAggregationChainBuilder returns a new builder instance. Use the init option for setting the builder initial state.
func (*AggregationChainBuilder) AddChainLink ¶
func (b *AggregationChainBuilder) AddChainLink(isLeft bool, lvlCorrection byte, siblingData LinkSiblingDataSetter) error
AddChainLink appends a new chain link. The sibling data can be applied via functional setters (see LinkSiblingMetaData, LinkSiblingHash)
func (*AggregationChainBuilder) AdjustLevelCorrection ¶
func (b *AggregationChainBuilder) AdjustLevelCorrection(calc LevelCalculator, lvl byte) error
AdjustLevelCorrection applies newly calculated level correction value to the aggregation chain first chain link. The calculation of the new level correction value is performed based on the provided calculation strategy calc.
func (*AggregationChainBuilder) Build ¶
func (b *AggregationChainBuilder) Build() (*AggregationChain, error)
Build constructs and returns the resulting aggregation hash chain. The receiver's internal state is reset after this method returns AggregationChain.
func (*AggregationChainBuilder) PrependChainIndex ¶
func (b *AggregationChainBuilder) PrependChainIndex(i []uint64) error
PrependChainIndex adds a new index to the front of the aggregation chain index.
func (*AggregationChainBuilder) SetAggregationTime ¶
func (b *AggregationChainBuilder) SetAggregationTime(t time.Time) error
SetAggregationTime is setter for aggregation chain time.
type AggregationChainList ¶
type AggregationChainList []*AggregationChain
AggregationChainList is alias type for []*AggregationChain.
func (AggregationChainList) Aggregate ¶
func (l AggregationChainList) Aggregate(lvl byte) (hash.Imprint, error)
Aggregate aggregates the aggregation hash chain list and returns the result root hash. The aggregation result is the input hash of the calendar hash chain (CalendarChain). Note that the aggregation chain must be sequential, meaning that the root hash of previous aggregation chain must match the input hash of the following aggregation chain, otherwise an error is returned.
func (AggregationChainList) Identity ¶
func (l AggregationChainList) Identity() (HashChainLinkIdentityList, error)
Identity returns a list of the identities present in all aggregation hash chains.
func (AggregationChainList) Len ¶
func (l AggregationChainList) Len() int
Len implements sort.(Interface).
func (AggregationChainList) Less ¶
func (l AggregationChainList) Less(i, j int) bool
Less implements sort.(Interface).
func (AggregationChainList) Swap ¶
func (l AggregationChainList) Swap(i, j int)
Swap implements sort.(Interface).
type AggregationReqSetting ¶
type AggregationReqSetting func(*aggregatorReq) error
AggregationReqSetting is a functional option setter for various aggregation request settings.
func AggrReqSetRequestID ¶
func AggrReqSetRequestID(id uint64) AggregationReqSetting
AggrReqSetRequestID is aggregation requests' configuration method for setting request ID. Should be used with care.
func AggrReqSetRequestLevel ¶
func AggrReqSetRequestLevel(level byte) AggregationReqSetting
AggrReqSetRequestLevel is aggregation requests' configuration method for setting input hash input level.
type AggregatorPdu ¶
type AggregatorPdu struct {
// contains filtered or unexported fields
}
AggregatorPdu is the KSI Aggregator Protocol (KSIAP) used to deliver client requests to the server and KSI items (and also configuration parameters) from the server to the client. Different message types are used for upstream (child to parent) and downstream (parent to child) traffic.
type AggregatorReq ¶
type AggregatorReq struct {
// contains filtered or unexported fields
}
AggregatorReq is used to deliver client requests to the server.
func NewAggregationReq ¶
func NewAggregationReq(requestHash hash.Imprint, settings ...AggregationReqSetting) (*AggregatorReq, error)
NewAggregationReq constructs a new aggregation request wrapped into the AggregatorReq container. Optionally additional configuration settings can be added via settings parameter.
func NewAggregatorConfigReq ¶
func NewAggregatorConfigReq() (*AggregatorReq, error)
NewAggregatorConfigReq constructs a new aggregator configuration request.
func (*AggregatorReq) AggregationReq ¶
func (r *AggregatorReq) AggregationReq() (*AggrReq, error)
AggregationReq returns aggregation request component from the receiver container. In case the aggregation request is missing, nil is returned.
func (*AggregatorReq) Clone ¶
func (r *AggregatorReq) Clone() (*AggregatorReq, error)
Clone returns a deep copy of the origin, or nil in case of an error. Note that only request part of the AggregatorReq will be cloned, meaning header and HMAC are ignored.
func (*AggregatorReq) Config ¶
func (r *AggregatorReq) Config() (*Config, error)
Config returns request config instance. In case the configuration is not part of the request, nil is returned.
func (*AggregatorReq) Context ¶
func (r *AggregatorReq) Context() context.Context
Context returns the request's context.
The returned context is always non-nil, it defaults to the background context.
func (*AggregatorReq) Encode ¶
func (r *AggregatorReq) Encode() ([]byte, error)
Encode serializes the aggregator request into TLV binary representation.
func (*AggregatorReq) HMAC ¶
func (r *AggregatorReq) HMAC() (hash.Imprint, error)
HMAC returns the request message authentication code, or nil if not present.
func (*AggregatorReq) Header ¶
func (r *AggregatorReq) Header() (*Header, error)
Header returns aggregator request header.
func (*AggregatorReq) SetHeader ¶
func (r *AggregatorReq) SetHeader(hdr *Header) error
SetHeader is request header setter.
func (*AggregatorReq) UpdateHMAC ¶
func (r *AggregatorReq) UpdateHMAC(alg hash.Algorithm, key string) error
UpdateHMAC updates the request HMAC. The MAC is computed over all PDU message bytes up to (but excluding) the hash value within the imprint in the MAC field:
- the TLV header of the PDU element itself;
- the complete header element (both the TLV header and the value of the element);
- the complete payload elements in the order in which they appear in the PDU;
- the TLV header of the MAC element;
- the hash algorithm identifier part of the imprint representing the MAC value.
func (*AggregatorReq) UpdateRequestID ¶
func (r *AggregatorReq) UpdateRequestID(id uint64) error
UpdateRequestID updates aggregation request ID in case it is not set explicitly. Note that if the aggregator request does not contain aggregation request component, no operation is performed.
func (*AggregatorReq) WithContext ¶
func (r *AggregatorReq) WithContext(ctx context.Context) *AggregatorReq
WithContext returns the original r with its context changed to ctx. In case of an error, nil is returned.
type AggregatorResp ¶
type AggregatorResp struct {
// contains filtered or unexported fields
}
AggregatorResp used to deliver KSI items (and also configuration parameters) from the server to the client, as reaction to an aggregator request.
func (*AggregatorResp) AggregationResp ¶
func (r *AggregatorResp) AggregationResp() (*AggrResp, error)
AggregationResp returns aggregation response. Note that if the aggregator response does not contain aggregation response, nil is returned.
func (*AggregatorResp) Clone ¶
func (r *AggregatorResp) Clone() (*AggregatorResp, error)
Clone returns a deep copy of the origin, or nil in case of an error. Note that only response part of the AggregatorResp will be cloned, meaning header and HMAC are ignored.
func (*AggregatorResp) Config ¶
func (r *AggregatorResp) Config() (*Config, error)
Config returns configuration response, or nil if not present.
func (*AggregatorResp) Decode ¶
func (r *AggregatorResp) Decode(raw []byte) error
Decode de-serializes the raw TLV into the receiver aggregator response. Note that the AggregatorResp has to be created prior to calling this method.
func (*AggregatorResp) Encode ¶
func (r *AggregatorResp) Encode() ([]byte, error)
Encode returns the serialized aggregator response.
func (*AggregatorResp) Err ¶
func (r *AggregatorResp) Err() error
Err returns the response error if present, otherwise nil is returned.
func (*AggregatorResp) SetConfig ¶
func (r *AggregatorResp) SetConfig(c *Config) error
SetConfig sets new configuration instance into the response container.
func (*AggregatorResp) Verify ¶
func (r *AggregatorResp) Verify(alg hash.Algorithm, key string) error
Verify verifies the aggregator response consistency. Returns an error in following cases:
- contains a service response error;
- the response is missing mandatory element;
- HMAC calculation result does not match with the response. The HMAC is calculated based on the provided hash function ('alg') and the secret cryptographic key ('key').
type CalendarAuthRec ¶
type CalendarAuthRec struct {
// contains filtered or unexported fields
}
CalendarAuthRec contains the following fields:
- 'published data': consists of a 'publication time' and a 'published hash';
- 'signature data': an authentication record for a calendar hash chain is created in the following way: 1. The 'publication time' of the calendar hash chain is stored as the 'publication time' field of the 'published data' structure. 2. The output hash of the calendar hash chain is computed and stored as the 'published hash' field of the 'published data' structure. 3. The whole 'published data' structure (including the TLV header) is signed and the result is saved as the 'signature data' structure.
func (*CalendarAuthRec) PublicationData ¶
func (c *CalendarAuthRec) PublicationData() (*PublicationData, error)
PublicationData returns the published data, or error if not present.
func (*CalendarAuthRec) SignatureData ¶
func (c *CalendarAuthRec) SignatureData() (*SignatureData, error)
SignatureData returns the signature data of the published data, or error if not present.
type CalendarChain ¶
type CalendarChain struct {
// contains filtered or unexported fields
}
CalendarChain is calendar hash chain structure consisting of:
- pubTime: publication time (time of the calendar root hash);
- aggrTime: aggregation time (optional, default value pubTime);
- input hash: the input for the computation specified by the hash chain;
- chainLinks: a sequence of 'left link' and 'right link' structures.
func (*CalendarChain) Aggregate ¶
func (c *CalendarChain) Aggregate() (hash.Imprint, error)
Aggregate aggregates the calendar hash chain. Returns the resulting root hash.
func (*CalendarChain) AggregationTime ¶
func (c *CalendarChain) AggregationTime() (time.Time, error)
AggregationTime returns calendar hash chain aggregation time, or 0 if not present (see (time.(Time).IsZero())).
func (*CalendarChain) CalculateAggregationTime ¶
func (c *CalendarChain) CalculateAggregationTime() (time.Time, error)
CalculateAggregationTime returns aggregation time calculated based on the shape of the calendar hash chain.
func (*CalendarChain) ChainLinks ¶
func (c *CalendarChain) ChainLinks() ([]*ChainLink, error)
ChainLinks returns calendar hash chain links. If not present, an error is returned.
func (*CalendarChain) InputHash ¶
func (c *CalendarChain) InputHash() (hash.Imprint, error)
InputHash returns calendar hash chain input hash. If not present, an error is returned.
func (*CalendarChain) PublicationTime ¶
func (c *CalendarChain) PublicationTime() (time.Time, error)
PublicationTime returns calendar hash chain publication time. If not present, an error is returned.
func (*CalendarChain) RightLinkMatch ¶
func (c *CalendarChain) RightLinkMatch(l *CalendarChain) error
RightLinkMatch verifies that the right links are pairwise equal.
func (*CalendarChain) String ¶
func (c *CalendarChain) String() string
String implements fmt.(Stringer) interface.
func (*CalendarChain) VerifyCompatibility ¶
func (c *CalendarChain) VerifyCompatibility(with *CalendarChain) error
VerifyCompatibility checks if the two calendar hash chains are compatible with each other. The function performs the following checks:
- The input hashes match.
- The aggregation times match. Note that the publication times may differ.
- The right links from both calendar hash chains are pairwise equal.
The publication time from the two aggregation hash chains and also the left-links from both of the chains can differ.
type CertificateRecord ¶
type CertificateRecord struct {
// contains filtered or unexported fields
}
CertificateRecord is a representation of a public key certificate for verifying authentication records, consisting of 'certificate identifier' and 'certificate value'.
func (*CertificateRecord) Cert ¶
func (c *CertificateRecord) Cert() ([]byte, error)
Cert returns x509 certificate, or error if not present.
func (*CertificateRecord) CertID ¶
func (c *CertificateRecord) CertID() ([]byte, error)
CertID returns certificate ID, or error if not present.
func (*CertificateRecord) IsValid ¶
func (c *CertificateRecord) IsValid(at time.Time) (bool, error)
IsValid verifies that the certificate is valid at the given time.
func (*CertificateRecord) VerifySigType ¶
func (c *CertificateRecord) VerifySigType(sigType string) error
VerifySigType compares the signature type OID string representation to the one included in the x509 certificate. As an example, the signature type "1.2.840.113549.1.1.11" (for "SHA-256 with RSA encryption") would indicate a signature formed by hashing the published data with the SHA2-256 algorithm and then signing the resulting hash value with an RSA private key. See also asn1.(ObjectIdentifier).String().
type ChainLink ¶
type ChainLink struct {
// contains filtered or unexported fields
}
ChainLink is hash chain link.
For several reasons, each node in the aggregation tree includes a level indicator that must be strictly larger than the indicator in either child node. In most cases, the value in the parent node is one more than the values in the child nodes and can then be computed from the value of either child (one of which precedes the parent in the hash chain). However, if the aggregation tree is not perfectly balanced, the values in the child nodes may differ and, in this case, the level indicator must increase by more than one on the step from one child to the parent. The optional 'level correction' is used in the hash chain to indicate the correction amount (additional increase) in this case. Sibling data must consist of one, and only one, of the following three fields:
- 'sibling hash': an 'imprint' representing a hash value from the sibling node in the tree;
- 'metadata': a sub-structure that provides the ability to incorporate client identity and other information about the request into the hash chain;
- 'legacy client identifier': a client identifier converted from a legacy signature.
In case of calendar hash chain, each link field contains only a hash value from the calendar hash tree.
func (*ChainLink) Identity ¶
func (l *ChainLink) Identity() (*HashChainLinkIdentity, error)
Identity return link identity, or nil if not present.
func (*ChainLink) LevelCorrection ¶
LevelCorrection returns chain link level correction value.
func (*ChainLink) MetaData ¶
MetaData returns the metadata value, or nil if not present. See also (ChainLink).SiblingHash
func (*ChainLink) SiblingHash ¶
SiblingHash returns the sibling link hash value, or nil if not present. See also (ChainLink).MetaData
type ChainLinkList ¶
type ChainLinkList []*ChainLink
ChainLinkList is alias for '[]*ChainLink'.
func (ChainLinkList) String ¶
func (l ChainLinkList) String() string
String implements Stringer interface. Returns an empty string in case of an error.
type Config ¶
type Config struct {
// contains filtered or unexported fields
}
Config is service configuration. In order to start using KSIAP, a client must have the following information:
- parent server URI;
- its own client identifier;
- an (HMAC) authentication key.
Using this minimal information, the client can obtain additional configuration data by sending the 'configuration request' within a protocol PDU. The server responds with a 'configuration' message with all applicable fields populated as follows:
- 'maximal level': maximum level value that the nodes in the client's aggregation tree are allowed to have (relevant only in case of aggregator service);
- 'aggregation hash algorithm': identifier of the hash function that the client is recommended to use in its aggregation trees (relevant only in case of aggregator service);
- 'aggregation period': recommended duration of client's aggregation round in milliseconds (relevant only in case of aggregator service);
- 'maximum requests': maximum number of requests the client is allowed to send within one period of the recommended duration;
- 'parent URI': parent server URI. Note that there may be several parent servers listed in the configuration. Typically, these are all members of one cluster;
- 'calendar first time': aggregation time of the oldest calendar record the extender has (relevant only in case of extender service);
- 'calendar last time': aggregation time of the newest calendar record the extender has (relevant only in case of extender service).
The server may also send configuration messages without an explicit request from the client. These may be triggered by a change in the server's own configuration, for example.
func (*Config) AggrAlgo ¶
AggrAlgo returns identifier of the hash function that the client is recommended to use in its aggregation trees. Applicable for aggregation service only.
func (*Config) AggrPeriod ¶
AggrPeriod returns recommended duration of client's aggregation round in milliseconds. Applicable for aggregation service only.
func (*Config) CalFirst ¶
CalFirst returns aggregation time of the oldest calendar record the extender has. Applicable for extending service only.
func (*Config) CalLast ¶
CalLast returns aggregation time of the newest calendar record the extender has. Applicable for extending service only.
func (*Config) Consolidate ¶
func (c *Config) Consolidate(cfg *Config, limits ConfigLimits, logic ConfigConsStrategy) error
Consolidate merges the provided configuration cfg into the receiver configuration based on the provided limits and strategy.
func (*Config) MaxLevel ¶
MaxLevel returns maximum level value that the nodes in the client's aggregation tree are allowed to have. Applicable for aggregation service only.
func (*Config) MaxReq ¶
MaxReq returns maximum number of requests the client is allowed to send within the recommended duration. Applicable for aggregation and extending services.
type ConfigConsStrategy ¶
type ConfigConsStrategy struct { // MaxLevelKeepLargest: if set, the largest value is preserved. MaxLevelKeepLargest bool // AggrAlgorithm: if set to hash.SHA_NA, the latest valid value is preserved. Otherwise the applied algorithm will // override the value from 'cfg'. // Note that the applied algorithm is not verified, only the new algorithm from 'cfg' is verified (see (Algorithm).Trusted()). AggrAlgorithm hash.Algorithm // AggrPeriodKeepLargest: if set, the largest value is preserved. AggrPeriodKeepLargest bool // MaxRequestsKeepLargest: if set, the largest value is preserved. MaxRequestsKeepLargest bool // ParentUriAppend: if set, URIs from the new 'cfg' will be appended to the already present list. Otherwise only // latest will be preserved. // Note that only unique entries are kept. ParentUriAppend bool // CalFirstKeepEarliest: if set, the earliest value is preserved. // Note that the aggregation time of the newest calendar record can not be limited, thus all values // greater than CalFirstLow will be accepted. For the same reason calendar last time is not limited and the latest value // is preserved (values before calendar first time are discarded). CalFirstKeepEarliest bool }
ConfigConsStrategy is the logic upon which configuration values are consolidated. See (Config).Consolidate().
type ConfigLimits ¶
type ConfigLimits struct { // MaxLevelLow limits the lower bound of the maximum level value. MaxLevelLow uint64 // MaxLevelHigh limits the upper bound of the maximum level value. MaxLevelHigh uint64 // AggrPeriodLow limits the lower bound of the recommended duration of aggregation round. AggrPeriodLow uint64 // AggrPeriodHigh limits the upper bound of the recommended duration of aggregation round. AggrPeriodHigh uint64 // MaxReqLow limits the lower bound of the maximum number of requests within of the recommended duration. MaxReqLow uint64 // MaxReqHigh limits the upper bound of the maximum number of requests within of the recommended duration. MaxReqHigh uint64 // CalFirstLow limits the aggregation time of the oldest calendar record to be accepted. // Note that the aggregation time of the newest calendar record can not be limited, thus all values // greater than CalFirstLow will be accepted. CalFirstLow uint64 }
ConfigLimits is used for configuration consolidation. See (Config).Consolidate().
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is as a special case, where an error is returned in a reduced message, because the server lacks the information needed to populate at least some of the normally mandatory fields of the 'header' and 'mac' components of the full response.
type ExtReq ¶
type ExtReq struct {
// contains filtered or unexported fields
}
ExtReq is an extension request message containing following data fields:
- 'request identifier: a number used to establish a relation between the request and the corresponding responses;
- 'aggregation time': the time of the aggregation round from which the calendar hash chain should start;
- 'publication time': the time of the calendar root hash value to which the aggregation hash value should be connected by the calendar hash chain. Its absence means a request for a calendar hash chain from aggregation time to the most recent calendar record the server has (the 'calendar last time' field in the response and configuration messages).
func (*ExtReq) AggregationTime ¶
AggregationTime returns the time of the aggregation round from which the calendar hash chain should start.
func (*ExtReq) PublicationTime ¶
PublicationTime returns the time of the calendar root hash value to which the aggregation hash value should be connected by the calendar hash chain. If not present, 0 is returned (see time.(Time).IsZero()).
type ExtResp ¶
type ExtResp struct {
// contains filtered or unexported fields
}
ExtResp is server's reaction to an extension request message. The response can be matched to the request using the 'request identifier' field. An extender response message has the following data fields:
- 'request identifier': normally the same value as in the corresponding client request, with the following exceptions:
- if the request identifier was missing in the client request, the server responds with an INVALID PAYLOAD error with the request identifier set to 0. Clients should avoid using 0 as a request identifier to prevent confusion with this placeholder value;
- if the request identifier in the client request was too long, it is truncated to contain as many least significant bits as the server can handle;
- handling of simultaneous requests with equal identifiers is implementation-defined. Possible actions include ignoring the condition and responding to all requests, treating the requests as duplicates and only responding to one of them, etc;
- 'status': a status code, where 0 means success and non-zero value is an error code;
- 'error message': an optional free-form error message;
- 'calendar last time': aggregation time of the newest calendar record the extender has;
- 'calendar chain': a calendar hash chain that connects the global root hash value of the aggregation tree of the round specified in the request to the published hash value specified in the request.
func (*ExtResp) CalendarChain ¶
func (r *ExtResp) CalendarChain() (*CalendarChain, error)
CalendarChain returns a calendar hash chain that connects the global root hash value of the aggregation tree of the round specified in the request to the published hash value specified in the request.
func (*ExtResp) CalendarLast ¶
CalendarLast returns aggregation time of the newest calendar record the extender has. If not present, 0 is returned.
func (*ExtResp) ErrorMsg ¶
ErrorMsg returns extending response error message. See also (ExtResp).Status().
type ExtenderPdu ¶
type ExtenderPdu struct {
// contains filtered or unexported fields
}
ExtenderPdu is the KSI Extender Protocol (KSIEP) used to deliver client requests to the server and calendar hash chains (and also configuration parameters) from the server to the client. Different message types are used for upstream (child to parent) and downstream (parent to child) traffic.
type ExtenderReq ¶
type ExtenderReq struct {
// contains filtered or unexported fields
}
ExtenderReq is used to deliver client requests to the server.
func NewExtenderConfigReq ¶
func NewExtenderConfigReq() (*ExtenderReq, error)
NewExtenderConfigReq constructs a new aggregator configuration request.
func NewExtendingReq ¶
func NewExtendingReq(start time.Time, settings ...ExtendingReqSetting) (*ExtenderReq, error)
NewExtendingReq constructs a new extending request. Start parameter is the time of the aggregation round from which the calendar hash chain should start. Optionally additional configuration settings can be added via settings parameter.
func (*ExtenderReq) Clone ¶
func (r *ExtenderReq) Clone() (*ExtenderReq, error)
Clone returns a deep copy of the origin, or nil in case of an error. Note that only request part of the ExtenderReq will be cloned, meaning header and HMAC are ignored.
func (*ExtenderReq) Config ¶
func (r *ExtenderReq) Config() (*Config, error)
Config returns request config instance. Note that in case the configuration is not part of the request, nil is returned.
func (*ExtenderReq) Context ¶
func (r *ExtenderReq) Context() context.Context
Context returns the request's context.
The returned context is always non-nil, it defaults to the background context.
func (*ExtenderReq) Encode ¶
func (r *ExtenderReq) Encode() ([]byte, error)
Encode serializes the extender request into binary TLV.
func (*ExtenderReq) ExtendingReq ¶
func (r *ExtenderReq) ExtendingReq() (*ExtReq, error)
ExtendingReq returns extending request component from the receiver container. In case the extending request is missing, nil is returned.
func (*ExtenderReq) HMAC ¶
func (r *ExtenderReq) HMAC() (hash.Imprint, error)
HMAC returns the request message authentication code, or nil if not present.
func (*ExtenderReq) Header ¶
func (r *ExtenderReq) Header() (*Header, error)
Header returns the request message header, or nil if not present.
func (*ExtenderReq) SetHeader ¶
func (r *ExtenderReq) SetHeader(hdr *Header) error
SetHeader is request header setter.
func (*ExtenderReq) UpdateHMAC ¶
func (r *ExtenderReq) UpdateHMAC(alg hash.Algorithm, key string) error
UpdateHmac updates the request HMAC. The MAC is computed over all PDU message bytes up to (but excluding) the hash value within the imprint in the MAC field:
- the TLV header of the PDU element itself;
- the complete header element (both the TLV header and the value of the element);
- the complete payload elements in the order in which they appear in the PDU;
- the TLV header of the MAC element;
- the hash algorithm identifier part of the imprint representing the MAC value.
func (*ExtenderReq) UpdateRequestID ¶
func (r *ExtenderReq) UpdateRequestID(id uint64) error
UpdateRequestID updates extending request ID in case it is not set explicitly.
func (*ExtenderReq) WithContext ¶
func (r *ExtenderReq) WithContext(ctx context.Context) *ExtenderReq
WithContext returns the original r with its context changed to ctx. In case of an error, nil is returned.
type ExtenderResp ¶
type ExtenderResp struct {
// contains filtered or unexported fields
}
ExtenderResp is used to deliver calendar hash chains (and also configuration parameters) from the server to the client.
func (*ExtenderResp) Clone ¶
func (r *ExtenderResp) Clone() (*ExtenderResp, error)
Clone returns a deep copy of the origin, or nil in case of an error. Note that only response part of the ExtenderResp will be cloned.
func (*ExtenderResp) Config ¶
func (r *ExtenderResp) Config() (*Config, error)
Config returns configuration response, or nil if not present.
func (*ExtenderResp) Decode ¶
func (r *ExtenderResp) Decode(raw []byte) error
Decode de-serializes the raw TLV into the receiver extender response. Note that the ExtenderResp has to be created prior to calling this method.
func (*ExtenderResp) Encode ¶
func (r *ExtenderResp) Encode() ([]byte, error)
Encode returns the serialized extender response.
func (*ExtenderResp) Err ¶
func (r *ExtenderResp) Err() error
Err returns the response error if present, otherwise nil is returned.
func (*ExtenderResp) ExtendingResp ¶
func (r *ExtenderResp) ExtendingResp() (*ExtResp, error)
ExtendingResp returns extending response. Note that if the extender response does not contain extending response, nil is returned.
func (*ExtenderResp) SetConfig ¶
func (r *ExtenderResp) SetConfig(c *Config) error
SetConfig sets new configuration instance into the response container.
func (*ExtenderResp) Verify ¶
func (r *ExtenderResp) Verify(alg hash.Algorithm, key string) error
Verify verifies the extender response consistency. Returns an error in following cases:
- contains a service response error;
- the response is missing mandatory element;
- HMAC calculation result does not match with the response. The HMAC is calculated based on the provided hash function ('alg') and the secret cryptographic key ('key').
type ExtendingReqSetting ¶
type ExtendingReqSetting func(*extenderReq) error
ExtendingReqSetting is functional option setter for extending request.
func ExtReqSetPubTime ¶
func ExtReqSetPubTime(end time.Time) ExtendingReqSetting
ExtReqSetPubTime sets the time of the calendar root hash value to which the aggregation hash value should be connected by the calendar hash chain. Its absence means a request for a calendar hash chain from aggregation time to the most recent calendar record the server has (the 'calendar last time' field in the response and configuration messages).
func ExtReqSetRequestID ¶
func ExtReqSetRequestID(id uint64) ExtendingReqSetting
ExtReqSetRequestID is aggregation request configuration method for setting request ID, a number used to establish a relation between the request and the corresponding responses. Should be used with care.
type HashChainLinkIdentity ¶
type HashChainLinkIdentity struct {
// contains filtered or unexported fields
}
HashChainLinkIdentity is hash chain link identity.
func (*HashChainLinkIdentity) ClientID ¶
func (id *HashChainLinkIdentity) ClientID() (string, error)
ClientID returns (human-readable) textual representation of metadata client identity, or legacy ID.
func (*HashChainLinkIdentity) MachineID ¶
func (id *HashChainLinkIdentity) MachineID() (string, error)
MachineID returns a (human-readable) identifier of the machine that requested the link structure (unique at least within the cluster that shares a 'client identifier'). If not present, an empty string is returned.
func (*HashChainLinkIdentity) RequestTime ¶
func (id *HashChainLinkIdentity) RequestTime() (uint64, error)
RequestTime returns the time when the server received the request from the client, recorded as precisely as the server's clock allows. This is another option for ordering of requests processed by the same machine within one aggregation round. If not present, 0 is returned.
func (*HashChainLinkIdentity) SequenceNr ¶
func (id *HashChainLinkIdentity) SequenceNr() (uint64, error)
SequenceNr returns a local sequence number of a request assigned by the machine that created the link. Sequence numbers enable determination of the temporal order of requests processed by the same machine even within one aggregation round. If not present, 0 is returned.
func (*HashChainLinkIdentity) String ¶
func (id *HashChainLinkIdentity) String() string
String implements fmt.(Stringer) interface.
func (*HashChainLinkIdentity) Type ¶
func (id *HashChainLinkIdentity) Type() HashChainLinkIdentityType
Type returns the link identity type.
type HashChainLinkIdentityList ¶
type HashChainLinkIdentityList []*HashChainLinkIdentity
HashChainLinkIdentityList is alias for []*HashChainLinkIdentity.
func (HashChainLinkIdentityList) String ¶
func (l HashChainLinkIdentityList) String() string
String implements fmt.(Stringer) interface.
type HashChainLinkIdentityType ¶
type HashChainLinkIdentityType byte
HashChainLinkIdentityType is hash chain link identity type.
const ( // IdentityTypeUnknown is invalid type. IdentityTypeUnknown HashChainLinkIdentityType = iota // IdentityTypeLegacyID is Legacy client identifier. // A client identifier converted from a legacy signature. IdentityTypeLegacyID // IdentityTypeMetadata is a structure that provides the ability to incorporate client // identity and other information about the request into the hash chain. IdentityTypeMetadata )
type Header ¶
type Header struct {
// contains filtered or unexported fields
}
Header is the message header consisting of the following fields:
- 'login identifier': identifier of the client host for MAC key lookup. For portability, it is recommended to limit the login identifiers to valid POSIX usernames (that is, they should contain only uppercase and lowercase letters 'a' to 'z' and 'A' to 'Z', digits '0' to '9', periods '.', underscores '_', and dashes '-'.
- 'instance identifier': a number identifying invocation of the sender.
- 'message identifier': message number for duplicate filtering.
The instance and message identifier fields, when present, are used for filtering duplicate messages. The value of the 'instance identifier' field should increase every time the sending process is restarted. The 'message identifier' should sequentially number the messages within a process invocation. Having seen messages with a higher 'instance identifier' value from a client, a server may drop future messages with lower 'instance identifier' values assuming these are delayed messages from a previous invocation and thus no longer relevant. Similarly, a server may prioritize messages from a given client invocation by 'message identifier' values under the assumption that messages with lower values are more likely to be stale. Messages where the 'instance identifier' and 'message identifier' fields are absent should be considered unique. This is to accommodate short-lived client applications that typically send only a single request. For long-lived processes, the 'instance identifier' and 'message identifier' fields should be considered mandatory.
func NewHeader ¶
func NewHeader(loginID string, f RequestHeaderFunc) (*Header, error)
NewHeader returns PDU Header instance. Use parameter 'f' for applying optional Header values.
func (*Header) InstanceID ¶
InstanceID returns a number identifying invocation of the sender. If not present, 0 is returned.
func (*Header) LoginID ¶
LoginID returns the identifier of the client host for MAC key lookup. If not present, an error is returned.
func (*Header) MessageID ¶
MessageID returns message number for duplicate filtering. If not present, 0 is returned.
type LegacyID ¶
type LegacyID struct {
// contains filtered or unexported fields
}
LegacyID is a wrapper type for the legacy client identifier.
A client identifier converted from a legacy signature. The value must consist of exactly 29 octets:
- The first two octets are fixed values 03 and 00.
- The value of the third octet (at most 25) defines the length of the embedded name and is followed by that many octets of an UTF-8 string.
- Finally, the value is padded with 00 octets to the final length (note that at least one padding octet will exist in any valid structure). For example, the name 'Test' is encoded as the sequence: 03 00 04 54=T 65=e 73=s 74=t 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 (all octet values in the example are given in hexadecimal).
This option is present only to support conversion of existing signatures created before the structured 'metadata' field was introduced and thus must not be used in new signatures. Note that 03 is marked as invalid value for hash function identifier to ensure that a 'legacy client identifier' value can't be confused with a 'sibling hash' imprint.
func (*LegacyID) Bytes ¶
Bytes returns raw structure.
+------+------+---------+------------------+------------------+ | Header | StrLen | UTF8 string | Padding | +------+------+---------+------------------+------------------+ | 0x03 | 0x00 | x | ... |0x00{1..25-StrLen}| +------+------+---------+------------------+------------------+
For example, the name 'Test' is encoded as the sequence:
03 00 04 54=T 65=e 73=s 74=t 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 (all octet values in the example are given in hexadecimal).
type LevelCalculator ¶
LevelCalculator is aggregation chain level correction calculation strategy.
type LinkSiblingDataSetter ¶
type LinkSiblingDataSetter func(*chainLink) error
LinkSiblingDataSetter is functional value setter for the chain link value.
func LinkSiblingHash ¶
func LinkSiblingHash(hsh hash.Imprint) LinkSiblingDataSetter
LinkSiblingHash is sibling hash setter.
func LinkSiblingMetaData ¶
func LinkSiblingMetaData(md *MetaData) LinkSiblingDataSetter
LinkSiblingMetaData is sibling metadata setter.
type MetaData ¶
type MetaData struct {
// contains filtered or unexported fields
}
MetaData is a sub-structure that provides the ability to incorporate client identity and other information about the request into the hash chain. It must contain the 'client identifier' field and may contain any combination of the 'machine identifier', 'sequence number', and 'request time' fields:
- 'client identifier': a (human-readable) textual representation of client identity;
- 'machine identifier': a (human-readable) identifier of the machine that requested the link structure (unique at least within the cluster that shares a 'client identifier');
- 'sequence number': a local sequence number of a request assigned by the machine that created the link. Sequence numbers enable determination of the temporal order of requests processed by the same machine even within one aggregation round.
- 'request time': the time when the server received the request from the client, recorded as precisely as the server's clock allows. This is another option for ordering of requests processed by the same machine within one aggregation round.
- 'padding': an element whose purpose is to ensure that a 'metadata' value can't be confused with a 'sibling hash' imprint. This element, with the 'non-critical' and 'forward' flags set, must be the first field in the 'metadata' structure (thus the first octet of the value part of the structure is 7E, which is marked as invalid hash function identifier. The value of this element must be either one octet 01 or two octets 01 01 to make the total length of the metadata an even number (since hash functions have even-length output, the imprints embedding them have odd length and consequently even-length metadata can't be confused with an imprint).
func NewMetaData ¶
func NewMetaData(clientID string, optionals ...MetaDataOptional) (*MetaData, error)
NewMetaData returns a new metadata instance. Additional value can be applied via optionals.
func (*MetaData) ClientID ¶
ClientID returns a (human-readable) textual representation of client identity, or nil if not present.
func (*MetaData) EncodeToTlv ¶
EncodeToTlv returns the metadata in TLV representation.
func (*MetaData) HasPadding ¶
HasPadding returns true in case the metadata structure contains padding bytes, otherwise false.
func (*MetaData) MachineID ¶
MachineID returns a (human-readable) identifier of the machine that requested the link structure. If not present, an empty string is returned.
func (*MetaData) ReqTime ¶
ReqTime returns the time when the server received the request from the client. If not present, 0 is returned.
func (*MetaData) SequenceNr ¶
SequenceNr returns a local sequence number of a request assigned by the machine that created the link. If not present, 0 is returned.
type MetaDataOptional ¶
type MetaDataOptional func(*metaData) error
MetaDataOptional is functional optional value setter.
func MetaDataMachineID ¶
func MetaDataMachineID(id string) MetaDataOptional
MetaDataMachineID is setter for the optional machine ID value.
func MetaDataReqTime ¶
func MetaDataReqTime(t uint64) MetaDataOptional
MetaDataReqTime is setter for the optional request time value.
func MetaDataSequenceNr ¶
func MetaDataSequenceNr(n uint64) MetaDataOptional
MetaDataSequenceNr is setter for the optional sequence number value.
type PublicationData ¶
type PublicationData struct {
// contains filtered or unexported fields
}
PublicationData is the published data containing:
- 'publication time': represented as a 64-bit unsigned integer;
- 'published hash': output hash value of the calendar hash chain at the publication time.
func NewPublicationData ¶
func NewPublicationData(builder PublicationDataBuilder) (*PublicationData, error)
NewPublicationData returns a new publication data instance. Use the builder parameter for providing an initializer.
func (*PublicationData) Base32 ¶
func (p *PublicationData) Base32() (string, error)
Base32 returns a publication string representing the fields of the published data structure, formatted in a way suitable for printed media and manual entry into a verification tool. The representation is limited to letters and numbers and embeds a checksum to detect typing errors.
func (*PublicationData) Bytes ¶
func (p *PublicationData) Bytes() ([]byte, error)
Bytes returns the binary TLV structure.
func (*PublicationData) Equal ¶
func (p *PublicationData) Equal(u *PublicationData) bool
Equal reports whether p and u represent the same publication data instance.
func (*PublicationData) PublicationTime ¶
func (p *PublicationData) PublicationTime() (time.Time, error)
PublicationTime returns the publication time.
func (*PublicationData) PublishedHash ¶
func (p *PublicationData) PublishedHash() (hash.Imprint, error)
PublishedHash returns published hash.
func (*PublicationData) String ¶
func (p *PublicationData) String() string
String implements fmt.(Stringer) interface.
type PublicationDataBuilder ¶
type PublicationDataBuilder func(*publicationData) error
PublicationDataBuilder is the concrete publication data constructor.
func PubDataFromImprint ¶
func PubDataFromImprint(t time.Time, h hash.Imprint) PublicationDataBuilder
PubDataFromImprint returns an initializer for constructing publication data from published data, where h is the output hash of the calendar hash chain at time t.
func PubDataFromString ¶
func PubDataFromString(s string) PublicationDataBuilder
PubDataFromString returns a builder for constructing publication data from publication string.
A publication string represents the fields of the published data structure, formatted in a way suitable for printed media and manual entry into a verification tool. The representation is limited to letters and numbers and embeds a checksum to detect typing errors. The publication string is constructed as follows:
- The publication data is assembled as a concatenation of - publication time, represented as a 64-bit unsigned integer, with the bits ordered from the most significant to the least significant. Note that the publication string is not a TLV structure and, in contrast with the TLV encoding rules, the leading zeros are preserved in this encoding to ensure consistent length of the publication strings. - publication imprint, consisting of the one-byte identifier of the hash algorithm and the hash value itself.
- The CRC-32 checksum of the publication data is computed and appended to the data.
- The resulting octet sequence is represented in base32 and optionally broken into groups of 6 or 8 characters by dashes.
For example, the encoding of a publication string for 2009-02-15T00:00:00Z:
Raw data: 1.1 8-byte integer 1234656000, the POSIX time value for 2009-02-15 00:00:00 00 00 00 00 49 97 5B 00 1.2 Imprint of the root hash value, the first 01 identifies the hash algorithm as SHA2-256 01 EE 1F BC 8F D3 FD 78 FD 11 B9 E2 67 DF 9A F2 36 11 B1 C5 BE 44 F0 20 AB 8B 14 19 C9 36 72 C4 D6 2. 4-byte CRC-32 checksum of the preceding bytes EE 57 DB C6 3. In base32 encoded printable form: AAAAAA-CJS5NQ-AAPOD6-6I7U75-PD6RDO-PCM7PZV4RWCG-Y4LPSE-6AQKXC-YUDHET-M4WE23-XFPW6G
type PublicationRec ¶
type PublicationRec struct {
// contains filtered or unexported fields
}
PublicationRec represents the information related to a published hash value, possibly including the publication reference. Publication may also point (via a URI) to a hash database that is in electronic form and may contain several published hash values. A 'publication record' structure contains the following fields:
- 'published data': consists of a 'publication time' and a 'published hash';
- 'publication reference': an UTF-8 string that contains the bibliographic reference to a media outlet where the publication appeared;
- 'publications repository URI': URI of a publications' repository (publication file).
func NewPublicationRec ¶
func NewPublicationRec(pubData *PublicationData, optionals ...PublicationRecOptional) (*PublicationRec, error)
NewPublicationRec is the publication record constructor.
A publication record represents the information related to a published hash value, possibly including the publication reference. Publication may also point (via a URI) to a hash database that is in electronic form and may contain several published hash values.
func (*PublicationRec) Clone ¶
func (p *PublicationRec) Clone() (*PublicationRec, error)
Clone returns a deep copy of the receiver publication record.
func (*PublicationRec) PublicationData ¶
func (p *PublicationRec) PublicationData() (*PublicationData, error)
PublicationData returns the published data.
func (*PublicationRec) PublicationRef ¶
func (p *PublicationRec) PublicationRef() ([]string, error)
PublicationRef returns an UTF-8 string that contains the bibliographic reference to a media outlet where the publication appeared.
func (*PublicationRec) PublicationRepURI ¶
func (p *PublicationRec) PublicationRepURI() ([]string, error)
PublicationRepURI returns URI of a publication's repository (publication file).
type PublicationRecOptional ¶
type PublicationRecOptional func(r *publicationRec) error
PublicationRecOptional is an optional functional parameter to be set while publication data construction.
func PubRecOptPublicationRef ¶
func PubRecOptPublicationRef(pubRef []string) PublicationRecOptional
PubRecOptPublicationRef sets an UTF-8 string that contains the bibliographic reference to a media outlet where the publication appeared.
func PubRecOptPublicationRepURI ¶
func PubRecOptPublicationRepURI(pubRepURI []string) PublicationRecOptional
PubRecOptPublicationRepURI sets the URI of a publication's repository.
type PublicationsHeader ¶
type PublicationsHeader struct {
// contains filtered or unexported fields
}
PublicationsHeader is the publications file header consisting of:
- the version number of the file format;
- the creation time of the file;
- URI of the canonical distribution point of the file.
The two latter fields are for the benefit of clients that may receive cached copies of the file and want to ensure these copies are not stale.
type RFC3161 ¶
type RFC3161 struct {
// contains filtered or unexported fields
}
RFC3161 is the RFC 3161 compatibility record. An older implementation of the KSI service used the formats and protocols specified in the X.509 time-stamping standard. In that format, the hash value of the time-stamped datum was not signed directly, but via several intermediate structures:
- The hash value of the original datum was entered into the MessageImprint field of the TSTInfo structure.
- The hash value of the TSTInfo structure was entered into the MessageDigest field of the SignedAttributes structure.
- Finally, the hash value of the SignedAttributes structure was actually signed.
To facilitate conversion of legacy KSI signatures issued in the RFC 3161 format, the helper data structure is used, where the fields have the following meaning:
- 'aggregation time', 'chain index', 'input data' and 'input hash' fields have the same meaning as in the 'aggregation chain' structure.
- 'tstinfo prefix' and 'tstinfo suffix' fields contain the data preceding and succeeding the hash value within the TSTInfo structure.
- 'tstinfo algorithm' field contains the one-octet identifier (as defined in Table 2) of the hash function used to hash the TSTInfo structure.
- 'signed attributes prefix' and 'signed attributes suffix' fields contain the data preceding and succeeding the hash value within the SignedAttributes structure.
- 'signed attributes algorithm' field contains the one-octet identifier of the hash function used to hash the SignedAttributes structure.
The record:
- belongs to the aggregation hash chain component that has the same 'aggregation time' value and the same sequence of 'chain index' values;
- may only be applied to the first component of the aggregation chain (that is, where the input to the aggregation is client data, not output of a previous aggregation);
- acts as a data conversion filter preprocessing the data before it becomes input to the aggregation chain.
func (*RFC3161) AggregationTime ¶
AggregationTime returns aggregation chain aggregation time. If time is not present, an error is returned.
func (*RFC3161) ChainIndex ¶
ChainIndex returns aggregation chain index. If chain index is not present, an error is returned.
func (*RFC3161) InputHash ¶
InputHash returns input hash. If hash is not present, an error is returned.
func (*RFC3161) OutputHash ¶
OutputHash calculates and returns the output hash of the RFC3161 record.
func (*RFC3161) SigAttrAlgo ¶
SigAttrAlgo returns the hash function used to hash the SignedAttributes structure. If hash is not present, an error is returned.
type RequestHeaderFunc ¶
RequestHeaderFunc is request header manipulation callback which is executed on every request prior to serializing and submitting the request. The callback should be used when additional data (i.e. session ID and message ID) should be added.
type SignatureData ¶
type SignatureData struct {
// contains filtered or unexported fields
}
SignatureData consists of:
- 'signature type': a signing algorithm and signature format identifier, as assigned by IANA, represented as an UTF-8 string containing a dotted decimal object identifier (OID);
- 'signature value': the signature itself, computed and formatted according to the specified method;
- 'certificate identifier' and optionally 'certificate repository URI', with the latter pointing to a repository (e.g. a publication file) that contains the certificate identified by the 'certificate identifier'.
As an example, the signature type "1.2.840.113549.1.1.11" (for "SHA-256 with RSA encryption") would indicate a signature formed by hashing the published data with the SHA2-256 algorithm and then signing the resulting hash value with an RSA private key.
func (*SignatureData) CertID ¶
func (s *SignatureData) CertID() ([]byte, error)
CertID returns the certificate identifier. If not set, an error is returned.
func (*SignatureData) CertRepURI ¶
func (s *SignatureData) CertRepURI() (string, error)
CertRepURI returns the optional certificate repository URI, pointing to a repository (e.g. a publication file) that contains the certificate identified by the 'certificate identifier' (see (SignatureData).CertID()).
func (*SignatureData) SignatureType ¶
func (s *SignatureData) SignatureType() (string, error)
SignatureType returns the signature type. If not set, an error is returned.
A signing algorithm and signature format identifier, as assigned by IANA, represented as an UTF-8 string containing a dotted decimal object identifier (OID).
As an example, the signature type "1.2.840.113549.1.1.11" (for "SHA-256 with RSA encryption") would indicate a signature formed by hashing the published data with the SHA2-256 algorithm and then signing the resulting hash value with an RSA private key.
func (*SignatureData) SignatureValue ¶
func (s *SignatureData) SignatureValue() ([]byte, error)
SignatureValue returns the signature itself, computed and formatted according to the specified method. If not set, an error is returned.