REST API | SignPath

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..."
        }
    ]
}

Documentation ❯ Crypto Providers ❯ REST API