added first block spec draft

This commit is contained in:
Kevin Froman 2019-04-04 16:56:18 -05:00
parent f7ae054d09
commit ad94c8a4ef
5 changed files with 67 additions and 4 deletions

64
docs/block-spec.md Normal file
View File

@ -0,0 +1,64 @@
# Onionr Block Spec v1.0.0
# Block Description
Onionr 'Blocks' are the primary means of sharing information in Onionr. Blocks are identified by a single hash value of their entire contents.
They contain a JSON metadata section followed by a line break, with the main data following.
In the future, the spec will be updated to use flags and MessagePack instead of JSON with english keys.
# Encryption and Signatures
Onionr blocks may be encrypted or signed. In the reference client, this is done with libsodium, for both asymmetric and symmetric encryption.
Unlike many similar projects, blocks may completely be in plaintext, making Onionr suitable for sharing information publicly.
# Metadata Section
The metadata section has the following fields. If a block contains any other field, it must be considered invalid. All metadata fields are technically optional, but many are useful and essentially necessary for most use cases.
## meta
Max byte size: 1000
Meta is a string field which can contain arbitrary sub fields. It is intended for applications and plugins to use it for arbitrary metadata information. In the reference client, if the data section is encrypted or signed, the meta section also is.
Common meta fields, such as 'type' are used by the reference Onionr client to describe the type of a block.
## sig
Max byte size: 200
Sig is a field for storing public key signatures of the block, typically ed25519. In the reference client, this field is a base64 encoded signature of the meta field combined with the block data. (**Therefore, information outside of the meta and data fields cannot be trusted to be placed there by the signer, although it can still be assured that the particular block has not been modified.**)
Note: the max field size is larger than a EdDSA signature (which is what is typically used) in order to allow other primitives for signing in alternative implementations or future versions.
## signer
Max byte size: 200
Signer is a field for specifying the public key which signed the block. In the reference client this is a base64 encoded ed25519 public key.
## time
Max byte size: 10
Time is an integer field for specifying the time of which a block was created. The trustworthiness of this field is based on one's trust of the block creator, however blocks with a time field set in the future (past a reasonable clock skew) are thrown out by the reference client.
## expire
Max byte size: 10
Expire is an integer field for specifying the time of which the block creator has indicated that the block should be deleted. The purpose of this is for voluntarily freeing the burden of unwanted blocks on the Onionr network, rather than security/privacy (since blocks could be trivially kept past expiration). Regardless, the reference client deletes blocks after a preset time if the expire field is either not set or longer than the preset time.
## pow
Max byte size: 1000
Pow is a field for placing the nonce found to make a block meet a target proof of work. In theory, a block could meet a target without a random token in this field.
## encryptType
encryptType is a field to specify the mode of encryption for a block. The values supported by Onionr are 'asym' and 'sym'.

View File

@ -325,7 +325,6 @@ class API:
if pubkey in self._core.onionrInst.communicatorInst.active_services: if pubkey in self._core.onionrInst.communicatorInst.active_services:
return Response('true') return Response('true')
except AttributeError as e: except AttributeError as e:
print('attribute error', str(e))
pass pass
return Response('false') return Response('false')

View File

@ -21,5 +21,5 @@
class OnionrValues: class OnionrValues:
def __init__(self): def __init__(self):
self.passwordLength = 20 self.passwordLength = 20
self.blockMetadataLengths = {'meta': 1000, 'sig': 200, 'signer': 200, 'time': 10, 'powRandomToken': 1000, 'encryptType': 4, 'expire': 14} #TODO properly refine values to minimum needed self.blockMetadataLengths = {'meta': 1000, 'sig': 200, 'signer': 200, 'time': 10, 'pow': 1000, 'encryptType': 4, 'expire': 14} #TODO properly refine values to minimum needed
self.default_expire = 2592000 self.default_expire = 2592000

View File

@ -247,7 +247,7 @@ class POW:
startNonce = nonce startNonce = nonce
while self.hashing: while self.hashing:
#token = nacl.hash.blake2b(rand + self.data).decode() #token = nacl.hash.blake2b(rand + self.data).decode()
self.metadata['powRandomToken'] = nonce self.metadata['pow'] = nonce
payload = json.dumps(self.metadata).encode() + b'\n' + self.data payload = json.dumps(self.metadata).encode() + b'\n' + self.data
token = myCore._crypto.sha3Hash(payload) token = myCore._crypto.sha3Hash(payload)
try: try:

View File

@ -75,7 +75,7 @@ class SubprocessPOW:
difficulty = self.difficulty difficulty = self.difficulty
mcore = core.Core() mcore = core.Core()
while True: while True:
metadata['powRandomToken'] = nonce metadata['pow'] = nonce
payload = json.dumps(metadata).encode() + b'\n' + data payload = json.dumps(metadata).encode() + b'\n' + data
token = mcore._crypto.sha3Hash(payload) token = mcore._crypto.sha3Hash(payload)
try: try: