# HSM

Hardware Security Module — Thales Luna Cloud (DPoD)

## Create HSM key pair

> Generates an Ed25519 key pair on the HSM partition. Returns the Zetrix address and raw public key hex. The returned address is used as the identifier for subsequent sign requests.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"HSM","description":"Hardware Security Module — Thales Luna Cloud (DPoD)"}],"servers":[{"url":"https://api-sandbox.zetrix.com","description":"Sandbox Environment – Use this for development and testing."}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer access token. Include in all requests as: `Authorization: Bearer <your_access_token>`"}},"schemas":{"HsmCreateAccountReqDto":{"type":"object","description":"Request to create an HSM-backed Ed25519 key pair","properties":{"label":{"type":"string","description":"Optional caller-supplied label suffix. Final key label = ZETRIX_<label> if provided, else ZETRIX_<uuid>."},"purpose":{"type":"string","description":"Optional purpose description for this key"},"password":{"type":"string","description":"User password used to encrypt the HSM key label in DB storage","minLength":8,"maxLength":128}},"required":["password"]},"ResponseWrapperHsmCreateAccountRespDto":{"type":"object","properties":{"object":{"$ref":"#/components/schemas/HsmCreateAccountRespDto"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"HsmCreateAccountRespDto":{"type":"object","description":"Response for HSM key pair creation","properties":{"publicKeyHex":{"type":"string","description":"Raw Ed25519 public key as hex string (64 hex chars = 32 bytes)"},"zetrixAddress":{"type":"string","description":"Zetrix blockchain address derived from the public key (e.g. ZTX3...). Use this as the identifier in subsequent sign requests."}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}},"paths":{"/ztx/hsm/create-account":{"post":{"tags":["HSM"],"summary":"Create HSM key pair","operationId":"createAccount","description":"Generates an Ed25519 key pair on the HSM partition. Returns the Zetrix address and raw public key hex. The returned address is used as the identifier for subsequent sign requests.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HsmCreateAccountReqDto"}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperHsmCreateAccountRespDto"}}}}}}}}}
```

## Sign blob with HSM

> Signs a hex-encoded transaction blob using the HSM-stored Ed25519 private key identified by the Zetrix address. The returned SignerEntity can be used directly in /tx/submit or /contract/submit.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"HSM","description":"Hardware Security Module — Thales Luna Cloud (DPoD)"}],"servers":[{"url":"https://api-sandbox.zetrix.com","description":"Sandbox Environment – Use this for development and testing."}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer access token. Include in all requests as: `Authorization: Bearer <your_access_token>`"}},"schemas":{"HsmBlobDataReqDto":{"type":"object","description":"Request to sign a transaction blob using the HSM","properties":{"blob":{"type":"string","description":"Hex-encoded transaction blob to sign (obtained from /tx/generate-blob or /contract/generate-blob)"},"password":{"type":"string","description":"User password used to decrypt the stored HSM key label","minLength":8,"maxLength":128},"address":{"type":"string","description":"Zetrix address returned by /hsm/create-account"}},"required":["blob","password","address"]},"ResponseWrapperListSignerEntity":{"type":"object","properties":{"object":{"type":"array","items":{"$ref":"#/components/schemas/SignerEntity"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"SignerEntity":{"type":"object","description":"A signer object containing a signature and public key pair. Used in transaction/contract submission requests.","properties":{"signBlob":{"type":"string","description":"Hex-encoded Ed25519 signature of the transaction blob."},"publicKey":{"type":"string","description":"Hex-encoded Ed25519 public key of the signer. Must be exactly 76 characters.","minLength":76,"maxLength":76}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}},"paths":{"/ztx/hsm/sign-blob":{"post":{"tags":["HSM"],"summary":"Sign blob with HSM","operationId":"signBlobHsm","description":"Signs a hex-encoded transaction blob using the HSM-stored Ed25519 private key identified by the Zetrix address. The returned SignerEntity can be used directly in /tx/submit or /contract/submit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HsmBlobDataReqDto"}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperListSignerEntity"}}}}}}}}}
```

## Sign message with HSM

> Signs a UTF-8 message using the HSM-stored Ed25519 private key identified by the Zetrix address.

```json
{"openapi":"3.1.0","info":{"title":"Zetrix Microservice API","version":"1.0.0"},"tags":[{"name":"HSM","description":"Hardware Security Module — Thales Luna Cloud (DPoD)"}],"servers":[{"url":"https://api-sandbox.zetrix.com","description":"Sandbox Environment – Use this for development and testing."}],"security":[{"Authorization":[]}],"components":{"securitySchemes":{"Authorization":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer access token. Include in all requests as: `Authorization: Bearer <your_access_token>`"}},"schemas":{"HsmMessageDataReqDto":{"type":"object","description":"Request to sign a UTF-8 message using the HSM","properties":{"message":{"type":"string","description":"UTF-8 message to sign"},"password":{"type":"string","description":"User password used to decrypt the stored HSM key label","minLength":8,"maxLength":128},"address":{"type":"string","description":"Zetrix address returned by /hsm/create-account"}},"required":["message","password","address"]},"ResponseWrapperListSignerEntity":{"type":"object","properties":{"object":{"type":"array","items":{"$ref":"#/components/schemas/SignerEntity"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/ResponseMessage"}},"success":{"type":"boolean"},"timestamp":{"type":"string","format":"date-time"},"traceId":{"type":"string"}}},"SignerEntity":{"type":"object","description":"A signer object containing a signature and public key pair. Used in transaction/contract submission requests.","properties":{"signBlob":{"type":"string","description":"Hex-encoded Ed25519 signature of the transaction blob."},"publicKey":{"type":"string","description":"Hex-encoded Ed25519 public key of the signer. Must be exactly 76 characters.","minLength":76,"maxLength":76}}},"ResponseMessage":{"type":"object","description":"A response message indicating informational, warning, or error details.","properties":{"type":{"type":"string","description":"Severity: `INFO`, `WARNING`, or `ERROR`.","enum":["INFO","ERROR","WARNING"]},"errorCode":{"type":"integer","format":"int32","description":"Numeric error code (0 = no error)."},"message":{"type":"string","description":"Human-readable description."}}}}},"paths":{"/ztx/hsm/sign-message":{"post":{"tags":["HSM"],"summary":"Sign message with HSM","operationId":"signMessageHsm","description":"Signs a UTF-8 message using the HSM-stored Ed25519 private key identified by the Zetrix address.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HsmMessageDataReqDto"}}}},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ResponseWrapperListSignerEntity"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zetrix.com/en/developer-resources/blockchain-as-a-services-baas/zetrix-service/hsm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.