attestation Class

namespace keychain → class attestation

Overview

The attestation class represents a digital signature with rich metadata, providing verifiable proof of authenticity and integrity for data. Attestations support multiple signatures on the same data and include comprehensive signature details.

Class Hierarchy

namespace keychain {
    class attestation : public serializable {
        // Digital signature with metadata
    };
}

Constructor

Default Constructor

attestation();

Creates an empty attestation.

Copy Constructor

attestation(const attestation& other);

Creates a copy of an existing attestation.

Properties

Signature Data

std::string get_signature() const;
void set_signature(const std::string& signature_hex);

Gets or sets the cryptographic signature in hexadecimal format.

Signer Information

std::string get_signer_did() const;
void set_signer_did(const std::string& did);

std::string get_signer_name() const;
void set_signer_name(const std::string& name);

std::string get_signer_public_key() const;
void set_signer_public_key(const std::string& public_key_hex);

Information about the entity that created the signature.

Algorithm Details

signature_scheme get_signature_scheme() const;
void set_signature_scheme(signature_scheme scheme);

std::string get_algorithm_identifier() const;

Cryptographic algorithm information used for the signature.

Timestamp Information

std::chrono::system_clock::time_point get_timestamp() const;
void set_timestamp(const std::chrono::system_clock::time_point& time);

std::string get_timestamp_iso8601() const;

When the signature was created.

Metadata

tag_set get_metadata() const;
void set_metadata(const tag_set& metadata);

void add_metadata(const std::string& key, const std::string& value);
std::string get_metadata_value(const std::string& key) const;

Additional key-value metadata associated with the signature.

Methods

Verification

bool verify(const std::string& original_data) const;
bool verify(const serialized_data& data) const;

Verifies the signature against the original data.

Parameters: * original_data - The original data that was signed * data - Serialized data that was signed

Returns: true if signature is valid, false otherwise

Signature Operations

std::string get_signed_data_hash() const;
bool matches_data(const std::string& data) const;
bool matches_data(const serialized_data& data) const;

Gets the hash of the signed data and checks if data matches what was signed.

Serialization

std::string to_json() const;
std::string to_xml() const;
std::vector<uint8_t> to_protobuf() const;

static attestation from_json(const std::string& json);
static attestation from_xml(const std::string& xml);
static attestation from_protobuf(const std::vector<uint8_t>& data);

Serializes attestation to various formats and deserializes from them.

Usage Examples

Creating an Attestation

#include <keychain/keychain.h>

// Create signed data with attestation
keychain::gateway gateway(settings);
keychain::persona signer = gateway.get_persona("alice", "personal");

std::string document = "Important contract terms...";
keychain::verifiable_data signed_doc = gateway.sign(signer, document);

// Extract attestation information
auto attestations = signed_doc.get_attestations();
for (const auto& attestation : attestations) {
    std::cout << "Signer: " << attestation.get_signer_name() << std::endl;
    std::cout << "DID: " << attestation.get_signer_did() << std::endl;
    std::cout << "Timestamp: " << attestation.get_timestamp_iso8601() << std::endl;
    std::cout << "Algorithm: " << attestation.get_algorithm_identifier() << std::endl;
}

Verification Workflow

// Verify attestation independently
bool verify_attestation(const keychain::attestation& att, const std::string& data) {
    // Check timestamp validity
    auto now = std::chrono::system_clock::now();
    auto signature_time = att.get_timestamp();
    auto age = std::chrono::duration_cast<std::chrono::hours>(now - signature_time);

    if (age > std::chrono::hours(24 * 365)) {  // 1 year old
        std::cout << "Warning: Signature is over 1 year old" << std::endl;
    }

    // Verify cryptographic signature
    if (!att.verify(data)) {
        std::cout << "Cryptographic verification failed" << std::endl;
        return false;
    }

    // Check algorithm strength
    auto scheme = att.get_signature_scheme();
    if (scheme == keychain::signature_scheme::RSA_2048_PKCS1_SHA256) {
        std::cout << "Warning: RSA-2048 may be weak for long-term use" << std::endl;
    }

    return true;
}

Multiple Attestations

// Add multiple signatures to data
keychain::verifiable_data document = gateway.sign(alice, "Contract v1.0");

// Add additional attestations
keychain::persona bob = gateway.get_persona("bob", "legal");
keychain::persona carol = gateway.get_persona("carol", "finance");

document.add_attestation(gateway.create_attestation(bob, document.get_content()));
document.add_attestation(gateway.create_attestation(carol, document.get_content()));

// Verify all attestations
auto attestations = document.get_attestations();
bool all_valid = std::all_of(attestations.begin(), attestations.end(),
    [&](const keychain::attestation& att) {
        return att.verify(document.get_content());
    });

std::cout << "All signatures valid: " << (all_valid ? "Yes" : "No") << std::endl;
std::cout << "Total attestations: " << attestations.size() << std::endl;

Metadata Usage

// Create attestation with metadata
keychain::attestation att;
att.set_signature(signature_hex);
att.set_signer_did(signer.get_did().to_string());
att.set_timestamp(std::chrono::system_clock::now());

// Add custom metadata
att.add_metadata("purpose", "contract_signature");
att.add_metadata("version", "1.0");
att.add_metadata("location", "New York");
att.add_metadata("witness", "john.doe@company.com");

// Query metadata
std::string purpose = att.get_metadata_value("purpose");
if (purpose == "contract_signature") {
    // Handle contract-specific logic
}

// Serialize with metadata
std::string json_with_metadata = att.to_json();

Attestation Structure

{
  "signature": "3045022100...",
  "signer": {
    "did": "did:keychain:alice.personal",
    "name": "alice.personal",
    "public_key": "04a1b2c3..."
  },
  "algorithm": {
    "scheme": "ECDSA_P256_SHA256",
    "identifier": "ecdsa-p256-sha256"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "metadata": {
    "purpose": "contract_signature",
    "version": "1.0",
    "location": "New York"
  }
}

Security Considerations

Timestamp Security

Timestamps are not cryptographically protected
Use trusted time sources when creating attestations
Consider time-stamping authorities for high-assurance applications

Algorithm Selection

Choose strong signature algorithms
Consider long-term security requirements
Plan for algorithm migration

Metadata Privacy

Metadata is included in serialized form
Sensitive information should be encrypted separately
Consider privacy implications of metadata

verifiable_data - Data containers with attestations
credential - W3C credentials with attestations
transaction - Consensus transactions with attestations
tag_set - Metadata storage