or
or
By clicking below, you agree to our terms of service.
New to HackMD? Sign up
Syntax | Example | Reference | |
---|---|---|---|
# Header | Header | 基本排版 | |
- Unordered List |
|
||
1. Ordered List |
|
||
- [ ] Todo List |
|
||
> Blockquote | Blockquote |
||
**Bold font** | Bold font | ||
*Italics font* | Italics font | ||
~~Strikethrough~~ | |||
19^th^ | 19th | ||
H~2~O | H2O | ||
++Inserted text++ | Inserted text | ||
==Marked text== | Marked text | ||
[link text](https:// "title") | Link | ||
![image alt](https:// "title") | Image | ||
`Code` | Code |
在筆記中貼入程式碼 | |
```javascript var i = 0; ``` |
|
||
:smile: | ![]() |
Emoji list | |
{%youtube youtube_id %} | Externals | ||
$L^aT_eX$ | LaTeX | ||
:::info This is a alert area. ::: |
This is a alert area. |
On a scale of 0-10, how likely is it that you would recommend HackMD to your friends, family or business associates?
Please give us some advice and help us improve HackMD.
Syncing
xxxxxxxxxx
Hora Reference Verifier Specification
tags:
Hora
Overview
A reference verifier in the framework is a component that is responsible to verify a specific artifact type(s) using the provided configuration. It provides the following capabilities
CanVerify
This document proposes a generic plugin-based solution for integrating different verifiers into the framework.
Terminology
The following terms will be used throughout the document
The following sections of the document aims to specify the interface between "framework" and "plugins"
Specification
The verifier specification defines
Section1 : Verifier Configuration format
The framework can be configured with a set of parameters that are used by both the framework and plugins. When a specific plugin is executed, its corresponding parameters will be passed as an execution configuration to the plugin. The framework MAY support dynamic updates to the configuration as needed and hence it is recommended for the plugins to not consider this configuration as static and always use the config passed by the framework for execution.
Verifier Configuration format
The verifier configuration is [TBD] YAML/JSON with the following properties
Plugin Configuration objects
The following are the keys used to describe configuration of individual plugins.
matchingLabels
Any other fields specified for a plugin other than the above mentioned are considered as opaque. The framework MUST preserve unknown fields and pass through these fields to the plugins at the time of execution. Plugins may define additional fields that they accept and may generate an error if called with unknown fields.
Example verifier configuration
Section2 : Verifier Interface
The framework defines an interface for all the capabilities provided by the verifier.
An interace defined in
golang
:Name
The method is used to get the name of the verifier.
CanVerify
The framework will invoke this method of the verifier to determine if it supports verification of a given artifact reference.
Verify
If verifier acknowledges its support for a reference type, the framework will invoke this method on the verifier to trigger the verification of the artifact reference. In addition to the artifact reference that has to be verified, the framework MUST include the associated referrer store and the framework's execution engine as part of the invocation. This will enable the verifier to query additional data from the store and also to initiate nested verification as needed.
Section 3 : Plugin Based Verifier
The framework MUST provide a reference implementation of the verifier interface using the plugin architecture It will execute the configured plugins to implement the methods of the interface.
The interface method
CanVerify
can be implemented by the framework using the verifier configuration without executing the plugin. It can useartifactTypes
key (ormatchingLabels
) to determine the support of a verifier plugin for a given artifact reference.Nested verification can also be handled by the framework with the use of executor engine that is pasased through the interface method.
The rest of the sections of the document defines the protocol for executing the plugins to implement the
Verify
method of the verifier interface.Section 4: Plugin Execution Protocol
The protocol is based on the execution of binaries invoked by the framework. The framework passes parameters to the plugin via environment variables and configuration. The configuration is supplied via
stdin
. The plugin returns the result onstdout
on success, or an error onstderr
if the verification fails. Configuration and results are encoded using JSON format.There are two types of inputs that are passed to the plugin. They are parameters which define invokation specific settings and the other is configuration that includes verifier and store configuration settings.
Parameters
Execution parameters are passed to the plugins via OS environment variables. The parameters that are passed to a verifier are defined below
VERIFY
{DNS/IP}/{Repository}:[name|digest]
version
field of the verifier configuration.Execution Configuration
When a plugin is registered using the configuration, the framework interprets the configuration per plugin and transforms it to a format that is expected by the plugin. This section describes the transformations made by the framework before the configuration is passed to the plugin.
The execution configuration for a plugin invocation is encoded in JSON. It will contain the plugin configuration that is provided by the user, primarily unchanged except for the specified additions
The execution configuration provided by the framework will contain the following fields.
config
: A JSON object representing the plugin configuration provided as part of registration with the framework and passed unchanged.storeConfig
: A JSON object representing the configuration of the store that will be used to create a store plugin to fetch additional data needed for verificationreferenceDesc
: A JSON object that has the descriptor properties of a reference type.Section 5: Result Types
Plugins can return either a Success or Error result type.
Success
The output of the verification process will be returned by the plugin. It MUST output a JSON object with the following properties upon successful
VERIFY
operationisSuccess
(bool) Indicates if the artifact is verified successfully or not.results
: (list of strings) A list of strings that describe the outcomes of the verification process.name
: (string) The name of the verifier plugin which matches with the name provided as part of the registration.Error
Plugins should output a JSON object with the following properties if they encounter an error
code
: A numeric error code as described belowmsg
: A short message describing the errordetails
: More details describing the error.[TODO] Add the error codes after the implementation
Section 5: Plugin Implementation
The framework MAY provide libraries that can provide skeletons for writing plugins. These libraries can scaffold the parameter and configuration parsing and transformation and can define methods that the plugin writers can override for the implementation. These libraries also should catch any exceptions retruned from the plugins and return a proper error result to the framework. A simple CLI for example
hora plugin verifier add myverifier
to create a stub for a plugin using these libraries MAY be provided by the framework.Appendix : Examples
A example protocol sequence for a
verify
operation is given belowociregistry
will be used as the reference for a subjectregistry.wabbit-networks.io:5000/net-monitor:signed@sha256:a0fc570a245b09ed752c42d600ee3bb5b4f77bbd70d8898780b7ab43454530eb
and will be verifiedartifactTypes
property to match the verifier plugin for the above reference type. In this case, the verifier with the namenv2verifier
supports its verification.nv2verifier
with the following environment variablesVERIFY
registry.wabbit-networks.io:5000/net-monitor:signed@sha256:a0fc570a245b09ed752c42d600ee3bb5b4f77bbd70d8898780b7ab43454530eb
1.0.0
nv2verifier
verifies the artifact using the provided configuration and returns a following JSON result