Elektroniskā paraksta nodrošinātāja API

Elektroniskā paraksta API ģenerē digitālos parakstus (PKCS #1) ar parakstīšanas identitātēm, ko pārvalda platforma.

Iegūstiet parakstīšanas identitātes informāciju

Ir divu veidu parakstīšanas identitātes — viena elektroniskajai parakstīšanai un otra autentifikācijai

Pieprasījums

GET /trustedx-resources/esigp/v1/sign_identities/{sign_identity_id}

Autorizācija

Pieprasījumā ir jāietver nesēja piekļuves marķieris, ko ģenerējis tā pakalpojuma uzticams autorizācijas serveris, no kura tiek pieprasīta informācija par parakstīšanas identitāti, un kas ir saistīts ar domēnu, kuram pieder identitāte. Šis marķieris ir jāizmanto atbilstoši RFC 6750. Tam ir jābūt urn:safelayer:eidas:sign:identity:profile tvērumam (scope).

Marķieris ir jāiekļauj HTTP autorizācijas galvenē šādi:

Authorization: Bearer <token>

Piekļuves marķieri var iegūt, izmantojot autorizācijas koda piešķiršanu vai pakalpojumu sniedzēja akreditācijas datu piešķiršanas OAuth 2.0 plūsmu.

Piemērs

GET /trustedx-resources/esigp/v1/sign_identities/12345678 HTTP/1.1
Authorization: Bearer mF_9.B5f-4.1JqM

Atbilde

Atbildes pamatteksta attēlojums JSON formātā ir norādīts tālāk

{
 "id" : {string},
 "self" : {string},
 "description" : {string},
 "labels" : [ {string} ],
 "type" : {string},
 "device_id" : {string},
 "domain" : {string},
 "access" : [ {
     "user_id" : {string}
 } ]
 "details" : {
      "certificate" : {string},
      "activation_mode": {string},
      "public_key" : {string}
 },
 "links" :  {
      <operation_alias> : {
           "auth" : {
               "oauth2": {
                  "scopes": [ {string} ]
               }
           }
      }   
      },
 "status" : {
    "value" : {string},
    "reason" : {string}
 }
}
ParametrsApraksts
idParakstīšanas identitātes identifikators.
selfPiekļuve parakstīšanas identitātes URL.
descriptionParakstīšanas identitātes apraksts.
labels[ ]Ar parakstīšanas identitāti saistīto tagu saraksts.
typeParakstīšanas identitātes veids. Šim parametram pašlaik vienmēr ir pki:x509 vērtība.
device_idIerīce, kurā atrodas ar parakstīšanas identitāti saistīto atslēgu privātā daļa. Šis parametrs ir tikai parakstīšanas identitātēm mobilajās ierīcēs.
domainDomēns, kuram pieder parakstīšanas identitāte.
access[ ]Informācija par piekļuves kontroli parakstīšanas identitātei.
access[ ].user_idTā galalietotāja identifikators, kuram ir piekļuve parakstīšanas identitātei.
detailsSīkāka informācija par parakstīšanas identitātes ieviešanu.
details.certificateX.509 sertifikāts, kas kodēts DER un base64. Šis parametrs ir tikai pki:x509 parakstīšanas identitātēm.
details.activation_modeParakstīšanas identitātes aktivizācijas režīms. Šis parametrs ir tikai servera parakstīšanas identitātēm, un tam var būt šādas vērtības: hsm-pwd: paraksta identitāti aktivizē parole, ko ievada īpašnieks un apstiprina HSM.
details.public_keyAr parakstīšanas identitāti saistīto atslēgu publiskā daļa. PublicKeyInfo ASN.1 struktūra, kas kodēta DER un base64. Šis parametrs ir tikai pki:x509 parakstīšanas identitātēm.
linksInformācija par operācijām, kurās tiek izmantota parakstīšanas identitāte.
links.\<operation_alias>Informācija par \<operation_alias> operāciju saistībā ar parakstīšanas identitātes izmantošanu. Šobrīd vienīgā iespējamā vērtība priekš \<operation_alias> ir Signatures.create.server.raw
links.\<operation_alias>.authAutorizācijas informācija par \<operation_alias> operāciju saistībā ar parakstīšanas identitātes izmantošanu.
links.\<operation_alias>.auth.oauth2OAuth 2.0 autorizācijas informācija par \<_operation_alias_> operāciju saistībā ar parakstīšanas identitātes izmantošanu.
links.\<operation_alias>.auth.oauth2.scopes[ ]OAuth 2.0 tvērumu kopums, kas nepieciešams piekļuvei\<operation_alias> operācijai, lai šī operācija varētu izmantot parakstīšanas identitāti.
statusInformācija par parakstīšanas identitātes statusu.
status.value

Parakstīšanas identitātes statuss.
enabled: parakstīšanas identitāte ir iespējota.

disabled: parakstīšanas identitāte ir atspējota.

locked: parakstīšanas identitāte ir bloķēta.

status.reasonIemesls, kāpēc parakstīšanas identitāte ir pašreizējā stāvoklī. Šis parametrs nav obligāts un parasti tiek izmantots, lai norādītu, kāpēc parakstīšanas identitāte ir bloķēta vai atspējota.
👍

Lai saņemtu parakstīšanas sertifikātu, etiķešu masīvs satur serverid .

Lai saņemtu autentifikācijas sertifikātu, etiķešu masīvs satur mobileid .

eID Scan parakstīšanas identitāte

Lai identificētu lietotāja eID Scan parakstīšanas identitāti, nolasiet sign_identities masīvu, ko atgriež Lietotāja informācijas nodrošinātāja API.

Izvēlieties identitāti, kas atbilst abiem šiem nosacījumiem:

  • labels satur:
    • eid
    • x509:keyUsage:contentCommitment
  • status.value ir vienāds ar enabled

Piemērs

{
  "id": "qbp5bg8oe15buhkqj1g5bnpnk0",
  "labels": [
    "eid",
    "x509:keyUsage:contentCommitment",
    "eparaksts"
  ],
  "status": {
    "value": "enabled"
  }
}

Aktīvas parakstīšanas identitātes nav

Ja identitāti, kas atbilst iepriekš minētajiem kritērijiem, nav iespējams atrast, lietotājam nav aktīvas eID Scan parakstīšanas identitātes.

Identitātes izmantošana

Lauka id vērtība ir jāizmanto visos turpmākajos parakstīšanas pieprasījumos.


Izveidojiet digitālo parakstu serverī

Apraksts

Izveido datu ciparparakstu (PKCS #1), izmantojot parakstīšanas identitāti serverī. Kā ievadi var saņemt datu jaucējvērtību (hash) vai baitu virkni, kas jāparaksta neapstrādātā veidā.

Paraksts tiek izveidots ar parakstīšanas identitāti serverī, kas norādīts pieprasījumā. Šai identitātei ir jāpieder galalietotājam, kura vārdā tiek veikta darbība.

Pieprasījums

POST /trustedx-resources/esigp/v1/signatures/server/raw

Content-type galvene

Content-Type: application/json

Pamatteksts (body)

{
 "digest_value" : {string},
 "signature_algorithm" : {string},
 "sign_identity_id" : {string}
}
ParametrsApraksts
digest_valueHash of the data to be signed encoded in base64.
signature_algorithmAlgoritms, kas jāizmanto digitālā paraksta ģenerēšanai (rsa-sha1, rsa-sha256, rsa-sha384, rsa-sha512 un ecdsa). Paraksta algoritma izvēlei jābūt balstītai uz klienta sertifikātā atrodamo atslēgas algoritmu.
sign_identity_idParakstīšanas identitātes identifikators, kas jāizmanto paraksta ģenerēšanai (tai jābūt servera parakstīšanas identitātei, kas pieder galalietotājam, kura vārdā tiek veikts paraksts).

Piemērs

POST /trustedx-resources/esigp/v1/signatures/server/raw
Host: eidas.eparaksts.lv
Content-Type: application/json
Authorization: Bearer cbc...6daf
Content-Length: 213
{
   "digest_value" : "n4bQgYhMfWWaL+qgxVrQFaO/TxsrC4Is0V1sFbDwCgg",
   "signature_algorithm" : "rsa-sha256",
   "sign_identity_id" : "nio...omq"
}

Atbilde

Atbilde satur PKCS #1 paraksta bināro vērtību.

🚧

Ja izmantojat Sign API pakalpojumu, PKCS#1 ir jābūt base64 kodētam ( hexToBase64 )


Serverī izveidojiet digitālā paraksta partiju

Apraksts

Izveido digitālu parakstu partiju no datu jaucējvērtībām (hash), kas jāparaksta, izmantojot servera parakstīšanas identitāti.

Paraksts tiek izveidots ar parakstīšanas identitāti serverī, kas norādīts pieprasījumā. Šai identitātei ir jāpieder galalietotājam, kura vārdā tiek veikta darbība.

🚧

Šo metodi var izmantot arī vienreizējai parakstīšanai. Galvenās atšķirības: partijas metodes atbilde ar base64 kodētiem parakstītiem datiem, bet vienreizējas parakstīšanas metodes atbilde ar PKCS#1 neapstrādātu parakstu.

Apraksts

POST /trustedx-resources/esigp/v1/signatures/server/raw/batch

Content-type galvener

Content-Type: application/json

Pamatteksts (body)

{
    "sign_identity_id" : {string},
    "signature_algorithm" : {string},
    "requests" : [
        {
            "digest_value" : {string},
            "signature_algorithm" : {string}
        }
    ]
}
ParametrsApraksts
sign_identity_idParakstīšanas identitātes identifikators, kas jāizmanto paraksta ģenerēšanai (tai jābūt servera parakstīšanas identitātei, kas pieder galalietotājam, kura vārdā tiek veikts paraksts).
signature_algorithmAlgoritms parakstu ģenerēšanai izmantojamo kriptogrāfisko jaucēju (rsa-sha1, rsa-sha256, rsa-sha384 un rsa-sha512) iegūšanai, ja katram no tiem nav norādīts cits algoritms.
requests[ ]Informācija par kriptogrāfijas jaucējkodiem (hashes), kas jāizmanto parakstu ģenerēšanai.
requests[ ].digest_valueParakstu ģenerēšanai izmantotā kriptogrāfiskā jaucējkodējuma Base64 kodējums.
requests[ ].signature_algorithmAlgoritms, kas jāizmanto digitālā paraksta ģenerēšanai (rsa-sha1, rsa-sha256, rsa-sha384, rsa-sha512 un ecdsa). Paraksta algoritma izvēlei jābūt balstītai uz klienta sertifikātā atrodamo atslēgas algoritmu.

Piekļuves kontrole

Pieprasījumā ir jāietver nesēja piekļuves marķieris (bearer access token), ko ģenerējis uzticams autorizācijas serveris, kas ir saistīts ar paraksta identitātes domēnu, ko jāizmanto paraksta ģenerēšanai. Šim marķierim (token) ir jābūt tvērumam (scope), kas ietver parakstīšanas identitātei konfigurēto vērtību (pēc noklusējuma urn:safelayer:eidas:sign:identity:use:server ), un tas ir jāizmanto atbilstoši RFC 6750. Būtībā marķieris ir jāiekļauj Autorizācijas galvenē šādi:

Authorization: Bearer <token>

Piekļuves marķieris ir jāiegūst, izmantojot autorizācijas koda piešķiršanas OAuth 2.0 plūsmu.

Piemērs

POST /trustedx-resources/esigp/v1/signatures/server/raw/batch
Host: eidas.eparaksts.lv
Content-Type: application/json
Authorization: Bearer cbc...6daf
Content-Length: 213
{
    "sign_identity_id": "12345678",
    "signature_algorithm": "rsa-sha1",
    "requests": [
        {
            "digest_value": "RXN0byBlcyB1biBoYXNoIFNoYTE=",
            "signature_algorithm": "rsa-sha1"
        },
        {
            "digest_value": "siHZ27CDp/M0KNfCo8MZiuklYU1wIQ4ocWzKp81N23k",
            "signature_algorithm": "rsa-sha256"
        }
    ]
}

Atbilde

Pamatteksts (body)

{
    "signatures" : [ {string} ]
}
ParametrsApraksts
signatures[]Digitāli paraksti, kas kodēti base64. Parakstiem ir tāda pati secība, kādā pieprasījumā tiek parādīti kriptogrāfiskie jaucējfaili (hashes), no kuriem tie tika izveidoti.

eID Scan parakstīšanas pieprasījumi

eID Scan parakstīšanas pieprasījumos data_info.html īpašībai ir jāsatur Base64 kodēts JSON objekts ar prefiksu =.

Formāts

=BASE64(JSON)

Satura piemērs

{
  "code": "8695",
  "message": "Please review and confirm this signature request",
  "params": {
    "transaction_type": "signature",
    "force_pin": true,
    "deadline": 1737467942694
  },
  "api_level": 1
}

Lauku apraksts

LauksApraksts
codeVerifikācijas kods, kas tiek attēlots lietotājam
messageLietotājam paredzēts paziņojums (maksimāli 300 rakstzīmes)
transaction_typeJābūt vērtībai signature
force_pinJābūt vērtībai true
deadlinePašreizējais laika zīmogs (timestamp) + 2 minūtes
api_levelJābūt vērtībai 1

Verifikācijas kods

Uzsākot eID Scan parakstīšanas operāciju, pakalpojuma sniedzējam ir jāattēlo tas pats verifikācijas kods, kas tiek parādīts mobilajā lietotnē.

Kods tiek aprēķināts no faktiskās digest_value vērtības, izmantojot šādu algoritmu:

integer(SHA256(digest_value)[-2:-1]) mod 10000

Aprēķina soļi

  1. Aprēķiniet SHA-256 jaucējvērtību (hash) no sākotnējās digest_value vērtības.
  2. Izgūstiet divus galējos baitus no rezultāta labās puses.
  3. Interpretējiet tos kā neparakstītu (unsigned) veselu skaitli big-endian formātā.
  4. Attēlojiet pēdējos četrus ciparus.

Svarīgi: Verifikācijas koda aprēķināšanai vienmēr ir jāizmanto SHA-256 algoritms, neatkarīgi no tā, kāds jaucēšanas (hash) algoritms tiek izmantots parakstīšanai.


Did this page help you?