POST Flow/Actions/CodeSign/PreQualify/Create

Pre-qualifies and adds a hash to a VCC Flow that already has a Pre-Qualified Signature action. However, the hash is hidden in VCC and CodeSign Protect.

Hash data ensures the identity of a specific assembly or executable. Later, during code signing, if the software hash does not match the pre-qualified hash, code signing fails.

You can add as many hashes as necessary to a project environment Flow. However, you must call PreQualify/Create to preauthorize each hash so it is available for future code signing.

BEST PRACTICE Applying a pre-qualified hash during code signing is also known as High Assurance Signing. Be sure to follow your company's Secure Development Practices.

Prerequisites

Use a tool, such as a malware scanner or SignTool, to get the hash Data of the software assembly or executable. For example:

signtool.exe sign /dg c:\temp\scratch /v /fd sha256 /n "Sample", "c:\temp\tosign\*.dll"
In a VCC environment template, configure a Key Use Flow that contains a Pre-Qualified Signature action. Before calling Prequalify/Create, make sure the template is assigned to a project environment. For more information, see the CodeSign Protect Guide.

Requirements

Permissions: The caller, who pre-authorizes the hash, must be a Key Use Approver.
Token scope: Codesign:Approve

Headers

Content type: Content-Type:application/json.
Token: The bearer access token that you received. For example, Authorization:Bearer 4MyGeneratedBearerTknz==. For more information, see Passing a bearer token in your API calls.

Parameters

Input parameters
Name	Description
Comment	The comments that the approver added. For example, the reason for hash pre-authorization.
Data	The Base64 encoding of a hash, digest, or data that will match the signing tool hash (at the time of code signing).
Dn	The Distinguished Name (DN) of the environment.
Hours	(Optional) The number of hours the pre-qualified signature is valid. If absent, the pre-qualified signature expires 24 hours after this API call occurs.
SingleUse	(Optional) The number of allowed signings for this hash: False: Unlimited until Hours expires. True: Sign once.
User	The project Key User who will make the signing request: A PrefixedName. For example, User: local:sample-cs-user. -OR- A PrefixedUniversal of a person, not a group. To get the value, call POST Identity/Browse. For example, User: local:{064cbe34-b46e-48c9-b65b-ea8dcda167d4}.

Returns

Response description
Name	Description
Error	Appears only when Success is false. An error message that accompanies the Result. Check your payload input values.
Result	The Result code of this API call. For more information, see Sign Result Codes.
Success	The result of this API call: A value of false indicates the request failed due to an Error. Otherwise, true.

Example: Pre-authorize a hash; store it to use for only one code signing

Request

POST https://tpp.venafi.example/vedsdk/Flow/Actions/CodeSign/PreQualify/Create
Authorization:Bearer 4MyGeneratedBearerTknz==
{
   "Dn":"\\VED\\Code Signing\\Projects\\Sample\\Production Environment",
   "User":"local:sample-cs-user",
   "SingleUse":true,
   "Comment":"File pre-authorized on 03/09/2021 19:23:19",
   "Data":"ew5Usp8f31jhUSQyyWNHZh8BKOrep7bIPg7VCtNJdLU="
}

Response

HTTP/1.1 200 OK
{
   "Result":1,
   "Success":true
}