Skip to content

Latest commit

 

History

History
163 lines (134 loc) · 4.56 KB

spec_38.rst

File metadata and controls

163 lines (134 loc) · 4.56 KB
GitHub is NOT the preferred viewer for this file. Please visit
https://flux-framework.rtfd.io/projects/flux-rfc/en/latest/spec_38.html

38/Flux Security Key Value Encoding

The Flux Security Key Value Encoding is a serialization format for a series of typed key-value pairs.

Name github.com/flux-framework/rfc/spec_38.rst
Editor Jim Garlick <garlick@llnl.gov>
State raw

Language

Related Standards

Background

The flux-security project requires simple objects to be encoded for communication in the following security-sensitive situations:

  • To encode the header component of J (signed jobspec plus metadata).
  • When communicating options between privileged and unprivileged sections of the IMP.

Goals

  • Replace JSON for security-sensitive use cases where auditability of source code is important.
  • Must handle strings and a few scalar types.
  • There should be no implicit type conversions. For example, a value encoded as an integer may not be decoded as floating point.
  • Design should allow for a simple, embedded C implementation.

Implementation

A single key-value pair SHALL be encoded as the UTF-8 key name, a zero byte delimiter, a type character, a UTF-8 value string, and zero byte delimiter.

Each key SHALL have a length greater than zero.

Keys and string values MAY NOT contain the UTF-8 NUL character.

Note

A zero byte MAY NOT be embedded in any key or value encoding because it would be indistinguishable from a field delimiter. The only UTF-8 encoding that contains a zero byte is that of the NUL character, therefore the NUL character is forbidden.

Value type characters and associated value string encodings are as follows:

s
String. The value SHALL be directly represented.
i
64-bit signed integer. The value SHALL be formatted by printf(3) using the PRIi64 format token.
d
Double-precision floating point number. The value SHALL be formatted by printf(3) using the .6f format token.
b
Boolean. The value SHALL be either the string "true" or the string "false" (lower case).
t
Timestamp. The value SHALL be represented as an ISO 8601 timestamp string.

Multiple key-value pairs SHALL be concatenated without additional delimiters, e.g. key\0Tvalue\0key\0Tvalue\0...key\0Tvalue\0.

An implementation defined limit SHALL be imposed on the maximum overall size of a serialized object to avoid resource exhaustion.

Test Vectors

name type value encoding
PATH string /bin:/usr/bin PATH\0s/bin:/usr/bin\0
EMPTY_STRING string   EMPTY_STRING\0s\0
JOB_ID_STRING string ƒuzzybunny JOB_ID_STRING\0sƒuzzybunny\0
INT_PLUS integer 42 INT_PLUS\0i42\0
INT_MINUS integer -42 INT_MINUS\0i-42\0
INT64_MAX integer 9223372036854775807 INT64_MAX\0i9223372036854775807\0
INT64_MIN integer -9223372036854775808 INT64_MIN\0i-9223372036854775808\0
DOUBLE double 3.0 DOUBLE\0d3.000000\0
DOUBLE_INF double INFINITY DOUBLE_INF\0dinf\0
DBL_MIN double 2.2250738585072014e-308 DBL_MIN\0d0.000000\0
DBL_MAX double 1.7976931348623158e+308 DBL_MAX\0d179769313486231570814527423731704356798070567525844996598917476803157260780028538760589558632766878171540458953514382464234321326889464182768467546703537516986049910576551282076245490090389328944075868508455133942304583236903222948165808559332123348274797826204144723168738177180919299881250404026184124858368.000000\0
MINUS_DBL_MAX double -1.7976931348623158e+308 MINUS_DBL_MAX\0d-179769313486231570814527423731704356798070567525844996598917476803157260780028538760589558632766878171540458953514382464234321326889464182768467546703537516986049910576551282076245490090389328944075868508455133942304583236903222948165808559332123348274797826204144723168738177180919299881250404026184124858368.000000\0
FALSE boolean false FALSE\0bfalse\0
TRUE boolean true TRUE\0btrue\0
TIMESTAMP timestamp 1692370785 (time_t) TIMESTAMP\0t2023-08-18T14:59:45Z\0