Cryptographic Operations

Sign messages and verify signatures using managed keys

Sign Message

Sign a message or digest using the specified key.

id · string · required

Key identifier

Request Body

algorithm · string · required

Signature algorithm to use:

• SHA256WithRSA - RSA with SHA-256
• SHA384WithRSA - RSA with SHA-384
• SHA512WithRSA - RSA with SHA-512
• SHA256WithECDSA - ECDSA with SHA-256
• SHA384WithECDSA - ECDSA with SHA-384
• SHA512WithECDSA - ECDSA with SHA-512
• Ed25519 - Ed25519 signature

message · string · required

Message to sign (base64 encoded)

message_type · string · required

Type of message:

• RAW - Raw message (will be hashed by the KMS)
• DIGEST - Pre-computed message digest

Response

signature · string

Base64 encoded signature

Example Request - Sign Raw Message

# Encode your message to base64
MESSAGE=$(echo -n "Hello, World!" | base64)

curl -X POST "https://api.lamassu.io/api/kms/v1/keys/key-123/sign" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "SHA256WithRSA",
    "message": "'"$MESSAGE"'",
    "message_type": "RAW"
  }'

Example Request - Sign Digest

# Compute SHA-256 digest and encode to base64
DIGEST=$(echo -n "Hello, World!" | openssl dgst -sha256 -binary | base64)

curl -X POST "https://api.lamassu.io/api/kms/v1/keys/key-123/sign" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "SHA256WithRSA",
    "message": "'"$DIGEST"'",
    "message_type": "DIGEST"
  }'

Example Response

{
  "signature": "c2lnbmF0dXJlIGRhdGEgaGVyZS4uLg=="
}

---

Verify Signature

Verify a signature against a message using the specified key.

id · string · required

Key identifier (must contain the public key)

Request Body

algorithm · string · required

Signature algorithm used (same values as Sign Message)

message · string · required

Original message (base64 encoded)

signature · string · required

Signature to verify (base64 encoded)

message_type · string · required

Type of message: RAW or DIGEST

Response

valid · boolean

Whether the signature is valid

error · string

Error message if validation failed (empty string if successful)

Example Request

MESSAGE=$(echo -n "Hello, World!" | base64)
SIGNATURE="c2lnbmF0dXJlIGRhdGEgaGVyZS4uLg=="

curl -X POST "https://api.lamassu.io/api/kms/v1/keys/key-123/verify" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "SHA256WithRSA",
    "message": "'"$MESSAGE"'",
    "signature": "'"$SIGNATURE"'",
    "message_type": "RAW"
  }'

Example Response - Valid Signature

{
  "valid": true,
  "error": ""
}

Example Response - Invalid Signature

{
  "valid": false,
  "error": "signature verification failed"
}

---

Signature Algorithms by Key Type

RSA Keys

Supported signature algorithms:

• SHA256WithRSA - Recommended for most use cases
• SHA384WithRSA - Higher security
• SHA512WithRSA - Maximum security

ECDSA Keys

Supported signature algorithms:

• SHA256WithECDSA - For P-256 keys
• SHA384WithECDSA - For P-384 keys
• SHA512WithECDSA - For P-521 keys

Ed25519 Keys

Supported signature algorithms:

• Ed25519 - Native Ed25519 signature (no separate hash algorithm needed)

---

Common Use Cases

Certificate Signing

# Step 1: Create or obtain a CSR
openssl req -new -key device.key -out device.csr

# Step 2: Extract the CSR data to be signed
CSR_DATA=$(openssl req -in device.csr -outform DER | base64 -w 0)

# Step 3: Sign the CSR with your CA key
curl -X POST "https://api.lamassu.io/api/kms/v1/keys/ca-key-123/sign" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "SHA256WithRSA",
    "message": "'"$CSR_DATA"'",
    "message_type": "RAW"
  }'

Firmware Signing

# Step 1: Compute SHA-256 digest of firmware
FIRMWARE_DIGEST=$(sha256sum firmware.bin | awk '{print $1}' | xxd -r -p | base64 -w 0)

# Step 2: Sign the digest
curl -X POST "https://api.lamassu.io/api/kms/v1/keys/firmware-signing-key/sign" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "SHA256WithECDSA",
    "message": "'"$FIRMWARE_DIGEST"'",
    "message_type": "DIGEST"
  }'

Document Signing

# Sign a document
DOCUMENT=$(cat document.pdf | base64 -w 0)

curl -X POST "https://api.lamassu.io/api/kms/v1/keys/document-signing-key/sign" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "SHA256WithRSA",
    "message": "'"$DOCUMENT"'",
    "message_type": "RAW"
  }'

Signature Verification

# Verify a signature received from a device or external system
MESSAGE=$(cat data.bin | base64 -w 0)
SIGNATURE=$(cat signature.bin | base64 -w 0)

curl -X POST "https://api.lamassu.io/api/kms/v1/keys/device-key-456/verify" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "SHA256WithECDSA",
    "message": "'"$MESSAGE"'",
    "signature": "'"$SIGNATURE"'",
    "message_type": "RAW"
  }'

---

Best Practices

Choose Appropriate Hash Algorithm

• SHA-256: Standard choice for most applications
• SHA-384/512: Use when security requirements demand higher resistance to collisions
• Match hash strength to key strength (e.g., SHA-256 for 2048-bit RSA, SHA-384 for 3072-bit RSA)

RAW vs DIGEST Message Type

• RAW: Use when you want the KMS to handle hashing. Simpler and less error-prone.
• DIGEST: Use when:
  • You’re signing very large data (hash locally to reduce network transfer)
  • You need to match existing signature formats
  • You’re implementing specific protocols that require pre-hashing

Signature Verification

• Always verify signatures using the same algorithm used for signing
• Ensure message encoding (base64) is consistent between signing and verification
• For certificate validation, verify the entire chain, not just the leaf certificate

Performance Optimization

• For large files, compute the digest locally and use message_type: "DIGEST"
• Cache public keys for verification to avoid repeated API calls
• Consider batching signature operations when possible

Security Considerations

• Never expose private keys - always use KMS operations
• Rotate signing keys according to your security policy
• Use HSM-backed engines (AWS KMS, Vault, PKCS#11) for critical signing operations
• Implement proper access controls on signing keys
• Log all signing operations for audit purposes

---

Error Handling

Common errors when performing cryptographic operations:

Invalid Key ID

{
  "err": "Key not found"
}

Solution: Verify the key ID exists using GET /keys/{id}

Algorithm Mismatch

{
  "err": "Algorithm not supported for this key type"
}

Solution: Use a compatible algorithm for your key type (e.g., SHA256WithRSA for RSA keys, SHA256WithECDSA for ECDSA keys)

Invalid Message Format

{
  "err": "Invalid base64 encoding"
}

Solution: Ensure your message and signature are properly base64 encoded

Signature Verification Failed

{
  "valid": false,
  "error": "signature verification failed"
}

Possible causes:

• Wrong message or signature
• Algorithm mismatch
• Message encoding issue
• Corrupted signature data