https://eideasy-docs.netlify.app/assets/direct-e-sealing-api.html-b17ae253.js

1import{_ as o,r as i,o as c,c as l,b as s,d as a,a as e,w as p,e as u}from"./app-4488e322.js";const r={};function d(k,n){const t=i("RouterLink");return c(),l("div",null,[n[6]||(n[6]=s("h1",{id:"cloud-direct-e-sealing-api",tabindex:"-1"},[s("a",{class:"header-anchor",href:"#cloud-direct-e-sealing-api","aria-hidden":"true"},"#"),a(" Cloud Direct e-Sealing API")],-1)),n[7]||(n[7]=s("p",null,"Cloud Direct e-Sealing is a simplified server-to-server API for enabled clients. It lets your server submit CAdES file digests, full XML files, or XAdES document reference digests and receive signatures without redirecting an end user to a signing flow.",-1)),n[8]||(n[8]=s("h2",{id:"request-types",tabindex:"-1"},[s("a",{class:"header-anchor",href:"#request-types","aria-hidden":"true"},"#"),a(" Request types")],-1)),n[9]||(n[9]=s("p",null,"Choose the request type for your integration:",-1)),s("ul",null,[s("li",null,[e(t,{to:"/e-seal/direct-e-sealing-cades-request.html"},{default:p(()=>[...n[0]||(n[0]=[a("CAdES",-1)])]),_:1}),n[1]||(n[1]=a(": send file digests and receive detached signatures.",-1))]),s("li",null,[e(t,{to:"/e-seal/direct-e-sealing-xades-full-file-request.html"},{default:p(()=>[...n[2]||(n[2]=[a("XAdES full file",-1)])]),_:1}),n[3]||(n[3]=a(": send original XML files and receive complete signed XML.",-1))]),s("li",null,[e(t,{to:"/e-seal/direct-e-sealing-xades-reference-digest-request.html"},{default:p(()=>[...n[4]||(n[4]=[a("XAdES reference digest",-1)])]),_:1}),n[5]||(n[5]=a(": send canonicalized XML digests and receive signature fragments to insert into the original XML.",-1))])]),n[10]||(n[10]=u(`<p>All three use the endpoint and authentication described below.</p><h2 id="setup" tabindex="-1"><a class="header-anchor" href="#setup" aria-hidden="true">#</a> Setup</h2><p>To use Cloud Direct e-Sealing, you need a <code>client_id</code> and an e-seal HMAC key.</p><p>For the test environment:</p><ol><li>Create an account at <code>https://test.eideasy.com</code>.</li><li>Go to <strong>My Webpages</strong> and add a webpage.</li><li>Open <strong>My Webpages</strong> again and copy the <code>client_id</code> from the webpage you created.</li><li>Click <strong>EDIT</strong> for that webpage and scroll to <strong>Eseal Settings</strong>.</li><li>Click <strong>Generate</strong> to create the e-seal HMAC key.</li><li>Copy the generated HMAC key into a safe location. It is shown only once.</li><li>Send the <code>client_id</code> to eID Easy so test e-seal credentials can be configured for your client.</li></ol><h2 id="endpoint" tabindex="-1"><a class="header-anchor" href="#endpoint" aria-hidden="true">#</a> Endpoint</h2><p>Send a server-side <strong>POST</strong> request to:</p><p><code>https://id.eideasy.com/api/signatures/e-seal</code></p><p>For the test environment, use:</p><p><code>https://test.eideasy.com/api/signatures/e-seal</code></p><h2 id="authentication" tabindex="-1"><a class="header-anchor" href="#authentication" aria-hidden="true">#</a> Authentication</h2><p>Cloud Direct e-Sealing uses HMAC authentication only.</p><p>Send these headers with each request:</p><table><thead><tr><th>Header</th><th>Description</th></tr></thead><tbody><tr><td>Content-Type</td><td>Must be <code>application/json</code>.</td></tr><tr><td>X-Timestamp</td><td>UNIX timestamp in seconds. Maximum leeway is 5 minutes.</td></tr><tr><td>X-HMAC-Signature</td><td>Base64-encoded HMAC.</td></tr></tbody></table><p>The HMAC input must be exactly:</p><div class="language-text line-numbers-mode" data-ext="text"><pre class="language-text"><code>METHOD + PATH + X-Timestamp + RAW_REQUEST_BODY
2</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><p>For example:</p><div class="language-text line-numbers-mode" data-ext="text"><pre class="language-text"><code>POST/api/signatures/e-seal1710000000{&quot;client_id&quot;:&quot;client-id&quot;,&quot;files&quot;:[{&quot;fileName&quot;:&quot;document.pdf&quot;,&quot;fileContent&quot;:&quot;rxr4oMRqMAjrAdhgXjjYeLlh285M9UU1wxj+ksg3efY=&quot;,&quot;mimeType&quot;:&quot;application/pdf&quot;}],&quot;signature_form&quot;:&quot;CAdES&quot;,&quot;signature_profile&quot;:&quot;CAdES_BASELINE_T&quot;}
3</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><p>Calculate the signature as:</p><div class="language-text line-numbers-mode" data-ext="text"><pre class="language-text"><code>base64(hmac_sha256(message, eseal_hmac_key))
4</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div></div></div><div class="custom-container warning"><p class="custom-container-title">IMPORTANT</p><p>Sign the exact raw JSON body that is sent over the wire. Do not pretty-print, reorder, or reseri

4alize the JSON after signing it.</p></div><h3 id="postman-hmac-example" tabindex="-1"><a class="header-anchor" href="#postman-hmac-example" aria-hidden="true">#</a> Postman HMAC example</h3><p>You can use the following Postman pre-request script to generate the HMAC signature with the native Web Crypto API. Set the <code>hmac_key</code> variable to your e-seal HMAC key before sending the request.</p><div class="language-javascript line-numbers-mode" data-ext="js"><pre class="language-javascript"><code><span class="token keyword">const</span> secretKey <span class="token operator">=</span> pm<span class="token punctuation">.</span>variables<span class="token punctuation">.</span><span class="token function">get</span><span class="token punctuation">(</span><span class="token string">&#39;hmac_key&#39;</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
5<span class="token keyword">const</span> httpMethod <span class="token operator">=</span> pm<span class="token punctuation">.</span>request<span class="token punctuation">.</span>method<span class="token punctuation">;</span>
6<span class="token keyword">const</span> url <span class="token operator">=</span> pm<span class="token punctuation">.</span>request<span class="token punctuation">.</span>url<span class="token punctuation">.</span><span class="token function">getPath</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
7<span class="token keyword">const</span> timestamp <span class="token operator">=</span> Math<span class="token punctuation">.</span><span class="token function">floor</span><span class="token punctuation">(</span>Date<span class="token punctuation">.</span><span class="token function">now</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">/</span> <span class="token number">1000</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
8<span class="token keyword">const</span> body <span class="token operator">=</span> pm<span class="token punctuation">.</span>variables<span class="token punctuation">.</span><span class="token function">replaceIn</span><span class="token punctuation">(</span>pm<span class="token punctuation">.</span>request<span class="token punctuation">.</span>body<span class="token punctuation">.</span><span class="token function">toString</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
9
10<span class="token keyword">async</span> <span class="token keyword">function</span> <span class="token function">createHmac</span><span class="token punctuation">(</span><span class="token parameter">key<span class="token punctuation">,</span> value</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
11  <span class="token keyword">const</span> encoder <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">TextEncoder</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
12  <span class="token keyword">const</span> cryptoKey <span class="token operator">=</span> <span class="token keyword">await</span> crypto<span class="token punctuation">.</span>subtle<span class="token punctuation">.</span><span class="token function">importKey</span><span class="token punctuation">(</span>
13    <span class="token string">&#39;raw&#39;</span><span class="token punctuation">,</span>
14    encoder<span class="token punctuation">.</span><span class="token function">encode</span><span class="token punctuation">(</span>key<span class="token punctuation">)</span><span class="token punctuation">,</span>
15    <span class="token punctuation">{</span> <span class="token literal-property property">name</span><span class="token operator">:</span> <span class="token string">&#39;HMAC&#39;</span><span class="token punctuation">,</span> <span class="token literal-property property">hash</span><span class="token operator">:</span> <span class="token string">&#39;SHA-256&#39;</span> <span class="token punctuation">}</span><span class="token punctuation">,</span>
16    <span class="token boolean">

16false</span><span class="token punctuation">,</span>
17    <span class="token punctuation">[</span><span class="token string">&#39;sign&#39;</span><span class="token punctuation">]</span>
18  <span class="token punctuation">)</span><span class="token punctuation">;</span>
19  <span class="token keyword">const</span> signature <span class="token operator">=</span> <span class="token keyword">await</span> crypto<span class="token punctuation">.</span>subtle<span class="token punctuation">.</span><span class="token function">sign</span><span class="token punctuation">(</span><span class="token string">&#39;HMAC&#39;</span><span class="token punctuation">,</span> cryptoKey<span class="token punctuation">,</span> encoder<span class="token punctuation">.</span><span class="token function">encode</span><span class="token punctuation">(</span>value<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
20
21  <span class="token keyword">return</span> <span class="token function">btoa</span><span class="token punctuation">(</span>String<span class="token punctuation">.</span><span class="token function">fromCharCode</span><span class="token punctuation">(</span><span class="token operator">...</span><span class="token keyword">new</span> <span class="token class-name">Uint8Array</span><span class="token punctuation">(</span>signature<span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
22<span class="token punctuation">}</span>
23
24<span class="token keyword">const</span> message <span class="token operator">=</span> <span class="token template-string"><span class="token template-punctuation string">\`</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">\${</span>httpMethod<span class="token interpolation-punctuation punctuation">}</span></span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">\${</span>url<span class="token interpolation-punctuation punctuation">}</span></span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">\${</span>timestamp<span class="token interpolation-punctuation punctuation">}</span></span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">\${</span>body<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">\`</span></span><span class="token punctuation">;</span>
25<span class="token keyword">const</span> signature <span class="token operator">=</span> <span class="token keyword">await</span> <span class="token function">createHmac</span><span class="token punctuation">(</span>secretKey<span class="token punctuation">,</span> message<span class="token punctuation">)</span><span class="token punctuation">;</span>
26
27pm<span class="token punctuation">.</span>request<span class="token punctuation">.</span>headers<span class="token punctuation">.</span><span class="token function">upsert</span><span class="token punctuation">(</span><span class="token punctuation">{</span> <span class="token literal-property property">key</span><span class="token operator">:</span> <span class="token string">&#39;X-HMAC-Signature&#39;</span><span class="token punctuation">,</span> <span class="token literal-property property">value</span><span class="token operator">:</span> signature <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
28pm<span class="token punctuation">.</span>request<span class="token punctuation">.</span>headers<span class="token punctuation">.</span><span class="token function">upsert</span><span class="token punctuation">(</span><span class="token punctuation">{</span> <span class="token literal-property property">key</span><span class="token operator">:</span> <span class="token string">&#39;X-Timestamp&#39;</span><span class="token punctuation">,</span> <span class="token literal-property property">value</span><span class="token operator">:</span> timestamp <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
29pm<span class="token punctuation">.</span>request<span class="token punctuation">.</span>headers<span class="token punctuation">.</span><span class="token function">upsert</span><span class="token punctuation">(</span><span class="token punctuation">{</span> <span class="token literal-property property">key</span><span class="token operator">:</span> <span class="token string">&#39;Content-Type&#39;</span><span class="token punctuation">,</span> <span class="token literal-property property">value</span><span class="token operator">:</span> <span class="token string">&#39;application/json&#39;</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
30
31console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">&#39;Message:&#39;</span><span class="token punctuation">,</span> message<span class="token punctuation">)</span><span class="token punctuation">;</span>
32console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">&#39;Signature:&#39;</span><span class="token punctuation">,</span> signature<span class="token punctuation">)</span><span class="token punctuation">;</span>
33console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">&#39;Timestamp:&#39;</span><span class="token punctuation">,</span> timestamp<span class="token punctuation">)</span><span class="token punctuation">;</span>
34</code></pre><div class="line-numbers" aria-hidden="true"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div>`,24))])}const g=o(r,[["render",d],["__file","direct-e-sealing-api.html.vue"]]);export{g as default};