POST API/Sign

Requests that data be digitally signed. During signing, CodeSign Protect uses a private key from a project's environment to sign the data (provided as base64) and return raw signature. If the signing operation is blocked by a Flow that requires key use approval, a digest is returned that uniquely identifies the signing request.

Requirements

Setup: See Setting up your HSM Client application and Install CodeSign Protect Clients on signing workstations.
Permissions: The caller must be a Key User.
Token scope: codesignclient

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

For details, see the LibHSM documentation on your signing workstation:

Linux: file:///opt/venafi/codesign/html/index.html
macOS: file:///Library/Venafi/CodeSigning/html/index.html
Windows: file:///C:/Program Files/Venafi CodeSign Protect/SDK/html/index.html

Input parameters
Name	Description
ClientInfo	The ClientInfo object that manages code signing.
ClientMechanism	(Optional) Use only when the server requires a different Mechanism. For example, when signing and hashing on the client side, set this field to describe the actual mechanism for a full operation (when signing this would include the digest).
Data	The Base-64 bit encoding of the data to sign.
Justification	(Optional) The reason for the request.
KeyContext	The purpose of the key: null authentication encryption signing
KeyContextToWrap	(Optional) If the environment contains multiple keys, the KeyId of the private key.
KeyId	The GUID that uniquely identifies a CodeSign Protect environment. The Key ID allows you to digitally sign Data. To get the value, use the Guid from the POST Codesign/GetEnvironment response.
Mechanism	The Mechanism ID that represents the encryption algorithm for signing the software. For Rsa Pkcs, specify 1. To get additional values, use the LibHSM documentation on your signing workstation. See md_Documentation_RESTCrypto.html.
Parameter	(Optional) Additional settings for Initialization Vector (IV), Optimal Asymmetric Encryption Padding (OAEP), and PKCS-PSS: HashAlg: Specify the CKM value. IV: If ParameterType is IV, the initialization vector in Base64 encoding. MGF: For OAEP and PKCSPSS, the mask generation function. ParameterType: Specify IV initialization vector, OAEP Optimal Asymmetric Encryption Padding, or PKCSPSS PKCS-PSS formatting. SaltLen: For PKCSPSS, the salt length, in bytes. Source: If OAEP and SourceData is provided, specify 1. Otherwise 0. SourceData: If you specify OAEP and Source is 1, include the executable as Base64 encoded.
Password	(Optional) The password that corresponds to Username.
ProcessInfo	The ProcessInfo object that describes how to sign.
Username	(Optional) The Key User.
VerifyData	(Optional) For operations that verify data.
WrappingKeyId	(Optional) The private key ID to wrap.

Returns

Response description
Name	Description
HTTP 200	For valid requests, this call returns a HTTP 200 message and the following data in the message body: Success: true if the operation was successful, false otherwise. Error: Appears only when there is an error. Possible reasons include: Missing or invalid KeyID Signing requires pre-authorization Locked template parameters block signing Private key prevents usage of a particular signing tool TryLater: true if the operation was not performed due to a flow condition that requires approval. RequestThumbprint: Displays the Flow Process Instance Identification digest, in case the operation is blocked by a Flow that requires approval. The approval request fingerprint is a digest of the parameters defined as instance identifiers. This digest is also displayed on the request approval screen. ResultData: The base64 of raw signature. Appears only if Success is true.

Example 1: Sign a request that doesn't require approval

Request for example 1

POST https://test.venafi.example/vedhsm/API/Sign/
Authorization:Bearer 4MyGeneratedBearerTknz==

{
   "ClientInfo":{
      "ClientLibraryName":"MyHSMClient",
      "ClientLibraryVersion":"1.0.4"
   },
   "ProcessInfo":{
      "Username":"Admin",
      "Machine":"192.168.0.130",
      "Executable":"C:\\temp\\MySigntool.exe",
      "CommandLine":"\"C:\\temp\\MySignTool.exe\"  sign /n \"Sample \" c:\\temp\\Mysoftware.exe",
      "ExecutableSize":2859520,
      "ExecutableHash":"8176CDBE..."
   },
   "KeyId":"{8f31e7a8-ec8e-42bc-b6aa-4d1d74315e96}",
   "Mechanism":1,
   "Data":"MDEwDQYJ..."
}

Response when no approval is required

HTTP/1.1 200 OK
{
   "ResultData": "niIT+q+sFigJDv/qlfzuy...",
   "Success": true
}

Response when pre-approval is required in the UI

HTTP/1.1 200 OK
{
   "Error": "Private Key Access: Your request was submitted for approval. Please wait for approval confirmation and retry.",
   "RequestThumbprint": "6F6B304E72EA451557BADDBD6F5EB40B8F858EAD42B62A18253C165071C634A8",
   "TryLater": true
}