Skip to content

protocol.md

Latest commit

 

History

History
61 lines (35 loc) · 5.28 KB

protocol.md

File metadata and controls

61 lines (35 loc) · 5.28 KB

Encrypted Message Protocol 1.0

Introduction

Encrypted Message Protocol is a protocol that describes abstract structure of encrypted message that can be securely transfered between multiple compatible Software parts.

It is not aimed to provide complete and strict requirements for Software rather than to provide a set of flexible yet precise agreements. The purpose of the protocol is to simplify the development of compatible software using encrypted messages to exchange data.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Message packing and data layout

Software implementing Encrypted Message Protocol (EMP) MUST produce well packed message that can be transfered to any compatible third-party software using any accessible transport or technology. This Software MUST document message packing method to ensure interoperability between any other EMP compatible Software.

Message produced by EMP compatible Software MUST cosist of clearly separated blocks of data. This Software MUST document blocks separation method to ensure interoperability between any other EMP compatible Software.

It is RECOMMENDED to store finalized message in JSON because of proper blocks separation and wide format adoption. Finalized JSON EMP message MAY be encoded using RFC 4648 "base64url" to ensure pass-by-URL safety.

Required data blocks

Message produced by EMP compatible Software MUST contain at least two REQUIRED blocks of data: encryption algorithm alias block (ALG block) and encrypted message block (MSG block). Any other blocks or payload in message are OPTIONAL and can be added based on spesific needs or implementation.

ALG block MUST contain short unique alias of algorithm used by Software to encrypt message. ALG block MUST comprise only ASCII alphanumerics, period and hyphen [0-9A-Za-z-.]. It is RECOMMENDED to use official abbreviation of ecryption algorithm with OPTIONAL signing hash and its bits length number. Meaning of every ALG block aliases MUST be documented to ensure overall EMP implementing Software interoperability. Examples:

  • RSA-SHA256 - for RSA based asymmetric encryption with SHA256 signature
  • ECDSA-SHA512 - for ECDSA based asymmetric encryption with SHA256 signature
  • AES192 - for AES based symmetric ecryption using 24 bytes key without signature

MSG block MUST contain properly encrypted message text. Message encryption algorithm MUST match ALG block alias and ALG block documentation to ensure successfull message text decryption by receiving side.

Optional data blocks

It is RECOMMENDED to add signature block (SIG block) within message, containing cryptographic signature, allowing additional message verification. SIG block MUST contain valid cryptographic signature. Message singing algorithm MUST match ALG block alias and documentation to ensure successfull message verification by receiving side.

Reserved message block key names

If message packing method uses key-value notation to separate data blocks then these keys MUST be called alg and msg for ALG and MSG blocks respectively. If SIG block presented in key-value notated message than this block key MUST be called sig. Key names alg, msg and sig are reserved by protocol and MUST be used only to store data blocks as described in previous section.

Documentation

Every protocol implementation SHOULD be followed by implementation documentation. It is RECOMMENDED to store documentation alongside with implementation source code in file named IMPLEMENTATION.

Summary

  • Use any encoding/packing format you want, but try to use widely adopted, such as JSON, Protobuf, etc.
  • Use any data layout you want, as long as you distinguish data blocks.
  • Always specify message block algorithm in designated data block.
  • It is recommended to add signature data block into your message to increase safety.
  • Always provide documentation of data layout, supported cryptographic algorithms with their aliases, additional payload and message packing method.
  • If you use key-value data layout try to use reserved keys for respected values to lower adoption complexity and increase interoperability.

Authors and attributions

The Encrypted Message Protocol is authored by Georgiy Zuykov. It has been inspired by Alexander Baranov's idea of Encrypted Timeline and partially based on JSON Web Token standard by 0Auth. This protocol text is partially based on Semantic Version 2.0.0 specification text by Tom Preston-Werner.

You can open an issue on GitHub if you would like to leave feedback.

License

Encrypted Message Protocol specification text distributed under Apache 2.0 license.