Documentation:IntroductionSeal DocumentVerify DocumentHistoryMutual TLS

Mutual TLS

The default way of authenticating with the API is by providing the API key with each request. Additionally, Sealninja also supports strong authentication by means of Mutual TLS when sealing or verifying documents.

With Mutual TLS Authentication, not only the identity of the server is proven to the client (as is typically the case with https requests), but the identity of the client is also proven to the server. For this, the client has to use a certificate provided by a Certificate Authority when sending a request to the server. An extensive explanation on how this works can be found in this acticle by Andrew Howden.

Mutual TLS Authentication can be enabled from the account settings page. Once enabled, a X.509 certificate chain has to be used for every API request. The certificate has to be provided by a Certificate Authority, and the domain (common name) of the certificate should match the domain of the account's email address.

An example request to seal a document with curl using a certificate could look something like this:

curl --user 'api:YOUR_API_KEY' \
  --key YOUR_PRIVATE_KEY.pem \
  --cert YOUR_CERTIFICATE.pem \
  --form document='@invoice.pdf;type=application/pdf' \
  --form details='{"seller":"John","price":100}' \
  https://sealninja.com/api/documents/seal

The identity as provided by the certificate will also be added to the document's seal, making it available to everyone for verifying the document's origin at a later stage. The following certificate identity properties will be added to the seal, if available: country name, state or province name, locality name, organization name, organizational unit name, and common name.

Hence, when verifying a document sealed using Mutual TLS Authentication, the seal could look something like this:

{
  "sub": {
    "id": "1261688f-9a4c-4406-a5d5-743c4a20abcb",
    "name": "invoice.pdf",
    "mimetype": "application/pdf",
    "checksum": "2134158ac85fb250df1b67bec00aef6fc5fe6e233d7d0c5c931787ae0557a2c7598e53c176242f1ebf604c1aa06c3483b75c2ba7f8a34642820d19d87f252e63",
    "origin": {
      "id": "4a552be4-a606-4e7b-8786-02899283b5eb",
      "email": "info@example.com",
      "countryName": "US",
      "stateOrProvinceName": "California",
      "localityName": "Los Angeles",
      "organizationName": "Internet Corporation for Assigned Names and Numbers",
      "organizationalUnitName": "Technology",
      "commonName": "www.example.org",
      "certificate": "-----BEGIN CERTIFICATE----- MIIGBzCCBO+gAwIBAgIRAMVfBVtPZGgqeDvQ+Yn5T5swDQYJKoZIhvcNAQELBQAw gY8xCzAJBgNVBAYTAkdCMRswGQYDVQQIExJHcmVhdGVyIE1hbmNoZXN0ZXIxEDAO BgNVBAcTB1NhbGZvcmQxGDAWBgNVBAoTD1NlY3RpZ28gTGltaXRlZDE3MDUGA1UE AxMuU2VjdGlnbyBSU0EgRG9tYWluIFZhbGlkYXRpb24gU2VjdXJlIFNlcnZlciBD QTAeFw0xOTA1MTIwMDAwMDBaFw0yMDA1MTEyMzU5NTlaMFYxITAfBgNVBAsTGERv bWFpbiBDb250cm9sIFZhbGlkYXRlZDEUMBIGA1UECxMLUG9zaXRpdmVTU0wxGzAZ BgNVBAMTEnRlc3Quc2VhbG5pbmphLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEP ADCCAQoCggEBAMx0whhxSv0Z29KowAXNJ8SCd76XnmPrzPEAoX8RPyfZRZ5nC+uC aNj65waitsCm/uXWGKyWFXgFsgq/ydMAdDikh+2nP7BECFmfrCc36LdAmrhVKHFQ fYp2RyitOONl4jltvQZ2T8PMyZYqLJAS6mLYOiodJkW/U6SX/ALIDpJXY4Ox6Yvy MTpHvu94R5viFL8ymJjYSm+6ieuPeWs84JsOqLtk816uNPwDWtfQ+crM/oOUc1m5 KgerkO/Lf/Zsxe3PSu5Iu22WWxUrfyWqDvxZkBDr8h7tIQ3FrDmtNiGSo1K6iY53 uAm29m8gxFCwMSV5eD8z3OBDVcGOgxHm/9MCAwEAAaOCApQwggKQMB8GA1UdIwQY MBaAFI2MXsRUrYrhd+mb+ZsF4bgBjWHhMB0GA1UdDgQWBBRjbgr8vcC+grXidlUW yDBVi9gYnjAOBgNVHQ8BAf8EBAMCBaAwDAYDVR0TAQH/BAIwADAdBgNVHSUEFjAU BggrBgEFBQcDAQYIKwYBBQUHAwIwSQYDVR0gBEIwQDA0BgsrBgEEAbIxAQICBzAl MCMGCCsGAQUFBwIBFhdodHRwczovL3NlY3RpZ28uY29tL0NQUzAIBgZngQwBAgEw gYQGCCsGAQUFBwEBBHgwdjBPBggrBgEFBQcwAoZDaHR0cDovL2NydC5zZWN0aWdv LmNvbS9TZWN0aWdvUlNBRG9tYWluVmFsaWRhdGlvblNlY3VyZVNlcnZlckNBLmNy dDAjBggrBgEFBQcwAYYXaHR0cDovL29jc3Auc2VjdGlnby5jb20wNQYDVR0RBC4w LIISdGVzdC5zZWFsbmluamEuY29tghZ3d3cudGVzdC5zZWFsbmluamEuY29tMIIB BgYKKwYBBAHWeQIEAgSB9wSB9ADyAHcAu9nfvB+KcbWTlCOXqpJ7RzhXlQqrUuga kJZkNo4e0YUAAAFqrac/UQAABAMASDBGAiEA0F7nfbHOTyeWIYL/j4Y/H5Sk+cHx p6hnT4Yt8pexWEACIQDU20HuVjpOtVXNo4OJ4oztSmRgKguno2kd21XUcNvZHQB3 AF6nc/nfVsDntTZIfdBJ4DJ6kZoMhKESEoQYdZaBcUVYAAABaq2nP3IAAAQDAEgw RgIhAJ79d16pawJEh2+F8Of4iCp/rayLUmmXbR/W1nMOHgeIAiEAhOPxSmP2Kxl7 XSIwcB2KNtP3rTQ0H8B9XtH6nOPeknwwDQYJKoZIhvcNAQELBQADggEBAEo6gmnR 8WU2blorq5/KyTZSvviqdAoQDBQfrkhuct0xQJ+ZqnEXTG4I6KA/d80/8fW/C1bB Ba98MRfie7d7dwX7QHVJSXpf0YwMQ2/czJlGFn+QMyYUIhFICrC80elcTEtBmsOU DPzOYlULQjv1ckMXZaHW2khAyViUNMJobJ9gVBUd0z8YVJVrkl+aAuTgIwdYXlmJ lbx9LKKpwGyYhvV6jzV9CP6j9uBampIn0gsjH4HIRZV71vFkXfmGckHcGqMOa/1u ecLNIwD9LbYOa8WxgcQ7+/RHWKKZEwCkweBEvNAFxmDNPjjTUkZGMMjqelMhbhpk VN9d5/WeuoLHIcc= -----END CERTIFICATE-----"
    },
    "details": {
      "seller": "John",
      "price": 100
    }
  },
  "iss": {
    "email": "info@sealninja.com",
    "commonName": "sealninja.com",
    "certificate": "-----BEGIN CERTIFICATE----- MIIGBzCCBO+gAwIBAgIRAMVfBVtPZGgqeDvQ+Yn5T5swDQYJKoZIhvcNAQELBQAw gY8xCzAJBgNVBAYTAkdCMRswGQYDVQQIExJHcmVhdGVyIE1hbmNoZXN0ZXIxEDAO BgNVBAcTB1NhbGZvcmQxGDAWBgNVBAoTD1NlY3RpZ28gTGltaXRlZDE3MDUGA1UE AxMuU2VjdGlnbyBSU0EgRG9tYWluIFZhbGlkYXRpb24gU2VjdXJlIFNlcnZlciBD QTAeFw0xOTA1MTIwMDAwMDBaFw0yMDA1MTEyMzU5NTlaMFYxITAfBgNVBAsTGERv bWFpbiBDb250cm9sIFZhbGlkYXRlZDEUMBIGA1UECxMLUG9zaXRpdmVTU0wxGzAZ BgNVBAMTEnRlc3Quc2VhbG5pbmphLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEP ADCCAQoCggEBAMx0whhxSv0Z29KowAXNJ8SCd76XnmPrzPEAoX8RPyfZRZ5nC+uC aNj65waitsCm/uXWGKyWFXgFsgq/ydMAdDikh+2nP7BECFmfrCc36LdAmrhVKHFQ fYp2RyitOONl4jltvQZ2T8PMyZYqLJAS6mLYOiodJkW/U6SX/ALIDpJXY4Ox6Yvy MTpHvu94R5viFL8ymJjYSm+6ieuPeWs84JsOqLtk816uNPwDWtfQ+crM/oOUc1m5 KgerkO/Lf/Zsxe3PSu5Iu22WWxUrfyWqDvxZkBDr8h7tIQ3FrDmtNiGSo1K6iY53 uAm29m8gxFCwMSV5eD8z3OBDVcGOgxHm/9MCAwEAAaOCApQwggKQMB8GA1UdIwQY MBaAFI2MXsRUrYrhd+mb+ZsF4bgBjWHhMB0GA1UdDgQWBBRjbgr8vcC+grXidlUW yDBVi9gYnjAOBgNVHQ8BAf8EBAMCBaAwDAYDVR0TAQH/BAIwADAdBgNVHSUEFjAU BggrBgEFBQcDAQYIKwYBBQUHAwIwSQYDVR0gBEIwQDA0BgsrBgEEAbIxAQICBzAl MCMGCCsGAQUFBwIBFhdodHRwczovL3NlY3RpZ28uY29tL0NQUzAIBgZngQwBAgEw gYQGCCsGAQUFBwEBBHgwdjBPBggrBgEFBQcwAoZDaHR0cDovL2NydC5zZWN0aWdv LmNvbS9TZWN0aWdvUlNBRG9tYWluVmFsaWRhdGlvblNlY3VyZVNlcnZlckNBLmNy dDAjBggrBgEFBQcwAYYXaHR0cDovL29jc3Auc2VjdGlnby5jb20wNQYDVR0RBC4w LIISdGVzdC5zZWFsbmluamEuY29tghZ3d3cudGVzdC5zZWFsbmluamEuY29tMIIB BgYKKwYBBAHWeQIEAgSB9wSB9ADyAHcAu9nfvB+KcbWTlCOXqpJ7RzhXlQqrUuga kJZkNo4e0YUAAAFqrac/UQAABAMASDBGAiEA0F7nfbHOTyeWIYL/j4Y/H5Sk+cHx p6hnT4Yt8pexWEACIQDU20HuVjpOtVXNo4OJ4oztSmRgKguno2kd21XUcNvZHQB3 AF6nc/nfVsDntTZIfdBJ4DJ6kZoMhKESEoQYdZaBcUVYAAABaq2nP3IAAAQDAEgw RgIhAJ79d16pawJEh2+F8Of4iCp/rayLUmmXbR/W1nMOHgeIAiEAhOPxSmP2Kxl7 XSIwcB2KNtP3rTQ0H8B9XtH6nOPeknwwDQYJKoZIhvcNAQELBQADggEBAEo6gmnR 8WU2blorq5/KyTZSvviqdAoQDBQfrkhuct0xQJ+ZqnEXTG4I6KA/d80/8fW/C1bB Ba98MRfie7d7dwX7QHVJSXpf0YwMQ2/czJlGFn+QMyYUIhFICrC80elcTEtBmsOU DPzOYlULQjv1ckMXZaHW2khAyViUNMJobJ9gVBUd0z8YVJVrkl+aAuTgIwdYXlmJ lbx9LKKpwGyYhvV6jzV9CP6j9uBampIn0gsjH4HIRZV71vFkXfmGckHcGqMOa/1u ecLNIwD9LbYOa8WxgcQ7+/RHWKKZEwCkweBEvNAFxmDNPjjTUkZGMMjqelMhbhpk VN9d5/WeuoLHIcc= -----END CERTIFICATE-----"
  },
  "iat": 1540927192
}

DashboardDocumentationPricingTerms and ConditionsPrivacy Policy

GitHubTwitterLinkedIninfo@sealninja.com

 

© 2019 Maximum Entropy Software Solutions