POST Codesign/RetrieveArchiveEntries

Returns data about code signing operations. This API is useful for administrators or auditors who need detailed information about the use of signing keys.

NOTE  For new enterprise customers, the signing archive is disabled by default on installation. For steps to enable it, see Signing archive options.

Requirements

  • Permissions: The caller must be a Code Signing Administrator, Code Signing Auditor, Trust Protection Platform Auditor, or Trust Protection Platform Master Admin.

    NOTE  Code Signing Auditors will see results only from the Code Singing Projects where they are identified as an auditor.

  • Token scope:  Codesign:Manage

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

All parameters are optional.

Input parameters

Name

Description

ArchiveFilter

The following keys can be passed in the ArchiveFilter object. Results must match all of the values passed. See the example section below for complete syntax.

The percent character % can be used as a wildcard in any string. It must be added at the beginning and end of the filtering string (for partial match), for example "ApplicationHash": "AD63AF5%".

Key name Description and request example
ApplicationHash

String

The hash of the application used to sign.

Request example: "ApplicationHash": "AD63AF5%"

ArchiveId

Integer

Table number for the archive. Passing this value will return a specific event.

Request example: "ArchiveId": 285800"

Artifact

String

The hash or token of the binary. This hash is what was signed during the code signing operation.

Request example: "Artifact": "MDEwDQY%"

AuthenticatedUserName

String

The user ID of the user that signed.

Request example: "AuthenticatedUserName": "sample-cs-user"

AuthenticatedUser

String

The prefixed universal UUID of the user that signed. Use POST Identity/Browse to look up the prefixed universal for an identity.

Request example: "AuthenticatedUser": "local:{9a06d381-0a9e-4ec7-92ce-e0d40abc71c4}"

ClientInterface

Integer

The signing client interface used to sign. The following integers are valid:

  • 0: Unknown interface

  • 1: PKCS11Config Interface

  • 2: CSPConfig Interface

  • 3: GPGConfig Interface

  • 4: TKDriverConfig Interface

  • 5: VenaifiSCD Interface

  • 6: Venafi Code Signing Token Driver Interface

Request example: "ClientInterface": 1

ClientLibraryName

String

The client library used to sign.

Request example: "ClientLibraryName": "pkcs11"

ClientLibraryVersion

String

The version of the library used to sign.

Request example: "ClientLibraryVersion": "22.2.3 (Crypto Library: mbed TLS 2.27.0)"

ClientMechanism

Integer

The mechanism used before hashing the data to send for signing.

Request example: "ClientMechanism": 64

Command

String

The command that was used to sign, if the command was sent during signing.

Request example: "Command": "/opt/venafi/codesign/bin/pkcs11config sign -file /tmp/test.out -label White-List-PKCS11-Allowed -output /tmp/test.sig"

EnvironmentDNs

Array of strings

List of DNs for multiple Code Signing Environments.

Request example:

"EnvironmentDNs": [
  "\\VED\\Code Signing\\Projects\\White List\\PKCS11 Allowed",
  "\\VED\\Code Signing\\Projects\\Testing\\ECCP256"
]
EnvironmentDN

String

DN of the Code Signing Environment.

Request example: "EnvironmentDN": "\\VED\\Code Signing\\Projects\\White List\\PKCS11 Allowed"

EventTypeId

Integer

Log event ID in hex format.

Request example: "EventId": 1610743809

EventType

String

The type of the event in the signing archive.

Request example: "EventType":"SigningSuccessful"

ExecutableLocation

Srting

File system location of the executable used to sign.

Request example: "ExecutableLocation": "/usr/local/bin/pkcs11config"

Executable

String

Name of the executable that was used to sign.

Request example: "Executable": "pkcs11config"

FlowDN

String

DN of the Flow used.

Request example: "FlowDN": "\\VED\\Code Signing\\Flows\\No Restrictions"

Grouping

Integer

A numerical representation of the thumbprint of the Request Identifier Fields used on the signing request.

A value of 0 will be shown if the process didn't complete its Flow or failed another constraint gate (such as IP address restrictions or time constraints).

Request example: "Grouping": 565083052

IPAddress

String

IP address of the system used to sign.

Request example: "IPAddress": "172.17.24.80"

KeyType

String

Key type used to sign.

Request example: "KeyType": "ECDSA P256"

KeyVaultId

Integer

SecretStore Vault ID of the signing private key.

Request example: "KeyVaultId": 91275

Machine

String

Name of the system used to sign.

Request example: "Machine": "cs-macos11-int1.local"

Mechanism

Integer

The Mechanism ID that represents the encryption algorithm for the signing operation.

Request example: "Mechanism": 1

ProjectDNs

Array of strings

List of DNs for multiple Code Signing Projects.

Request example:

"ProjectDNs": [
  "\\VED\\Code Signing\\Projects\\White List",
  "\\VED\\Code Signing\\Projects\\Testing"
]
ProjectDN

String

DN of the Code Signing Project.

Request example: "ProjectDN": "\\VED\\Code Signing\\Projects\\White List"

RemoteAccount

String

(missing or bad snippet)

Request example: "RemoteAccount": "jenkins"

TimestampAfter

String

All entries with a timestamp prior to the provided timestamp will be excluded from the response.

Request example: "TimestampAfter": "2022-11-18T22:44:12Z"

TimestampBefore

String

All entries with a timestamp earlier than the provided timestamp will be excluded from the response.

Request example: "TimestampBefore": "2022-11-20T23:59:59Z"

PageSize

Integer specifying the number of results to be included in each page of the response. Default is 50.

Page

The page to return. Default is 1.

Returns

For valid requests, RetrieveArchiveEntries returns a HTTP 200 message and the following data in the message body:

Response description

Name

Description

HTTP 200

 

For valid requests, this call returns a HTTP 200 message and the following data in the message body:

  • ArchiveResults: The ArchiveResults object includes the details of the code signing operations returned.

    • ApplicationHash: The hash of the application used to sign.

    • ArchiveEntryId: The ID of the record. Each record is ordered sequentially.

    • Artifact: The hash or token that was signed.

    • AuthenticatedUser: The prefixed universal of the key user's identity.

    • AuthenticatedUserName: The username of the key user.

    • ClientInterface: An integer representing the interface used to sign.

      • 0: Unknown interface

      • 1: PKCS11Config Interface

      • 2: CSPConfig Interface

      • 3: GPGConfig Interface

      • 4: TKDriverConfig Interface

      • 5: VenaifiSCD Interface

      • 6: Venafi Code Signing Token Driver Interface

    • ClientLibraryLocation: The file system location of the client library on the signing machine.

    • ClientLibraryName: The name of the library used to sign.

    • ClientLibraryVersion: The version number of the client library.

    • ClientMechanism: The mechanism used before hashing the data to send for signing.

    • Command: The command that was used to sign.

    • Environment: The DN of the Code Signing Environment.

    • EventType: The result of the event archive entry

    • EventTypeId: Log event ID in hexadecimal format.

    • Executable: The executable used to sign.

    • ExecutableLocation: The file system location of the executable on the signing machine.

    • Flow: The DN of the Code Signing Flow.

    • Grouping: A numerical representation of the thumbprint of the Request Identifier Fields used on the signing request. A value of 0 will be shown if the process didn't complete its Flow or failed another constraint gate (such as IP address restrictions or time constraints).

    • IPAddress: The IP address of the machine where the code signing operation took place.

    • KeyType: The key type that was used to sign.

    • KeyVaultId: SecretStore Vault ID of the signing private key.

    • Machine: The name of the machine where the code signing operation took place.

    • Mechanism: The Mechanism ID that represents the encryption algorithm for signing the software.

    • Project: The DN of the Code Signing Project.

    • RemoteAccount: Account of the user executing the signing command on the signing workstation.

    • Timestamp: The time and date when the signing operation took place.

  • PageNumber: The page number of the results. The number of results per page is specified by the PageSize parameter.

  • TotalCount: Total count of returned signing operations

  • Error: Appears only when Success is false. An error message that accompanies the Result. Check your payload input values.

HTTP 400

For invalid requests, this call returns HTTP 400 Bad Request and the following data in the message body:

  • error: The reason for the error.
  • error_description: If available, additional information about how to retry the request.

Examples

Request code signing operations performed between November 18, 2022 and November 19, 2022

POST /vedsdk/Codesign/RetrieveArchiveEntries HTTP/1.1
Host: tpp.server.url
Authorization: Bearer 4MyGeneratedBearerTknz==
Content-Type: application/json

{
  "ArchiveFilter": {
    "TimestampAfter": "2022-11-18T00:00:00Z",
    "TimestampBefore": "2022-11-19T23:59:59Z"
  }
}

Request code signing operations performed by a specific user, from a specific IP address, using an RSA 2048 key

POST /vedsdk/Codesign/RetrieveArchiveEntries HTTP/1.1
Host: tpp.server.url
Authorization: Bearer 4MyGeneratedBearerTknz==
Content-Type: application/json

{
  "ArchiveFilter": {
    "AuthenticatedUser": "local:{80904436-ded7-4602-9c6f-2e1502d2b6b2}",
    "IPAddress": "172.17.24.80",
    "KeyType": "RSA 2048"
  }
}

Request code signing operations performed by the pkcs11 library. Return 5 results per page, and return page 10.

POST /vedsdk/Codesign/RetrieveArchiveEntries HTTP/1.1
Host: tpp.server.url
Authorization: Bearer 4MyGeneratedBearerTknz==
Content-Type: application/json

{
  "ArchiveFilter": {
    "ClientLibraryName": "pkcs11"
  },
  "PageSize": 5,
  "Page": 10
}

Response

HTTP/1.1 200 
{
  "ArchiveResults": [
    {
      "ApplicationHash": "FB437BD1CD52E22BBC5BE8738E8DC79D4C2289DE05EAE9354B46C8C95685BC76",
      "ArchiveEntryId": 281672,
      "Artifact": "MDEwDQYJYIZIAWUDBAIBBQAEIBxGcqTGcTvLlJWrunEr4lG77/cj158AH4HlFwsdFiel",
      "AuthenticatedUser": "local:{80904436-ded7-4602-9c6f-2e1502d2b6b2}",
      "ClientLibraryLocation": "",
      "ClientLibraryName": "pkcs11",
      "ClientLibraryVersion": "22.2.3 (Crypto Library: mbed TLS 2.27.0)",
      "ClientMechanism": 64,
      "Command": "",
      "Environment": "\\VED\\Code Signing\\Projects\\White List\\PKCS11 Allowed",
      "EventId": 1610743809,
      "Executable": "pkcs11config",
      "ExecutableLocation": "/usr/local/bin/pkcs11config",
      "Flow": "\\VED\\Code Signing\\Flows\\No Restrictions",
      "Grouping": 1553877821,
      "IPAddress": "172.17.24.80",
      "KeyType": "RSA 2048",
      "KeyVaultId": 91232,
      "Machine": "cs-macos11-int1.local",
      "Mechanism": 1,
      "Platform": "",
      "Project": "\\VED\\Code Signing\\Projects\\White List",
      "RemoteAccount": "jenkins",
      "Timestamp": "2022-11-28T22:44:18Z"
    }
  ],
  "PageNumber": 1,
  "Success": true,
  "TotalCount": 134154
}