Technical Specifications

Complete technical details for implementing DSPIP shipping protocol: SHIP payload format, privacy modes, cryptographic operations, DNS key distribution, and delivery confirmation.

Cryptographic Specifications

DSPIP uses multiple cryptographic algorithms depending on the privacy mode: secp256k1 for standard signatures, Ed25519 for split-key labels, and ECIES for recipient encryption.

Standard Signatures (secp256k1)

Parameter Value
Curve secp256k1 (SEC 2)
Signature Algorithm ECDSA + SHA-256
Private Key Size 256 bits (32 bytes)
Public Key Size 264 bits (33 bytes compressed)
Signature Encoding DER format, hex-encoded
Use Case Standard and encrypted privacy modes

Split-Key Signatures (Ed25519)

Parameter Value
Curve Curve25519 (Edwards form)
Signature Algorithm Ed25519
Private Key Size 256 bits (32 bytes)
Public Key Size 256 bits (32 bytes)
Signature Size 512 bits (64 bytes)
Use Case Physical anti-cloning labels with scratch-off zones

Recipient Encryption (ECIES)

Parameter Value
Key Agreement ECIES (secp256k1)
Symmetric Cipher AES-256-GCM
Key Derivation HKDF-SHA256
Nonce Size 96 bits (12 bytes)
Auth Tag Size 128 bits (16 bytes)
Use Case Encrypted recipient for last mile provider

Payload Structure

The payload contains shipping information encoded as JSON with type "SHIP". Required fields: type, issuer, itemId, timestamp.

{ "type": "SHIP", // REQUIRED: Fixed for shipping "issuer": { // REQUIRED: Sender information "name": "string", // Optional "organization": "string", // Optional "facility": "string", // Optional: Warehouse ID "address": { "city": "string", // Optional "state": "string", // Optional "country": "string" // ISO 3166-1 alpha-2 } }, "subject": { // Recipient or LMP "name": "string", // Standard mode only "address": { ... }, // Standard mode only "lastMileProvider": "string" // Encrypted/split-key mode }, "itemId": "string", // REQUIRED: Unique tracking ID "timestamp": number, // REQUIRED: Unix timestamp (ms) "typeData": { // SHIP-specific fields "privacyMode": "standard|encrypted|split-key", "parcelId": "string", // Optional: Legacy ID "carrier": "string", // Optional: Carrier name "service": "string", // Optional: Service level "lastMileProvider": "string", // LMP key locator "encryptedRecipient": "base64", // Encrypted mode "labelSerial": "string", // Split-key mode "gs1": "string", // Optional: GS1 identifier "ediRef": "string" // Optional: EDI reference } }

For encrypted and split-key modes, the subject contains only the last mile provider reference. The actual recipient is encrypted in typeData.encryptedRecipient.

QR Data Serialization

QR data MUST be serialized using pipe (|) delimiters. The pipe delimiter was chosen for its low frequency in Base64 and domain names.

DSPIP|<version>|<type>|<keyLocator>|<encodedPayload>|<signature>[|<privateMessage>]

Implementations MUST validate that exactly 6 or 7 pipe-delimited fields are present.

Field Description
protocol Fixed string "DSPIP"
version Semantic version (e.g., "1.0")
type Fixed to "SHIP" for shipping applications
keyLocator DNS path for public key lookup (or label serial for split-key)
encodedPayload Base64-encoded JSON payload
signature Hex-encoded signature (ECDSA for standard, Ed25519 for split-key)
privateMessage Optional: Base64-encoded ECIES-encrypted recipient data

QR Code Requirements

Error Correction Level M (15% recovery) recommended
Version 40 or automatic selection
Encoding Mode Binary for optimal density
Max Capacity (Level M) 2,331 bytes

DNS Key Distribution

DSPIP uses DNS TXT records for public key distribution, following the model established by DKIM. Key locators MUST follow this pattern:

<selector>._dspip.<domain>

Examples:

warehouse._dspip.example.com // Shipping warehouse lmp._dspip.carrier.com // Last mile provider omaha-main._dspip.usps.gov // Post office

DNS TXT Record Format

The DNS TXT record MUST contain a semicolon-separated list of tag=value pairs:

v=DSPIP1; k=ec; c=secp256k1; p=<base64_public_key>; types=SHIP; [optional tags]

Required Tags

v
Protocol version (MUST be "DSPIP1")Required
k
Key type: "ec" (secp256k1) or "ed" (Ed25519)Required
c
Curve: "secp256k1" or "ed25519"Required
p
Public key in Base64 encodingRequired
types
Supported types (e.g., "SHIP")Required

Key Lifecycle Tags (SHOULD include)

t
Key creation timestamp (Unix time). If omitted, key is valid from indefinite past.Recommended
exp
Signing expiration timestamp (Unix time). After this time, key MUST NOT sign new items.Recommended
exp-v
Verification expiration timestamp (Unix time). After this time, key MUST NOT verify any signatures. Defaults to exp value if omitted.Recommended

Optional Tags

s
Key status: "active" (default), "verify-only", or "revoked"Optional
seq
Sequence number for key updates. Higher values supersede lower for same selector.Optional
rsig
Record signature - cryptographic authentication of lifecycle metadata (t, exp, exp-v, s, seq). Protects against DNS cache manipulation.Optional
auth
Authorization level: "shipper", "lmp", "government"Optional
coverage
Geographic coverage for LMPs (postal codes, regions)Optional
address
Physical facility location. Schemes: plus: (Plus Code), street: (percent-encoded), geo: (lat,lng), facility: (reference ID)Optional
n
Human-readable notes (percent-encoded)Optional
eth
Ethereum address for blockchain integrationOptional

Shipper Key Example (with lifecycle fields)

warehouse._dspip.example.com. IN TXT "v=DSPIP1; k=ec; c=secp256k1; p=AzmjYBMwFZfa70H75ZOgLMUT0LVVJ+wt8QUOLo/0nIXC; types=SHIP; t=1703548800; exp=1735084800; exp-v=1766620800; s=active; seq=1; n=Main%20Warehouse%20Key%202025"

Last Mile Provider Key Example

omaha-main._dspip.usps.gov. IN TXT "v=DSPIP1; k=ec; c=secp256k1; p=AzmjYBMwFZfa70H75ZOgLMUT0LVVJ+wt8QUOLo/0nIXC; types=SHIP; auth=government; address=86HJW222+22; coverage=68101,68102,68103,68104,68105"

Key Lifecycle States

Keys transition through the following states:

State Condition Can Sign Can Verify
Active s=active (or omitted), current time < exp Yes Yes
Verify-Only s=verify-only, or exp < current time < exp-v No Yes
Expired s=revoked, or current time > exp-v No No

Recommended key lifetime: Active signing: 365 days. Verify-only period: 365 additional days. Total: 730 days (2 years).

Signature Operations

Standard/Encrypted Mode (ECDSA)

For standard and encrypted privacy modes:

  1. Construct signable content: protocol|version|type|keyLocator|encodedPayload
  2. Calculate SHA-256 hash of signable content
  3. Sign hash using ECDSA with secp256k1 private key
  4. Encode signature in DER format, hex-encoded

Split-Key Mode (Ed25519)

For physical anti-cloning labels:

  1. Sender reveals Zone A (scratch-off) to obtain Ed25519 private key
  2. Construct signable content: protocol|version|type|labelSerial|encodedPayload
  3. Sign using Ed25519 with revealed private key
  4. Hex-encode 64-byte signature
  5. Destroy private key after signing (one-time use)

Verification (Standard/Encrypted)

  1. Reconstruct signable content from QR data
  2. Query DNS TXT record at keyLocator
  3. Verify ECDSA signature with public key
  4. Check key lifecycle: verify s status and exp-v expiration
  5. Verify rsig if present (protects against DNS cache manipulation)
  6. Query key revocation list at _revoked-key._dspip.<domain>
  7. Query item revocation list for itemId

Verification (Split-Key)

  1. Recipient reveals Zone B (scratch-off) to obtain Ed25519 public key
  2. Reconstruct signable content from QR data
  3. Verify Ed25519 signature with revealed public key
  4. Verify Zone B scratch-off was previously intact (visual inspection)
  5. Cloned QRs will fail: no matching physical public key

Note: Split-key verification is offline - no DNS lookup required. This enables verification in areas without network connectivity.

Privacy Modes

DSPIP defines three privacy modes for different security and privacy requirements:

Mode
Standard
Traditional shipping with full transparency
  • Full recipient info in payload
  • ECDSA signature (secp256k1)
  • DNS key lookup
  • Business-to-business shipments
  • Internal transfers
Mode
Encrypted
Privacy-preserving consumer delivery
  • Recipient encrypted with ECIES
  • LMP reference in subject
  • ECDSA signature (secp256k1)
  • DNS key lookup
  • Consumer privacy protection
Mode
Split-Key
Maximum security with anti-cloning
  • Ed25519 signature from Zone A
  • Physical label with scratch-offs
  • Offline verification (no DNS)
  • One-time-use private key
  • High-value shipments
MUST
SHOULD
MAY

Key Revocation

When a signing key is compromised or must be retired, organizations publish key revocation records at a dedicated DNS endpoint. This operates independently of key record caching for faster propagation.

Key Revocation Record Format

_revoked-key._dspip.example.com. IN TXT "v=DSPIP1; type=key-revocation; selector=warehouse; revoked=1703548900; reason=compromised; replacement=warehouse-v2"

Revocation Reasons

compromised
Private key was exposed or stolen
retired
Key reached end of lifecycle
superseded
Key replaced by newer key
suspended
Temporarily disabled (may be reactivated)

Important: Key revocation takes precedence over s=active in the key record. Verifiers SHOULD use short TTLs (60-300 seconds) when caching key revocation records.

Item Revocation Lists

Senders can revoke shipping labels for lost, stolen, damaged, or recalled packages. Revocation lists auto-prune entries older than 180 days for SHIP type.

Revocation List Format

{ "version": "1.0", "issuer": "warehouse._dspip.example.com", "updated": 1703548800, "expires": 1719316800, // 180 days "revoked": [ { "itemId": "TRACK-2025-000123", "revoked": 1703548900, "reason": "lost|stolen|damaged|recalled", "replacementId": "TRACK-2025-000124" // Optional } ], "signature": "issuer_signature" }

DNS Revocation Pointer

revocation._dspip.example.com. IN TXT "v=DSPIP1; type=revocation; url=https://example.com/dspip/revoked.json; updated=1703548800; ttl=86400"

Delivery Confirmation

Cryptographic proof of delivery using challenge-response protocol. Provides non-repudiable evidence of successful delivery.

Confirmation Protocol

  1. Carrier generates time-bounded challenge at delivery
  2. Recipient signs challenge with their delivery key
  3. Carrier verifies signature and records confirmation
  4. Optional: Record confirmation hash to blockchain

Confirmation Format

{ "itemId": "TRACK-2025-000123", "deliveryTimestamp": 1703635200000, "status": "delivered", "carrierKeyLocator": "lmp._dspip.carrier.com", "recipientSignature": "base64_signature", // Optional "location": { "lat": 41.2565, "lng": -95.9345 }, "carrierSignature": "base64_signature" }

Performance Guidelines

Expected operation times for typical implementations:

Operation Expected Time
Key generation (secp256k1) 5-10 ms
Key generation (Ed25519) 2-5 ms
Signature creation 2-5 ms
DNS lookup 20-100 ms (cacheable)
Signature verification 3-8 ms
ECIES encryption 5-15 ms
ECIES decryption 5-15 ms
Revocation list check 10-50 ms (cacheable)
Blockchain recording 2-5 seconds (optional, async)

© 2025 Midwest Cyber LLC • dspip.io • dspip.dev