From 64d00eb76671a26c943e461baddcadd93b98672b Mon Sep 17 00:00:00 2001
From: Nikos Fotiou <nikosft@gmail.com>
Date: Sun, 2 Jun 2024 13:52:19 +0300
Subject: [PATCH] more dumentation provided

---
 01_web/index.html        | 32 +++++++++++++++++++++++++++++++-
 02_api/index.html        | 37 +++++++++++++++++++++++++++++++++----
 index.html               |  2 +-
 search/search_index.json |  2 +-
 4 files changed, 66 insertions(+), 7 deletions(-)

diff --git a/01_web/index.html b/01_web/index.html
index 8c59d84..280523b 100644
--- a/01_web/index.html
+++ b/01_web/index.html
@@ -46,6 +46,10 @@
               <ul class="current">
                 <li class="toctree-l1 current"><a class="reference internal current" href="#">Web UI</a>
     <ul class="current">
+    <li class="toctree-l2"><a class="reference internal" href="#signing">Signing</a>
+    </li>
+    <li class="toctree-l2"><a class="reference internal" href="#verification">Verification</a>
+    </li>
     </ul>
                 </li>
               </ul>
@@ -77,7 +81,33 @@
             <div class="section" itemprop="articleBody">
               
                 <h1 id="web-ui">Web UI</h1>
-<p>STaaS can be accessed using a Web Ui</p>
+<p>STaaS can be accessed using a Web UI</p>
+<h2 id="signing">Signing</h2>
+<p>Artifact signature can be simply executed by following these steps:</p>
+<ol>
+<li>Press the <code>Sign</code> button</li>
+<li>Select a file to sign and optionally provide a comment</li>
+</ol>
+<p>In the background, the sign page calculates the digest of the selected file and
+submits it for signature. Signed files can be viewed by pressing the <code>Activity</code>
+button. From there, you can download the signature bundle and you can view information
+about the generated certificate, as well as, the record stored in the public registry.
+Signatures can be deleted from STaaS but they are not revoked. </p>
+<h2 id="verification">Verification</h2>
+<p>Generated bundles can be verified using the <a href="https://docs.sigstore.dev/signing/quickstart/">Cosign tool</a>.
+For this verification you would need STaaS's CA certificate. This can be obtained
+by clicking <a href="https://staas.excid.io/Sign/Certificate">here</a>.  A signature bundle can be
+verified using the following command:</p>
+<pre><code>cosign verify-blob \
+    --certificate-identity=YOUR_STAAS_IDENTITY \
+    --certificate-oidc-issuer=https://staas.excid.io \
+    --certificate-chain ca.pem \
+    --insecure-ignore-sct \
+    --bundle signature.bundle \
+    YOUR_FILE
+</code></pre>
+<p>The <code>--insecure-ignore-sct</code> flag is required since certificated generated using a private
+instance of Fulcio are not allowed to be recorded in the transparency registry.</p>
               
             </div>
           </div><footer>
diff --git a/02_api/index.html b/02_api/index.html
index 3f195bd..884f40b 100644
--- a/02_api/index.html
+++ b/02_api/index.html
@@ -54,8 +54,6 @@
     </li>
     <li class="toctree-l2"><a class="reference internal" href="#signing">Signing</a>
     </li>
-    <li class="toctree-l2"><a class="reference internal" href="#listing">Listing</a>
-    </li>
     </ul>
                 </li>
               </ul>
@@ -83,10 +81,41 @@
             <div class="section" itemprop="articleBody">
               
                 <h1 id="api">API</h1>
-<p>STaaS provides an API that can be used for signing files</p>
+<p>STaaS provides an API that can be used for signing files.</p>
 <h2 id="authorization">Authorization</h2>
+<p>In order to access STaaS API you need to obtain an authorization token. This can be obtained
+by pressing the <code>API tokens</code> button. The generated token should be included in all requests
+an Authorization header. Here is an example of a python script that uses an API token</p>
+<pre><code class="language-python">headers = {
+    'Authorization': 'Basic API_TOKEN'
+    }
+response = requests.request(&quot;POST&quot;, &quot;https://staas.excid.io/Api/Sign&quot;, headers=headers)
+</code></pre>
 <h2 id="signing">Signing</h2>
-<h2 id="listing">Listing</h2>
+<p>STaaS API provides a <code>Sign</code> endpoint that expects a JSON object that includes the 
+following attributes:</p>
+<ul>
+<li>HashBase64: Base64 encoding of a SHA-256 digest.</li>
+<li>Comment : A comment to be stored with the signature.</li>
+</ul>
+<p>This is an example of a python script that used the <code>Sign</code> API endpoint:</p>
+<pre><code class="language-python">with open(ARTIFACT_TO_SIGN,&quot;rb&quot;) as f:
+    bytes = f.read() # read entire file as bytes
+    artifact_hash = hashlib.sha256(bytes).digest()
+headers = {
+'Content-Type': 'application/json',
+'Authorization': 'Basic API_TOKEN'
+}
+payload = f&quot;&quot;&quot;
+{{
+    &quot;HashBase64&quot;:&quot;{base64.b64encode(artifact_hash).decode()}&quot;,
+    &quot;Comment&quot;:&quot;{item}&quot;  
+}}
+
+response = requests.request(&quot;POST&quot;, url + &quot;Api/Sign&quot;, headers=headers, data=payload)
+</code></pre>
+<p>If the signing process is successful, the <code>Sign</code> endpoint responds with HTTP code
+201 and the generated signature bundle.</p>
               
             </div>
           </div><footer>
diff --git a/index.html b/index.html
index 65ee485..1c03d18 100644
--- a/index.html
+++ b/index.html
@@ -145,5 +145,5 @@ <h2 id="technology-stack">Technology stack</h2>
 
 <!--
 MkDocs version : 1.6.0
-Build Date UTC : 2024-06-02 08:13:38.589272+00:00
+Build Date UTC : 2024-06-02 10:51:10.569135+00:00
 -->
diff --git a/search/search_index.json b/search/search_index.json
index 8fc072b..3c0621a 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Introduction This is the documentation of Software Transparency as a Service-STaaS platform. You can use STaaS for free here . You can access the source code of STaaS platform at GitHub . Overview STaaS platform is a free, open-source platform for signing artifacts. Signatures are generated using an one-time signing key. The corresponding public key is included in a short-lived certificate. This certificate also includes the identity of the user in the STaaS platform. User authentication in STaaS platform is implemented using OpenID Connect. Signatures are recorded in a public, auditable registry. Technology stack Short-lived certificates are generated using a private instance of Fulcio CA . Signatures are recorded in the public instance of Rekor . STaaS generates a signature bundle that can be verified using Cosign .","title":"Introduction"},{"location":"#introduction","text":"This is the documentation of Software Transparency as a Service-STaaS platform. You can use STaaS for free here . You can access the source code of STaaS platform at GitHub .","title":"Introduction"},{"location":"#overview","text":"STaaS platform is a free, open-source platform for signing artifacts. Signatures are generated using an one-time signing key. The corresponding public key is included in a short-lived certificate. This certificate also includes the identity of the user in the STaaS platform. User authentication in STaaS platform is implemented using OpenID Connect. Signatures are recorded in a public, auditable registry.","title":"Overview"},{"location":"#technology-stack","text":"Short-lived certificates are generated using a private instance of Fulcio CA . Signatures are recorded in the public instance of Rekor . STaaS generates a signature bundle that can be verified using Cosign .","title":"Technology stack"},{"location":"01_web/","text":"Web UI STaaS can be accessed using a Web Ui","title":"Web UI"},{"location":"01_web/#web-ui","text":"STaaS can be accessed using a Web Ui","title":"Web UI"},{"location":"02_api/","text":"API STaaS provides an API that can be used for signing files Authorization Signing Listing","title":"API"},{"location":"02_api/#api","text":"STaaS provides an API that can be used for signing files","title":"API"},{"location":"02_api/#authorization","text":"","title":"Authorization"},{"location":"02_api/#signing","text":"","title":"Signing"},{"location":"02_api/#listing","text":"","title":"Listing"}]}
\ No newline at end of file
+{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Introduction This is the documentation of Software Transparency as a Service-STaaS platform. You can use STaaS for free here . You can access the source code of STaaS platform at GitHub . Overview STaaS platform is a free, open-source platform for signing artifacts. Signatures are generated using an one-time signing key. The corresponding public key is included in a short-lived certificate. This certificate also includes the identity of the user in the STaaS platform. User authentication in STaaS platform is implemented using OpenID Connect. Signatures are recorded in a public, auditable registry. Technology stack Short-lived certificates are generated using a private instance of Fulcio CA . Signatures are recorded in the public instance of Rekor . STaaS generates a signature bundle that can be verified using Cosign .","title":"Introduction"},{"location":"#introduction","text":"This is the documentation of Software Transparency as a Service-STaaS platform. You can use STaaS for free here . You can access the source code of STaaS platform at GitHub .","title":"Introduction"},{"location":"#overview","text":"STaaS platform is a free, open-source platform for signing artifacts. Signatures are generated using an one-time signing key. The corresponding public key is included in a short-lived certificate. This certificate also includes the identity of the user in the STaaS platform. User authentication in STaaS platform is implemented using OpenID Connect. Signatures are recorded in a public, auditable registry.","title":"Overview"},{"location":"#technology-stack","text":"Short-lived certificates are generated using a private instance of Fulcio CA . Signatures are recorded in the public instance of Rekor . STaaS generates a signature bundle that can be verified using Cosign .","title":"Technology stack"},{"location":"01_web/","text":"Web UI STaaS can be accessed using a Web UI Signing Artifact signature can be simply executed by following these steps: Press the Sign button Select a file to sign and optionally provide a comment In the background, the sign page calculates the digest of the selected file and submits it for signature. Signed files can be viewed by pressing the Activity button. From there, you can download the signature bundle and you can view information about the generated certificate, as well as, the record stored in the public registry. Signatures can be deleted from STaaS but they are not revoked. Verification Generated bundles can be verified using the Cosign tool . For this verification you would need STaaS's CA certificate. This can be obtained by clicking here . A signature bundle can be verified using the following command: cosign verify-blob \\ --certificate-identity=YOUR_STAAS_IDENTITY \\ --certificate-oidc-issuer=https://staas.excid.io \\ --certificate-chain ca.pem \\ --insecure-ignore-sct \\ --bundle signature.bundle \\ YOUR_FILE The --insecure-ignore-sct flag is required since certificated generated using a private instance of Fulcio are not allowed to be recorded in the transparency registry.","title":"Web UI"},{"location":"01_web/#web-ui","text":"STaaS can be accessed using a Web UI","title":"Web UI"},{"location":"01_web/#signing","text":"Artifact signature can be simply executed by following these steps: Press the Sign button Select a file to sign and optionally provide a comment In the background, the sign page calculates the digest of the selected file and submits it for signature. Signed files can be viewed by pressing the Activity button. From there, you can download the signature bundle and you can view information about the generated certificate, as well as, the record stored in the public registry. Signatures can be deleted from STaaS but they are not revoked.","title":"Signing"},{"location":"01_web/#verification","text":"Generated bundles can be verified using the Cosign tool . For this verification you would need STaaS's CA certificate. This can be obtained by clicking here . A signature bundle can be verified using the following command: cosign verify-blob \\ --certificate-identity=YOUR_STAAS_IDENTITY \\ --certificate-oidc-issuer=https://staas.excid.io \\ --certificate-chain ca.pem \\ --insecure-ignore-sct \\ --bundle signature.bundle \\ YOUR_FILE The --insecure-ignore-sct flag is required since certificated generated using a private instance of Fulcio are not allowed to be recorded in the transparency registry.","title":"Verification"},{"location":"02_api/","text":"API STaaS provides an API that can be used for signing files. Authorization In order to access STaaS API you need to obtain an authorization token. This can be obtained by pressing the API tokens button. The generated token should be included in all requests an Authorization header. Here is an example of a python script that uses an API token headers = { 'Authorization': 'Basic API_TOKEN' } response = requests.request(\"POST\", \"https://staas.excid.io/Api/Sign\", headers=headers) Signing STaaS API provides a Sign endpoint that expects a JSON object that includes the following attributes: HashBase64: Base64 encoding of a SHA-256 digest. Comment : A comment to be stored with the signature. This is an example of a python script that used the Sign API endpoint: with open(ARTIFACT_TO_SIGN,\"rb\") as f: bytes = f.read() # read entire file as bytes artifact_hash = hashlib.sha256(bytes).digest() headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic API_TOKEN' } payload = f\"\"\" {{ \"HashBase64\":\"{base64.b64encode(artifact_hash).decode()}\", \"Comment\":\"{item}\" }} response = requests.request(\"POST\", url + \"Api/Sign\", headers=headers, data=payload) If the signing process is successful, the Sign endpoint responds with HTTP code 201 and the generated signature bundle.","title":"API"},{"location":"02_api/#api","text":"STaaS provides an API that can be used for signing files.","title":"API"},{"location":"02_api/#authorization","text":"In order to access STaaS API you need to obtain an authorization token. This can be obtained by pressing the API tokens button. The generated token should be included in all requests an Authorization header. Here is an example of a python script that uses an API token headers = { 'Authorization': 'Basic API_TOKEN' } response = requests.request(\"POST\", \"https://staas.excid.io/Api/Sign\", headers=headers)","title":"Authorization"},{"location":"02_api/#signing","text":"STaaS API provides a Sign endpoint that expects a JSON object that includes the following attributes: HashBase64: Base64 encoding of a SHA-256 digest. Comment : A comment to be stored with the signature. This is an example of a python script that used the Sign API endpoint: with open(ARTIFACT_TO_SIGN,\"rb\") as f: bytes = f.read() # read entire file as bytes artifact_hash = hashlib.sha256(bytes).digest() headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic API_TOKEN' } payload = f\"\"\" {{ \"HashBase64\":\"{base64.b64encode(artifact_hash).decode()}\", \"Comment\":\"{item}\" }} response = requests.request(\"POST\", url + \"Api/Sign\", headers=headers, data=payload) If the signing process is successful, the Sign endpoint responds with HTTP code 201 and the generated signature bundle.","title":"Signing"}]}
\ No newline at end of file