Document Status

This is a initial draft of the SSF32™ 1.0 specification.

While this draft has been released, it has not been approved by any standards body.

Implementors should periodically check the SSF32 online resources (see #Online Resources tab) for the current status of SSF32 documentation.

Abstract

The Secure Signature Format 32 Byte (SSF32) specification provides an extensible, tamper & corruption resistant file format for cryptographically secure signatures for files and strings.

The SSF32 specification is inspired by the patent-free PNG specification and is designed to provide a poratble, legally unencumbered, highly-secure, well-specified standard for encoding and decoding formatted pairs of cryptographically secure hashes & digital signatures.

The initial motivation for the SSF32 standard was to have a convenient, extensible, compact & cryptographically secure method for storing hashes and signatures for secure verification of files or strings transmitted across internet protocols or stored on blockchains.

All applications which encode or decode SSF32 files in compliance with this specification should utilize the industry standard OpenSSL Protocol or another secure & tested cryptographic protocol.

The SSF32 file format is a patent-free format licensed under the Apache 2.0 License.

This specification defines the Internet Media Type "application/ssf32".

Please review either the #License tab or the repository LICENSE.md for more information.

SSF32 features retained from the PNG Standard include:

  • Complete hardware and platform independence.
  • Reliable, straightforward detection of file corruption.

SSF32 is designed to be:

  • Simple & portable.
  • Secure: Reasonably cryptographically resistant to tampering or data corruption.
  • Flexible: Allows for future extensions without compromising the fundementals of the specification.
  • Robust: Designed to support full file integrity, including: simple, quick detection of common transmission errors, while also supporting highly optimized, industry standard cryptographic validation algorithms.

The primary purpose of this specification is to provide the definition of the Secure Signature Format and recommendations for the minimum required behaviour for encoders and decoders.

The #Appendix tab provides additional documentation, including rational for all design decisions.

While the #Appendix tab and its content are not part of the formal specification, it helps implementors to understand the design and intent behind this document. Its other purpose is to provide cross-references to relevant sections of rationale, examples or other supporting material.

Terms

The key words in this document:

  • "MUST"
  • "MUST NOT"
  • "REQUIRED"
  • "SHALL"
  • "SHALL NOT"
  • "SHOULD"
  • "SHOULD NOT"
  • "RECOMMENDED"
  • "MAY"
  • and "OPTIONAL"

are to be interpreted as described in RFC-2119.

Pronunciation

Phonetically, SSF is pronounced: "ɛs-ɛs-ɛf".

Packed Specification

A tightly packed SSF32 compliant file consists of a standard 8-byte SSF header followed by:

  1. The Content Integrity Hash of the remainder of the file's content.
  2. A Format Layout Type Hash of the string representing the domain, format data types and their layout in the file which includes:
    1. A 4 Byte (32 bit) file length indicator.
    2. Hash of the raw data file or string.
    3. optional:
      1. Hash of the signing Public Key
      2. Sequence of zero or more 8-bit bytes.
  3. The Byte Length Specifier, a 4 byte (32 bit) unsigned integer specifying the number of (8-bit) bytes expected to follow in the file.
  4. 256 bit (32 Byte) Source Hash of the raw data file or string which was signed.
  5. optional:
    1. 256 bit (32 Byte) Public Key Hash of the public key used to sign the data source.
    2. Arbitrary sequence of bytes of the Source Signature, the cryptograhically secure signature of the source data signed by the Author/Publisher/Copyright holder.

File Header

The first 8 bytes of an SSF file are always the following (hexadecimal) values: 0x23 0x53 0x53 0x46 0x0d 0x0a 0x1a 0x0a

The signature indicates that the remainder of the file consists of a SSF32 signature as specified by this standard.

See rationale: SSF File Signature.

Content Layout

Immediately following the 8 byte file header is a format specific hash, which is the hash of the remaining file content, which is used for verification of the integrity of the file contents.

Following the Content Integrity Hash is a unique, parser specific Type Hash specifying the following layout of the expected data and their types.

  1. 32-bit (4 byte) uint specifying the total bytes to expect in the remainder of the file.
  2. 32 bytes Hash of the data being signed.
  3. optional:
    1. 32 byte Public Key Hash.
    2. Arbitrary bytes of Author/Publisher/Copyright Holder Signature of the signed source file.

This Type Hash is a unique identifier for SSF32 data, used to easily identify, encode and decode binary data in the expected format as specified by this standard, which differentiates an arbitrary, unstructured binary payload from an SSF32 compliant file, string or data stream.

See rationale: SSF32 Type Hash.

Packed File Layout

By default, SSF32 should be

The binary layout for an SSF32 file is as follows: 

\x23\x53\x53\x46\x0d\x0a\x1a\x0a\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00...)?

The byte length of an SSF32 compliant file (excluding trailing signature) must be no less than: 

8 + (32 + 32 + 4) + (32) = 108 Bytes

With signature included, the minimum byte length of a SSF32 compliant file (excluding trailing signature) must be greater than: 

8 + (32 + 32 + 4) + (32 + 32) = 140 Bytes

See:

Packed Regular Expression

A PHP preg_* compatible regex repressenting a SSF32 compatible string which conforms to this specification, which captures all required groups may be implemented as follows:

'/^(\x23\x53\x53\x46\x0d\x0a\x1a\x0a)((.{32})(.{32})(.{4}))((.{32})((.{32})(.+))?)$/s'

See: The Official SSF32 PHP Implementation for a practical example.

Padded Specification

A padded SSF32 file is the same as the packed version, with the only difference being all data fields are aligned to 32 bytes (padded) and must be encoded in the same manner as to be comliant with standard Ethereum Virtual Machine (EVM) ABI encoding.

  1. Unisgned integers less than 32 bytes are left padded with '\x00' bytes.
  2. Bytes, String and Arrays are right padded with '\x00' bytes.
  3. Bytes, String and Array objects are encoded with the first element indicating the number of elements it contains.

A padded SSF32 compliant file consists of a standard 8-byte SSF header followed by:

  1. 24 Bytes of padding, which must be ignored.
  2. The Content Integrity Hash of the remainder of the file's content.
  3. A Format Layout Type Hash of the string representing the domain, format data types and their layout in the file which includes:
    1. A 4 Byte (32 bit) file length indicator.
    2. Hash of the raw data file or string.
      3. optional:
      1. Hash of the signing Public Key
      2. Encoded binary singature as a sequence of more than 32 bytes, if present.
  4. 28 Bytes of padding, which must be ignored.
  5. The Byte Length Specifier, a 4 byte (32 bit) unsigned integer specifying the number of (8-bit) bytes expected to follow in the file.
  6. 32 Byte Source Hash of the raw data file or string which was signed.
  7. optional:
    1. 256 bit (32 Byte) Public Key Hash of the public key used to sign the data source.
    2. Arbitrary sequence of bytes of the Source Signature, the cryptograhically secure signature of the source data signed by the Author/Publisher/Copyright holder.

File Header

The first 8 bytes of an SSF file are always the following (hexadecimal) values: 0x23 0x53 0x53 0x46 0x0d 0x0a 0x1a 0x0a

Followed by 24 bytes of '\x00' padding

The signature indicates that the remainder of the file consists of a SSF32 signature as specified by this standard.

See rationale: SSF Padded File Signature.

Content Layout

Immediately following the 32 byte file signature is a format specific hash, which is the hash of the remaining file content, which is used for verification of the integrity of the file contents.

Following the Content Integrity Hash is a unique, parser specific Type Hash specifying the following layout of the expected data and their types.

  1. 32-bit (4 byte) uint specifying the total bytes to expect in the remainder of the file (must be a multiple of 32 bytes).
  2. 32 byte Hash of the data being signed.
  3. optional:
    1. 32 byte Public Key Hash.
    2. Arbitrary bytes of Author/Publisher/Copyright Holder Signature of the signed source file (padded to 32 bytes).

This Type Hash is a unique identifier for SSF32 data, used to easily identify, encode and decode binary data in the expected format as specified by this standard, which differentiates an arbitrary, unstructured binary payload from an SSF32 compliant file, string or data stream.

See rationale: SSF32 padded Type Hash.

Padded File Layout

The binary layout for a 32 byte padded SSF32 file is as follows: 

\x23\x53\x53\x46\x0d\x0a\x1a\x0a\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
(
\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00
\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00...
)?

The byte length of a 32 byte padded SSF32 compliant file (excluding trailing signature) must be no less than: 

32 + (32 + 32 + 32) + (32) = 160 Bytes

With signature included, the minimum byte length of a SSF32 compliant file (excluding trailing signature) must be greater than: 

32 + (32 + 32 + 32) + (32 + 32) = 192 Bytes

See:

Padded Regular Expression

A PHP preg_* compatible regex repressenting a padded SSF32 compatible string which conforms to this specification, which captures all required groups may be implemented as follows:

'/^(\x23\x53\x53\x46\x0d\x0a\x1a\x0a).{24}((.{32})(.{32}).{28}(.{4}))((.{32})((.{32})(.+))?)$/s'

See: The Official SSF32 PHP Implementation for a practical example.

Deflate/Inflate Compression

SSF compression utilizes the deflate/inflate compression method.

Deflate compression is an LZ77 derivative used in zip, gzip, pkzip, and related programs. Extensive research has been done supporting its patent-free status. Portable C implementations are freely available across multiple platforms.

File Name Extension

On systems where file names customarily include an extension signifying file type, the extension ".ssf32" is recommended for SSF files.

Lowercase ".ssf32" is preferred if file names are case-sensitive.

In the event an SSF file extension lacks an integer suffix (eg. ".ssf"), it must be parsed as a 32 Byte SSF file as outlined in this specification.

Internet Media Type

For robustness, decoders may choose to support the interim media type: 

'application/x-ssf32'
Until an official MIME type registration is complete.

Terminating Signature

If present, the length of the final 'Signautre' field is an arbitrary, non-zero amount of byte which is dependant upon the signing algorithm and whether packed or padded format is used.

This specification allows for a maximum allowable byte size for the combined trailing hash and signature to be no more than 4 gB. Taking future proofing into consideration, for all practical purposes, the trailing hash and signature combined should not require more than 4 kB but may potentailly exceed 4 kB and is encoder specific.

This approach accomodates future signing algorithms requiring more bytes than modern algorithms while also being algorithm agnostic and implementation specific.

Security Considerations

All SSF32 files must be non-executable.

A decoder that fails to complete all checks specified in the #Decoders tab must consider the decoded data corrupt or otherwise invalid.

Encoder Recommendations

This section provides recommendations for SSF32 encoder behavior.

The only absolute requirement for an SSF32 encoder is that it However, best results will usually be achieved by following these recommendations.

Encoders must:

  • Produce files or strings that conform to this specification.
  • Support Packed mode and should support Padded mode, especially if compatibility with Ethereum Virtual Machine (or similar blockchain) is desired.

Encoders may:

  • Perform encryption, compression, base64 encoding or any combination of the three on its output.

Decoder Recommendations

This section provides recommendations for decoder behavior.

The only absolute requirement for an SSF32 decoder is that it successfully reads any file conforming to the format specified in this document. However, best results will usually be achieved by following these recommendations.

To ensure early detection of common file-transfer problems, decoders must verify that all initial eight (8) bytes (64 bits) of the SSF32 file signature are correct. (See Rationale: SSF32 file signature).

A decoder can have additional confidence in the file's integrity using the File Content Integrity Hash, File Layout Type Hash and Byte Length Specifier.

Decoders must:

  • Support Packed mode and should support Padded mode, especially if compatibility with Ethereum Virtual Machine (or similar blockchain) is desired.
  • Hash (using the alogrithm specific to the parser rendering the file) the parsed Type Hash, Byte Length Specifier, Source Content Hash, Source Signature then validate it against the parsed Content Integrity Hash.
  • Validate the file's parsed Type Hash matches the unique Type Hash of the specific parser implemenation rendering the file.
  • Verify the number of (8-bit) bytes read from the file following the 4 Byte Byte Length Specifier equals the parsed Byte Length Specifier. The Byte Length Specifier must be no less than the number of bytes corresponding to the specific parser rendering the file (typically either 32 or 64 Bytes).

Decoders may:

  • Perform decryption, decompression, base64 decoding or any combination of the three on its input. The result must conform to this standard.

In the event the parsed Byte Length Specifier of a file equals the number of bytes in its hashing algorithm (typically either 32 or 64 Bytes), there is no signature associated with the data and parse must end after the Source Content Hash has been parsed.

Glossary of Terms

Byte
Eight bits; also called an octet.
SSF32
An extensible, secure, non-executable binary format for structuring the hash and digital signature in a manner which is resistant to corruption, transferable over common internet protocols as a header, embeded within an HTML webpages, included as an email attachment or stored in a database server or blockchain.

Appendix

This section is not part of the formal PNG specification.

This section provides reasoning behind some of the design decisions which when into standardizing SSF32. Many of these decisions were the subject of considerable debate.

Why a new file format

Common cryptographic operations include generating then subsequently storing a hash and signature to prove the authorship or ownership of some text or file.

The SSF32 specification provides a convenient, patent-free manner in which to structure, encode and decode such data, which can then be directly embbeded within another file as metadata, transmitted across the internet or stored in a database on a blockchain, which may be used for validation.

Example Encoders

The official example SSF32 encoder for PHP can be found here.

Example Decoders

The official example SSF32 decoder for PHP can be found here.

Online Resources

The Official SSF32 PHP reference is available here.

Errata

Change Log:

References

Credits

License

This specification is being provided by the copyright holders under the following conditions: 

----------------------------------------------------------------

# Copyright © 11-04-2022 Tyler R. Drury (vigilance.eth™), All Rights Reserved.
    
----------------------------------------------------------------

## Disclaimer

This specification (the **Product**), including but not limited to,
all source code, object files, executables, library files,
images, video, audio, documentation, content generated by
the Product and any other resource file of the Product,
are subject to the following terms and conditions (the **License**).

----------------------------------------------------------------

## Retention of Intellectual Property Rights

The name, likeness or works (either in part or in whole)
of [Tyler R. Drury](https://vigilance91.github.io/) or that of any additional authors or contributors respectfully
may not be used to endorse or promote products derived from this specification without specific prior written permission.

----------------------------------------------------------------

## Use and Redistribution

Redistribution and use in source and binary forms,
with or without modification is permitted,
provided that the following conditions are met:

* Redistributions of source code must retain, in whole,
the above copyright notice, disclaimer, and this list of conditions.
* Redistributions in binary form must reproduce, in whole,
the above copyright notice, disclaimer
and this list of conditions in the documentation
and/or other materials provided with the distribution.
* Any documentation, advertising materials,
and other materials related to such distribution and use,
must acknowledge the original author of the **Product** and all contributors.


----------------------------------------------------------------

## Coverage

The **Product** is licensed under the Apache License, Version 2.0 (the **Apache License**),
and may not be used, except in compliance with the **Apache License**.

A full copy of the **Apache License** can be obtained [here](http://www.apache.org/licenses/LICENSE-2.0).

----------------------------------------------------------------

## Disclaimer of Warranty and Limitation of Liability

Unless required by applicable law or agreed to in writing,
software distributed under the **License** is distributed on an
**AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND**,
either express or implied.

Copyright holders and contributors are **not liable for damages** incurred through the use or inability to use the **Product**.

See the [Apache License](http://www.apache.org/licenses/LICENSE-2.0) for the specific language governing permissions and
limitations under the **Apache License**.

----------------------------------------------------------------