etiCORE logo
API docs by Redocly

(((etiCORE SAM-Server Interface for terminals (1.0.0-rc.1)

Download OpenAPI specification:

License: etiCORE terms of use

Interface of the (((etiCORE SAM-Server for (((etiCORE terminals.

info

information about the SAM-Server application

Provides general information about the SAM-Server application.

Authorizations:
BasicAuthBearerAuthApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "vendorName": "ACME Corporation",
  • "productName": "ACME SAM-Server Enterprise Edition",
  • "productSoftwareVersion": "2.5.0",
  • "samSpecVersion": "1.0.8",
  • "samServerTerminalSpecVersion": "1.0.0",
  • "samServerSpecVersion": "1.0.0",
  • "samServerTerminalInterfaceSpec": "1.0.0",
  • "samServerSchemeManagerInterfaceSpec": "1.0.0"
}

execution

execution interface for terminals

Get general information.

Provides general information about the configuration of the executor.

Authorizations:
BasicAuthBearerAuthApiKeyAuth
path Parameters
executorId
required
string
Example: executor1

Executor identifier

header Parameters
X-ClientId
required
string <uuid>
Example: 1ac81b4a-c810-4f0b-9cab-437408abb82b

Client identifier. To be set universally uniquely per client.

X-MessageNumber
required
integer <int64> >= 0
Example: 7

Number identifying the message uniquely together with the ClientId. Required for message recovery purposes. Useful for logging/investigative purposes.

Responses

Response samples

Content type
application/json

The key establishment information contain single entry for key reference 0x01 and secp256r1. The symmetric key directory consists of the entries 0x01 and 0x02, both for AES256. The vSAMs have product issuance rights for the organisation IDs 123 and 438.

{
  • "keyEstablishmentInformation": [
    ],
  • "symmetricKeyDirectory": "fyogdA5TAQEGCWCGSAFlAwQBKnQOUwECBglghkgBZQMEASo=",
  • "productIssuanceRightsTemplate": [
    ]
}

Execute commands within a session.

Executes a list of commands on a single vSAM. If no SAMS-session is referenced, a new session is established by acquiring an available vSAM. In this case, the response will contain session data. If no request body is present, a new SAMS-session will be established. If endSessionAfterwards is set to true, the SAMS-session will be ended after executing the commands (if any) and the volatile data of the session will be released.

In addition to the logic provided by the SAM, counter values are provided if used during command execution for the following counters in plain text: - action counter - entitlement issuance counter - product issuance counter (together with the corresponding OrganisationId)

Note that not all commands listed in the SAM Spec are supported for all parameters listed in the SAM Spec. For further details with respect to these restrictions, refer to the SAM-Server Spec. Unsupported commands / parameters lead to status words in the response APDUs indicating the corresponding errors.

To improve the potential of bundling several CAPDUs into a single invocation, WRAP_CAPDU and EXPORT_DERIVED_KEY CAPDUs may be annotated with the expectResponseTrailer property. In this case, the SAM-Server will skip the follow-up send sequence counter (SSC) values. The skipped SSC values are internally reserved and have to be used in a follow-up invocation for UNWRAP_RAPDU CAPDUs. For example usages, refer to the SAM-Server Spec.

Authorizations:
BasicAuthBearerAuthApiKeyAuth
path Parameters
executorId
required
string
Example: executor1

Executor identifier

header Parameters
X-ClientId
required
string <uuid>
Example: 1ac81b4a-c810-4f0b-9cab-437408abb82b

Client identifier. To be set universally uniquely per client.

X-MessageNumber
required
integer <int64> >= 0
Example: 7

Number identifying the message uniquely together with the ClientId. Required for message recovery purposes. Useful for logging/investigative purposes.

If-Match
required
string
Example: bfc13a64729c4290ef5b2c2730249c88ca92d82d

HTTP standard header If-Match

Request Body schema: application/json
One of
vSamSessionId
required
string (VSamSessionId) <= 18 characters

Identifier for a session between client and SAM-Server. Not to be confused with the secure messaging session between User Medium and SAM.

object (EstablishSession)

Indicates that a new vSAM session shall be established.

Array of objects (Capdus)

List of CAPDUs to be executed by the SAM-Server. Each of these CAPDUs might be annotated via the exceptResponseTrailer property. See documentation of the property for more information.

endSessionAfterwards
boolean
Default: false

If set to true, ends the session after execution of the capdus (if any).

Responses

Request samples

Content type
application/json
Example
{
  • "vSamSessionId": "K2AoWWFWydR61zGtx3",
  • "capdus": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "rapdus": [
    ]
}