chapter reorganization
This commit is contained in:
parent
af3f10fc6a
commit
b64abef18c
|
|
@ -1,4 +1,6 @@
|
|||
# Behavior Driven Development
|
||||
# Implementation
|
||||
|
||||
## Behavior Driven Development
|
||||
|
||||
In Behavior Driven Development (BDD), the important role of software integration and unit tests is extended to serve both the purposes of designing the human-machine interaction flow (user journey in UX terms) and of laying down a common ground for interaction between designers and stakeholders. In this Agile software development methodology the software testing suite is based on natural language units that grant a common understanding for all participants and observers.
|
||||
|
||||
|
|
@ -54,3 +56,107 @@ The full implementation of Zencode available at the time of publishing this docu
|
|||
|
||||
|
||||
|
||||
## Declarative Schema Validation
|
||||
|
||||
In order to make the processing of Zencode more robust, all data used as input and output for its computations is validated according to predefined schemas. This makes the Zencode DSL a declarative language in which data recognition is operated before processing.
|
||||
|
||||
The data schemas are added on a per-usecase basis: they refer to specific cryptographic implementations as they are added in Zencode. Careful evaluation regarding their addition is made to realise if old schemas can be extended to include new requirements.
|
||||
|
||||
Schemas are expressed in a simple format using Lua scripting syntax, for example:
|
||||
|
||||
```lua
|
||||
-- zencode_keypair
|
||||
keypair = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
private = S.Optional(S.hex),
|
||||
public = S.ecp
|
||||
}
|
||||
```
|
||||
|
||||
The schema above is the smallest and most commonly used one, composed by one required field and two optional ones, used to validate the input and output of public/private keypairs to be used in transformations.
|
||||
|
||||
The only required field in the schema is the `public` key which is validated using the `ECP` type (`S.` is an abbreviation for the `SCHEMA.` namespace). The validation of `S.ECP` is an actual cryptographic validation: Zenroom will check that the big integer number represented by the field corresponds to a valid point on the curve. In case the validation is not passed, the execution of the Zencode script will not take place and Zenroom will return a meaningful error message indicating the wrong field.
|
||||
|
||||
The other optional field is the `private` key which can correspond to any sequence of values, therefore no cryptographic validation is possible for it; in this case then the validation used is one that refers to the encoding of the field: `S.hex` is verifying that the value is encoded with a sequence of characters that express only hexadecimal numbers (that is, 0..9 numbers and case-insensitive letters from A to Z). Other encoding tests are also available, for instance `S.base64` if that is the encoding used in the specific implementation.
|
||||
|
||||
Another more complex example follows:
|
||||
|
||||
```lua
|
||||
-- packets encoded with AES GCM
|
||||
AES-GCM = S.record {
|
||||
checksum = S.hex,
|
||||
iv = S.hex,
|
||||
schema = S.Optional(S.string),
|
||||
text = S.hex,
|
||||
zenroom = S.Optional(S.string),
|
||||
encoding = S.string,
|
||||
curve = S.string,
|
||||
pubkey = S.ecp
|
||||
}
|
||||
```
|
||||
|
||||
In this example no new validations are being used and in fact it just adds fields compared to the previous: it defines a portable packet of ciphertext data that is returned as output of AES-GCM asymmetric encryption as well is accepted as input to AES-GCM decryption. A similarity between these two examples is evident: the presence of the `schema` field. This field is a sort of "introspective" indication matching the data structure to its schema specification. If this field is not present (as it is always optional) then no validation on the data structure will take place, meaning the Zencode implementation leaves the risk (and hopefully the validation task) to the host.
|
||||
|
||||
This chapter ends with the current implementation of schema validation data types that are currently implemented for symmetric and asymmetric encryption of ciphertexts as well for implicit certificates. The schema implementation for Zencode is maintained into the sourcecode within the source file `src/lua/zencode_schemas.lua` and can be accessed by the function `ZEN.validate(data,'schema','error')` which is a wrapper of `ZEN.assert(validate(data,schemas['schema']),'error')`.
|
||||
|
||||
|
||||
```lua
|
||||
_G['schemas'] = {
|
||||
|
||||
-- packets encoded with AES GCM
|
||||
AES-GCM = S.record {
|
||||
checksum = S.hex,
|
||||
iv = S.hex,
|
||||
schema = S.Optional(S.string),
|
||||
text = S.hex,
|
||||
zenroom = S.Optional(S.string),
|
||||
encoding = S.string,
|
||||
curve = S.string,
|
||||
pubkey = S.ecp
|
||||
},
|
||||
|
||||
-- zencode_keypair
|
||||
keypair = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
private = S.Optional(S.hex),
|
||||
public = S.ecp
|
||||
},
|
||||
|
||||
-- zencode_ecqv
|
||||
certificate = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
private = S.Optional(S.big),
|
||||
public = S.ecp,
|
||||
hash = S.big,
|
||||
from = S.string,
|
||||
authkey = S.ecp
|
||||
},
|
||||
|
||||
certificate_hash = S.Record {
|
||||
schema = S.Optional(S.string),
|
||||
public = S.ecp,
|
||||
requester = S.string,
|
||||
statement = S.string,
|
||||
certifier = S.string
|
||||
},takes
|
||||
|
||||
declaration = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
from = S.string,
|
||||
to = S.string,
|
||||
statement = S.string,
|
||||
public = S.ecp
|
||||
},
|
||||
|
||||
declaration_keypair = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
requester = S.string,
|
||||
statement = S.string,
|
||||
public = S.ecp,
|
||||
private = S.hex
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
# Implicit Certificate
|
||||
## Implicit Certificates
|
||||
|
||||
This section will illustrate a Zencode implementation of the Elliptic Curve Qu-Vanstone implicit certificate scheme (ECQV) as described by the Standards for Efficient Cryptography 4 (SEC4, 2014).
|
||||
|
||||
|
|
@ -10,7 +10,7 @@ ECQV relates well to those DECODE pilots in need to authenticate participants ac
|
|||
|
||||
The limit of this implementation is the lack of threshold certification, a problem that will be solved by the Coconut [cit] implementation in Zencode language, which is still a work in progress. However it should be noted that only one pilot in DECODE (Amsterdam's Gebiedonline) may benefit from this feature, which is however not vital to the deployment.
|
||||
|
||||
## Differences with traditional certificates
|
||||
### Differences with traditional certificates
|
||||
|
||||
To justify the implementation and adoption of ECQV in place of traditional certificates, here are quickly listed three salient characteristics, closely referring to the documentation offered by the SEC4-1.0 document.
|
||||
|
||||
|
|
@ -20,7 +20,7 @@ Unlike traditional certificates, an implicit certificate does not contain a digi
|
|||
|
||||
Another difference between traditional certificates and implicit certificates is that when presented with a valid traditional certificate, one knows that the certificate belongs to someone. A valid certificate containing the certificate data string IU is a proof that the CA signed this certificate for U , and also that U knows the private key corresponding to the public key included in the certificate. One does not have this guarantee with implicit certificates, satisfying certain privacy conditions made evident by the GDPR.
|
||||
|
||||
## Zencode Implementation
|
||||
### Zencode Implementation
|
||||
|
||||
This section will demonstrate the Zencode implementation in four
|
||||
steps, covering all the transformations into a human-readable language
|
||||
|
|
|
|||
|
|
@ -1,7 +1,11 @@
|
|||
introduction.md
|
||||
bdd.md
|
||||
schema.md
|
||||
implementation.md
|
||||
implicit_certificate.md
|
||||
|
||||
# asymmetric_crypto.md
|
||||
# elgamal_vote_tally.md
|
||||
implicit_certificate.md
|
||||
conclusion.md
|
||||
|
||||
prototypes.md
|
||||
integration.md
|
||||
|
||||
# conclusion.md
|
||||
|
|
|
|||
|
|
@ -0,0 +1,28 @@
|
|||
# Integration
|
||||
|
||||
The integration of Zencode is so far relying on the same integration schemes present for Zenroom, with the addition of a minimal layer of boilerplate code for its execution. This is so to facilitate flexibility in piloting, but will be later changed to lock down to the sole execution of Zencode via new specific API calls.
|
||||
|
||||
Therefore, for now, in addition to the C call that we have exported to Java, Go, Python and Javascript languages along with utility wrappers:
|
||||
|
||||
```c
|
||||
int zenroom_exec(char *script, char *conf, char *keys,
|
||||
char *data, int verbosity);
|
||||
```
|
||||
|
||||
We also have the boilerplate internal to the `script` buffer:
|
||||
|
||||
```lua
|
||||
verbosity_level = 1
|
||||
ZEN:begin(verbosity_level)
|
||||
ZEN:parse([[
|
||||
-- your zencode here
|
||||
]])
|
||||
ZEN:run()
|
||||
```
|
||||
|
||||
The execution of actual Zencode lines happens sequentially at the time of the `ZEN:run()` call. Each line as part of the whole statement block (utterance) makes use of data types which may or may be validated and should be present in the KEYS and DATA buffers.
|
||||
|
||||
A list of Zenroom/Zencode integrated implementations follow: they have been developed in relation to each pilot software implementation as needed, covering several languages. Also notable the presence of the `zenroom` module inside the NodeJS Package Manager collection (NPM) and of course its extremely portable WebAssembly optimized build (universal binary).
|
||||
|
||||
TODO: list git repos
|
||||
|
||||
|
|
@ -1,6 +1,8 @@
|
|||
# Zencode usage
|
||||
# Evaluation of prototypes
|
||||
|
||||
In order to better explain the potential of the Zencode Domain Specific Language (DSL), approaches may change on a domain-specific basis, meaning an explanation will be more effective when tailored on the specific context it applies to. As we are on the quest to merge the description of an algorithm with its executive expression we get close to the concept of a speech act that refers to a specific context and adopts a limited taxonomy which may or may not be inscribed in a larger ontology.
|
||||
In order to better explain the potential offered by the Zencode Domain Specific Language (DSL) to DECODE's prototypes its important to understand the versatility of its usage. Approaches may change on a domain-specific basis and its possible to tailor and simplify usage on the specific context it applies to.
|
||||
|
||||
As we are on the quest to merge the description of an algorithm with its executive expression we get close to the concept of a speech act that refers to a specific context and adopts a limited taxonomy which may or may not be inscribed in a larger ontology.
|
||||
|
||||
At the time of writing our explanation can be based on an extended experimentation of in-vitro usage (lab tests) and a limited experimentation of in-vivo usage mostly bound to the conceptualization of use-cases in the IoT pilot and the Amsterdam's register pilot. In order to extend the coverage of Zencode to more pilots, we need to have a completed implementation of the underlying cryptographic contract, in this case the petition.
|
||||
|
||||
|
|
@ -16,32 +18,3 @@ What follows is another flow diagram leading to data outputs that can be reused
|
|||
|
||||
Future horizons of development of Zencode include further implementations supporting interoperable and extensible crypto schemes on the same EC curve that can still work with the above implementations, as well further refinement of the parser and extension of the schema validation. From this point onwards Zencode must be informed by piloting, while it will be also refined in cooperation with legal experts to match the smart-rule statements so far identified to express consensual data processing conditions.
|
||||
|
||||
|
||||
# Zencode Integration
|
||||
|
||||
The integration of Zencode is so far relying on the same integration schemes present for Zenroom, with the addition of a minimal layer of boilerplate code for its execution. This is so to facilitate flexibility in piloting, but will be later changed to lock down to the sole execution of Zencode via new specific API calls.
|
||||
|
||||
Therefore, for now, in addition to the C call that we have exported to Java, Go, Python and Javascript languages along with utility wrappers:
|
||||
|
||||
```c
|
||||
int zenroom_exec(char *script, char *conf, char *keys,
|
||||
char *data, int verbosity);
|
||||
```
|
||||
|
||||
We also have the boilerplate internal to the `script` buffer:
|
||||
|
||||
```lua
|
||||
verbosity_level = 1
|
||||
ZEN:begin(verbosity_level)
|
||||
ZEN:parse([[
|
||||
-- your zencode here
|
||||
]])
|
||||
ZEN:run()
|
||||
```
|
||||
|
||||
The execution of actual Zencode lines happens sequentially at the time of the `ZEN:run()` call. Each line as part of the whole statement block (utterance) makes use of data types which may or may be validated and should be present in the KEYS and DATA buffers.
|
||||
|
||||
A list of Zenroom/Zencode integrated implementations follow: they have been developed in relation to each pilot software implementation as needed, covering several languages. Also notable the presence of the `zenroom` module inside the NodeJS Package Manager collection (NPM) and of course its extremely portable WebAssembly optimized build (universal binary).
|
||||
|
||||
TODO: list git repos
|
||||
|
||||
104
views/schema.md
104
views/schema.md
|
|
@ -1,104 +0,0 @@
|
|||
# Declarative Schema Validation
|
||||
|
||||
In order to make the processing of Zencode more robust, all data used as input and output for its computations is validated according to predefined schemas. This makes the Zencode DSL a declarative language in which data recognition is operated before processing.
|
||||
|
||||
The data schemas are added on a per-usecase basis: they refer to specific cryptographic implementations as they are added in Zencode. Careful evaluation regarding their addition is made to realise if old schemas can be extended to include new requirements.
|
||||
|
||||
Schemas are expressed in a simple format using Lua scripting syntax, for example:
|
||||
|
||||
```lua
|
||||
-- zencode_keypair
|
||||
keypair = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
private = S.Optional(S.hex),
|
||||
public = S.ecp
|
||||
}
|
||||
```
|
||||
|
||||
The schema above is the smallest and most commonly used one, composed by one required field and two optional ones, used to validate the input and output of public/private keypairs to be used in transformations.
|
||||
|
||||
The only required field in the schema is the `public` key which is validated using the `ECP` type (`S.` is an abbreviation for the `SCHEMA.` namespace). The validation of `S.ECP` is an actual cryptographic validation: Zenroom will check that the big integer number represented by the field corresponds to a valid point on the curve. In case the validation is not passed, the execution of the Zencode script will not take place and Zenroom will return a meaningful error message indicating the wrong field.
|
||||
|
||||
The other optional field is the `private` key which can correspond to any sequence of values, therefore no cryptographic validation is possible for it; in this case then the validation used is one that refers to the encoding of the field: `S.hex` is verifying that the value is encoded with a sequence of characters that express only hexadecimal numbers (that is, 0..9 numbers and case-insensitive letters from A to Z). Other encoding tests are also available, for instance `S.base64` if that is the encoding used in the specific implementation.
|
||||
|
||||
Another more complex example follows:
|
||||
|
||||
```lua
|
||||
-- packets encoded with AES GCM
|
||||
AES-GCM = S.record {
|
||||
checksum = S.hex,
|
||||
iv = S.hex,
|
||||
schema = S.Optional(S.string),
|
||||
text = S.hex,
|
||||
zenroom = S.Optional(S.string),
|
||||
encoding = S.string,
|
||||
curve = S.string,
|
||||
pubkey = S.ecp
|
||||
}
|
||||
```
|
||||
|
||||
In this example no new validations are being used and in fact it just adds fields compared to the previous: it defines a portable packet of ciphertext data that is returned as output of AES-GCM asymmetric encryption as well is accepted as input to AES-GCM decryption. A similarity between these two examples is evident: the presence of the `schema` field. This field is a sort of "introspective" indication matching the data structure to its schema specification. If this field is not present (as it is always optional) then no validation on the data structure will take place, meaning the Zencode implementation leaves the risk (and hopefully the validation task) to the host.
|
||||
|
||||
This chapter ends with the current implementation of schema validation data types that are currently implemented for symmetric and asymmetric encryption of ciphertexts as well for implicit certificates. The schema implementation for Zencode is maintained into the sourcecode within the source file `src/lua/zencode_schemas.lua` and can be accessed by the function `ZEN.validate(data,'schema','error')` which is a wrapper of `ZEN.assert(validate(data,schemas['schema']),'error')`.
|
||||
|
||||
|
||||
```lua
|
||||
_G['schemas'] = {
|
||||
|
||||
-- packets encoded with AES GCM
|
||||
AES-GCM = S.record {
|
||||
checksum = S.hex,
|
||||
iv = S.hex,
|
||||
schema = S.Optional(S.string),
|
||||
text = S.hex,
|
||||
zenroom = S.Optional(S.string),
|
||||
encoding = S.string,
|
||||
curve = S.string,
|
||||
pubkey = S.ecp
|
||||
},
|
||||
|
||||
-- zencode_keypair
|
||||
keypair = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
private = S.Optional(S.hex),
|
||||
public = S.ecp
|
||||
},
|
||||
|
||||
-- zencode_ecqv
|
||||
certificate = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
private = S.Optional(S.big),
|
||||
public = S.ecp,
|
||||
hash = S.big,
|
||||
from = S.string,
|
||||
authkey = S.ecp
|
||||
},
|
||||
|
||||
certificate_hash = S.Record {
|
||||
schema = S.Optional(S.string),
|
||||
public = S.ecp,
|
||||
requester = S.string,
|
||||
statement = S.string,
|
||||
certifier = S.string
|
||||
},takes
|
||||
|
||||
declaration = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
from = S.string,
|
||||
to = S.string,
|
||||
statement = S.string,
|
||||
public = S.ecp
|
||||
},
|
||||
|
||||
declaration_keypair = S.record {
|
||||
schema = S.Optional(S.string),
|
||||
requester = S.string,
|
||||
statement = S.string,
|
||||
public = S.ecp,
|
||||
private = S.hex
|
||||
}
|
||||
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
Loading…
Reference in New Issue