API reference

Authorization

Cleverbase’s CSC hash signing application uses OAuth 2.0 for authorization.

GET /oauth2/authorize

• RFC 6749, Section 3.1
• CSC

Description

Starts the OAuth 2.0 authorization server using an Authorization Code flow, as described in Section 1.3.1 of RFC 6749, to request authorization for the user to access the remote service resources. The authorization is returned in the form of an authorization code, which the signature application SHALL then use to obtain an access token with the oauth2/token method.

The authorization server SHOULD support two access token scopes: “service” and “credential”. These scopes SHALL only be used separately to obtain an access token suitable for service and credential authorization respectively.

Input parameters

Response

Examples

• Service Scope Request

  GET /oauth2/authorize?
  response_type=code&
  client_id=<OAuth2_client_id>&
  redirect_uri=<OAuth2_redirect_uri>&
  scope=service&
  lang=en-US&
  state=12345678

• Service Scope Response

  HTTP/1.1 302 Found
  Location: <OAuth2_redirect_uri>?
  code=FhkXf9P269L8g&
  state=12345678

• Credential Scope Request

  GET /oauth2/authorize?
  response_type=code&
  client_id=<OAuth2_client_id>&
  redirect_uri=<OAuth2_redirect_uri>&
  scope=credential&
  credentialID=GX0112348&
  numSignatures=1&
  hash=MTIzNDU2Nzg5MHF3ZXJ0enVpb3Bhc2RmZ2hqa2zDtnl4
  &state=12345678

• Credential Scope Response

  HTTP/1.1 302 Found
  Location: <OAuth2_redirect_uri>?code=HS9naJKWwp901hBcK348IUHiuH8374&
  state=12345678

• Error Response

  HTTP/1.1 302 Found
  Location: <OAuth2_redirect_uri>?error=invalid_request&
  error_description=Invalid%20Authorization%20Code&state=12345678

Access tokens

POST /oauth2/token

• RFC 6749, Section 3.2
• CSC

Description

Obtain an OAuth 2.0 bearer access token from the authorization server by passing either the client credentials pre-assigned by the authorization server or the authorization code returned by the authorization server after a successful user authentication, along with the client ID and client secret in possession of the signature application.

Input parameters

Input headers

Response

Examples

• Sample Request (Authorization code flow)

  POST /oauth2/token HTTP/1.1
  Authorization: Basic Y2xpZW50SUQ6cGFzc3dvcmQ
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code&
  code=FhkXf9P269L8g&
  client_id=<OAuth2_client_id>&
  redirect_uri=<OAuth2_redirect_uri>

• Sample Response (for service scope)

  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  
  {
    "access_token": "4/CKN69L8gdSYp5_pwH3XlFQZ3ndFhkXf9P2_TiHRG-bA",
    "token_type": "Bearer",
    "expires_in": 3600
  }

• Sample Response (for credential scope)

  HTTP/1.1 200 OK
  Content-Type: application/json;charset=UTF-8
  
  {
    "access_token": "3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5H3XlFQZ3ndFhkXf9P2",
    "token_type": "SAD",
    "expires_in": 300
  }

Credentials

POST /csc/v1/credentials/list

• CSC Chapter 11.4

Description

Returns the list of credentials associated with a user identifier.

Input Parameters

Input headers

Response

Sample Request

POST /csc/v1/credentials/list HTTP/1.1
Authorization: Bearer 4/CKN69L8gdSYp5_pwH3XlFQZ3ndFhkXf9P2_TiHRG-bA
Content-Type: application/json

{
  "maxResults": 10
}

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "credentialIDs": [ "GX0112348", "HX0224685" ]
}

POST /csc/v1/credentials/info

• CSC Chapter 11.5

Description

Returns the main identity information and public key certificate of the credential obtained with the /csc/v1/credentials/list endpoint.

Input Parameters

Input headers

Response

Sample Request

POST /csc/v1/credentials/info HTTP/1.1
Authorization: Bearer 4/CKN69L8gdSYp5_pwH3XlFQZ3ndFhkXf9P2_TiHRG-bA
Content-Type: application/json

{
  "credentialID": "GX0112348"
}

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "key" : {
    "status" : "enabled",
    "algo" : [
      "1.2.840.113549.1.1.1"
    ],
    "len" : 2048
  },
  "cert" : {
    "certificates" : [
      "MIIGDSGDGSD...."
    ]
  },
  "authMode" : "oauth2code"
}

Signatures

POST /csc/v1/signatures/signHash

• CSC Chapter 11.9

Description

Calculate the remote digital signature of one or multiple hash values provided in input. This method requires credential authorization in the form of Signature Activation Data (SAD).

Input Parameters

Input headers

Response

Sample Request

POST /csc/v1/signatures/signHash HTTP/1.1
Content-Type: application/json
Authorization: Bearer 4/CKN69L8gdSYp5_pwH3XlFQZ3ndFhkXf9P2_TiHRG-bA

{
  "credentialID": "GX0112348",
  "SAD": "3XlFQZ3ndFhkXf9P24/CKN69L8gdSYp5H3XlFQZ3ndFhkXf9P2",
  "hash": [
    "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI="
  ],
  "hashAlgo": "2.16.840.1.101.3.4.2.1",
  "signAlgo": "1.2.840.113549.1.1.1"
}

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "signatures": [
    "KedJuTob5gtvYx9qM3k3gm7kbLBwVbEQRl26S2tmXjqNND7MRGtoew=="
  ]
}