SignPath

Crypto Providers  ❯  REST API

Overview

As an alternative to using a Crypto Provider client, signing requests to a “Hash signing data” project can also be performed directly via SignPath’s REST API.

Signing Request

See HTTP REST API for basic instructions to submit a signing request.

Fast signing

For hash data we recommend using a fast signing request. These requests are performed immediately without queuing, and the API immediately returns the signed artifact.

  • Provide the additional field IsFastSigningRequest with the value true
  • The API returns the JSON-formatted result (see response description)

(By default, the API returns a signing request ID that can be used to get the result.)

Artifact format for signing hash digests

JSON property Value Remarks

SignatureAlgorithm

RSA keys:

  • RsaPkcs1: PKCS #1 v1.5 padding mode
  • RsaPss: PSS padding mode (PKCS #1 v2.1)

Elliptic curve keys: Ecdsa

RsaHashAlgorithm

The OID for the hash algorithm used. Available values:

  • MD5: 1.2.840.113549.2.5
  • SHA1: 1.3.14.3.2.26
  • SHA-256: 2.16.840.1.101.3.4.2.1
  • SHA-384: 2.16.840.1.101.3.4.2.2
  • SHA-512: 2.16.840.1.101.3.4.2.3

Only used for RSA keys.

EcdsaSignatureFormat

  • Ieee (default): IEEE P1363 fixed-size signature block
  • Asn1: RFC 3279 ASN.1 sequence

Only used for ECDSA keys.

Base64EncodedHash

The Base64 encoded hash value to sign.

For RSA, the result of the function specified as RsaHashAlgorithm.

Metadata

CreatingProcess object with CommandLine and User properties (see example below)

Can contain arbitrary metadata JSON values. Specified values are used by SignPath crypto providers.

Key length

SignPath crypto providers use the file name payload.json for hash digest artifacts.

Response

The response artifact has the same format and values as the request artifact with the additional property ‘Signature’.

JSON property Description
Signature Base64-encoded signature of ‘Base64EncodedHash’. Format and length depend on the key of the signing policy’s certificate.

Example

Request:

curl -H "Authorization: Bearer $API_TOKEN" \
     -F "ProjectSlug=$PROJECT" \
     -F "SigningPolicySlug=test-signing" \
     -F "IsFastSigningRequest=true" \
     -F "Artifact=@$PATH_TO_ARTIFACT" 
     https://app.signpath.io/API/v1/$ORGANIZATION_ID/SigningRequests

Request artifact:

{
    "SignatureAlgorithm": "RsaPkcs1",
    "RsaHashAlgorithm": "2.16.840.1.101.3.4.2.1",
    "Base64EncodedHash": "GJShnIW6FTrL90OsTkP8AEyJFgSyb4xp4eg+oq/HxI8=",
    "Metadata":
    {
        "CreatingProcess": { "CommandLine": "SampleCommand -SampleArgument", "User": "SampleUser" }
    }
}

Response:

{
    "SignatureAlgorithm": "RsaPkcs1",
    "RsaHashAlgorithm": "2.16.840.1.101.3.4.2.1",
    "Base64EncodedHash": "GJShnIW6FTrL90OsTkP8AEyJFgSyb4xp4eg+oq/HxI8=",
    "Metadata": { ... },
    "Signature": "wGI2oiHHVSVGHR1rtjv83Pir1SEVLmnLNGuJD4..."
}

Retrieve Signing Policy details

Use GET https://app.signpath.io/api/v1/$OrganizationId/Cryptoki/MySigningPolicies?projectSlug=$Project&signingPolicySlug=$SigningPolicy to get information about the signing plicy, including the X.509 certificate and RSA key parameters.

(If project and signing policy are not specified, this API returns all signing policies where user identified by the API token is assigned as Submitter.)

Example response:

{
    "signingPolicies": [
        {
            "signingPolicySlug": "test-signing",
            "projectSlug": "hash-signing-test",
            "keySizeInBits": 2048,
            "rsaParameters": {
                "publicExponent": "AQAB",
                "modulus": "2e4JTm..."
            },
            "signingPolicyId": "eacd4b78-6038-4450-9eec-4acd1c7ba6f1",
            "certificateBytes": "MIIC5zCC...",
            "keyType": "Rsa",
            "publicKeyBytes": "MIIBCgKC..."
        }
    ]
}

Sign up for news and special offers