Beacon Value

The NistBeaconValue objects act as basic python objects. As one would expect, there are a number of properties and methods available on it.

Instance Details

"""
:param version:
    Reported NIST randomness beacon version

:param frequency:
    The time interval, in seconds, between expected records

:param timestamp:
    The time the seed value was generated as the number of
    seconds since January 1, 1970

:param seed_value:
    A seed value represented as a 64 byte (512-bit) hex string
    value

:param previous_output_value:
    The SHA-512 hash value for the previous record - 64 byte hex
    string

:param signature_value:
    A digital signature (RSA) computed over (in order): version,
    frequency, timeStamp, seedValue, previousHashValue, statusCode

    Note: Except for version, the hash is on the byte
    representations and not the string representations of the data
    values

:param output_value:
    The SHA-512 hash of the signatureValue as a 64 byte hex string

:param status_code:
    The status code value:
        0 - Chain intact, values all good
        1 - Start of a new chain of values, previous hash value
            will be all zeroes
        2 - Time between values is greater than the frequency, but
            the chain is still intact
"""

Properties

frequency

@property
def frequency(self) -> int:
    """
    :return: The time interval, in seconds, between expected records
    """

json

@property
def json(self) -> str:
    """
    :return: The JSON representation of the beacon, as a string
    """

output_value

@property
def output_value(self) -> str:
    """
    :return: The SHA-512 hash of the signatureValue as a 64 byte hex string
    """

previous_output_value

@property
def previous_output_value(self) -> str:
    """
    :return:
        The SHA-512 hash value for the previous record - 64 byte hex
        string
    """

pseudo_random

@property
def pseudo_random(self) -> Random:
    """
    :return:
        A python `random.Random` object that has been seeded with
        the value's `output_value`. This is a pseudo-random
        number generator
    """

seed_value

@property
def seed_value(self) -> str:
    """
    :return:
        A seed value represented as a 64 byte (512-bit) hex string
        value
    """

signature_value

@property
def signature_value(self) -> str:
    """
    :return:
        A digital signature (RSA) computed over (in order): version,
        frequency, timeStamp, seedValue, previousHashValue, statusCode

        Note: Except for version, the hash is on the byte
        representations and not the string representations of the data
        values
    """

status_code

@property
def status_code(self) -> str:
    """
    :return:
        The status code value:
            0 - Chain intact, values all good
            1 - Start of a new chain of values, previous hash value
                will be all zeroes
            2 - Time between values is greater than the frequency, but
                the chain is still intact
    """

timestamp

@property
def timestamp(self) -> int:
    """
    :return:
        The time the seed value was generated as the number of
        seconds since January 1, 1970
    """

valid_signature

@property
def valid_signature(self) -> bool:
    """
    Shows the result of signature verification

    First, required records (version, frequency, timestamp,
    seed_value, previous_output_value) are packed together to form
    a message. This message is then checked against the record's reported
    signature field WITH the known NIST public key.

    Second, the signature value is independently ran through a SHA512
    hash. The result of this operation SHOULD equal the record's reported
    output_value field.

    As long as the result of the 'First' step and'ed with the 'Second'
    step, the record is considered valid.

    :return: 'True' if this record is valid. 'False' otherwise
    """

version

@property
def version(self) -> str:
    """
    :return: Reported NIST randomness beacon version
    """

xml

@property
def xml(self) -> str:
    """
    :return: The XML representation of the beacon, as a string
    """

Methods

from_json

@classmethod
def from_json(cls, input_json: str):
    """
    Convert a string of JSON which represents a NIST randomness beacon
    value into a 'NistBeaconValue' object.

    :param input_json: JSON to build a 'Nist RandomnessBeaconValue' from
    :return: A 'NistBeaconValue' object, 'None' otherwise
    """

from_xml

@classmethod
def from_xml(cls, input_xml: str):
    """
    Convert a string of XML which represents a NIST Randomness Beacon value
    into a 'NistBeaconValue' object.

    :param input_xml: XML to build a 'NistBeaconValue' from
    :return: A 'NistBeaconValue' object, 'None' otherwise