> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cryptography API

> Analyse cryptographic algorithms, usage hints and version coverage for software components.

## ComponentAlgorithms

Retrieves cryptographic algorithms detected in a single software component.

### HTTP Request Example

```bash theme={null}
# Get cryptographic algorithms for a component
curl -X GET 'https://api.scanoss.com/v2/cryptography/algorithms/component?purl=pkg:github/scanoss/engine&requirement=>=5.0.0' \
  -H "X-Api-Key: $SCANOSS_API_KEY" | jq
```

### Response Examples

#### Successful Response

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "version": "5.0.0",
    "requirement": ">=5.0.0",
    "algorithms": [
      {
        "algorithm": "AES",
        "strength": "Strong"
      },
      {
        "algorithm": "RSA",
        "strength": "Strong"
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms Successfully retrieved"
  }
}
```

#### Error Response — Component Not Found

```json theme={null}
{
  "component": {
    "purl": "pkg:github/unknown/component",
    "version": "",
    "requirement": ">=1.0.0",
    "algorithms": [],
    "error_message": "Component not found in database",
    "error_code": "COMPONENT_NOT_FOUND"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Request processed"
  }
}
```

#### Error Response — Invalid PURL

```json theme={null}
{
  "component": {
    "purl": "invalid-purl-format",
    "version": "",
    "requirement": ">=1.0.0",
    "algorithms": [],
    "error_message": "Invalid PURL format provided",
    "error_code": "INVALID_PURL"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Request processed"
  }
}
```

### Error Handling

Component responses include optional error fields when issues occur during processing:

* `error_message`: Human-readable description of the error
* `error_code`: Machine-readable error code for programmatic handling

#### Error Codes

| Code                  | Description                                                 |
| --------------------- | ----------------------------------------------------------- |
| `INVALID_PURL`        | The provided PURL format is invalid                         |
| `COMPONENT_NOT_FOUND` | The component was not found in the database                 |
| `NO_INFO`             | No cryptographic information is available for the component |
| `INVALID_SEMVER`      | The provided version requirement is invalid                 |

> When a component-level error occurs, the overall response `status` remains `"SUCCESS"` because the request itself was processed successfully. Component-level errors are indicated within the individual component object.

## ComponentsAlgorithms

Retrieves cryptographic algorithms detected across multiple software components in a single request.

### HTTP Request Example

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/cryptography/algorithms/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=5.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq
```

### Response Examples

#### Successful Response

```json theme={null}
{
  "components": [
    {
      "purl": "pkg:github/scanoss/engine",
      "requirement": ">=5.0.0",
      "version": "5.0.0",
      "algorithms": [
        {
          "algorithm": "AES",
          "strength": "Strong"
        },
        {
          "algorithm": "RSA",
          "strength": "Strong"
        }
      ]
    },
    {
      "purl": "pkg:github/scanoss/scanoss.py",
      "requirement": "~1.30.0",
      "version": "v1.30.0",
      "algorithms": [
        {
          "algorithm": "SHA-256",
          "strength": "Strong"
        }
      ]
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms Successfully retrieved"
  }
}
```

#### Mixed Response with Error

```json theme={null}
{
  "components": [
    {
      "purl": "pkg:github/scanoss/engine",
      "requirement": ">=5.0.0",
      "version": "5.0.0",
      "algorithms": [
        {
          "algorithm": "AES",
          "strength": "Strong"
        }
      ]
    },
    {
      "purl": "pkg:github/unknown/component",
      "requirement": ">=1.0.0",
      "version": "",
      "algorithms": [],
      "error_message": "Component not found in database",
      "error_code": "COMPONENT_NOT_FOUND"
    }
  ],
  "status": {
    "status": "SUCCESS",
    "message": "Batch request processed"
  }
}
```

## ComponentAlgorithmsInRange

Analyses a single software component across a specified version range and returns all cryptographic algorithms detected, along with the versions in which each algorithm appears. Use this endpoint to audit cryptographic changes across a component's release history.

### HTTP Request Example

```bash theme={null}
curl -X GET 'https://api.scanoss.com/v2/cryptography/algorithms/range/component?purl=pkg:github/scanoss/engine&requirement=>=1.0.0' \
  -H "X-Api-Key: $SC_API_KEY" | jq
```

### Response Format

The response contains the following fields:

* `component`: Contains the component analysis results
  * `purl`: The PURL of the requested component
  * `versions`: Component versions in which at least one cryptographic algorithm was detected
  * `algorithms`: All cryptographic algorithms found across the specified version range
* `status`: Response status indicating success or failure

Each algorithm object contains:

* Algorithm name and strength classification
* Detection metadata and analysis results

### Response Example

#### Component with Algorithms Across Versions

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "versions": ["1.0.0", "2.0.0", "3.0.0", "5.0.0"],
    "algorithms": [
      {
        "algorithm": "AES",
        "strength": "Strong"
      },
      {
        "algorithm": "RSA",
        "strength": "Strong"
      },
      {
        "algorithm": "MD5",
        "strength": "Weak"
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms in range Successfully retrieved"
  }
}
```

#### Component with No Cryptographic Algorithms

```json theme={null}
{
  "component": {
    "purl": "pkg:github/example/simple-utility",
    "versions": [],
    "algorithms": [],
    "error_message": "Component not found: 'pkg:github/example/simple-utility'",
    "error_code": "COMPONENT_NOT_FOUND"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Algorithms in range Successfully retrieved"
  }
}
```

## ComponentsAlgorithmsInRange

Analyses multiple software components across specified version ranges and returns cryptographic algorithms for each in a single request.

### HTTP Request Example

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/cryptography/algorithms/range/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=1.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq
```

## ComponentVersionsInRange

Analyses a single software component and returns two lists: versions that contain cryptographic algorithms, and versions that do not. Use this endpoint to determine at which point in a component's release history cryptographic functionality was introduced or removed.

### HTTP Request Example

```bash theme={null}
curl -X GET 'https://api.scanoss.com/v2/cryptography/algorithms/versions/range/component?purl=pkg:github/scanoss/engine&requirement=>=1.0.0' \
  -H "X-Api-Key: $SC_API_KEY" | jq
```

### Response Example

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "versions_with": ["2.0.0", "3.0.0", "4.0.0", "5.0.0"],
    "versions_without": ["1.0.0", "1.5.0"]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Version ranges Successfully retrieved"
  }
}
```

## ComponentsVersionsInRange

Batch version of ComponentVersionsInRange - analyzes multiple components and returns version lists based on cryptographic algorithm presence for each component.

### HTTP Request Example

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/cryptography/algorithms/version/range/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=1.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq
```

## ComponentHintsInRange

Retrieves cryptographic hints for a component, including detected protocols, libraries, SDKs and frameworks.

### HTTP Request Example

```bash theme={null}
curl -X GET 'https://api.scanoss.com/v2/cryptography/hints/component?purl=pkg:github/scanoss/engine&requirement=>=5.0.0' \
  -H "X-Api-Key: $SC_API_KEY" | jq
```

### Response Format

The response contains the following fields:

* `component`: Contains the component analysis results
  * `purl`: The PURL of the requested component
  * `hints`: Cryptographic hints detected in the component
  * `version`: The specific version analysed
* `status`: Response status indicating success or failure

Each hint object contains:

* Unique identifier for the hint
* Name of the cryptographic entity detected
* Description of the detected usage or implementation
* Classification of the hint (see categories below)
* Reference URL for further information
* PURL of the detected entity

#### Hint Categories

Hints are classified into the following categories:

| Category    | Description                                               |
| ----------- | --------------------------------------------------------- |
| `protocol`  | Cryptographic protocols (e.g. TLS, SSH, HTTPS)            |
| `library`   | Cryptographic libraries (e.g. OpenSSL, Bouncy Castle)     |
| `sdk`       | Software development kits with cryptographic capabilities |
| `framework` | Frameworks that include cryptographic functionality       |

### Response Examples

#### Component with Cryptographic Hints

```json theme={null}
{
  "component": {
    "purl": "pkg:github/scanoss/engine",
    "version": "5.0.0",
    "hints": [
      {
        "id": "openssl-hint-001",
        "name": "OpenSSL",
        "description": "Industry standard cryptographic library providing SSL/TLS protocols",
        "category": "library",
        "url": "https://www.openssl.org/",
        "purl": "pkg:generic/openssl@3.0.0"
      },
      {
        "id": "tls-protocol-001",
        "name": "TLS 1.3",
        "description": "Transport Layer Security protocol implementation",
        "category": "protocol",
        "url": "https://tools.ietf.org/html/rfc8446",
        "purl": ""
      }
    ]
  },
  "status": {
    "status": "SUCCESS",
    "message": "Cryptographic hints Successfully retrieved"
  }
}
```

#### Component with No Cryptographic Hints

```json theme={null}
{
  "component": {
    "purl": "pkg:github/example/simple-utility",
    "version": "1.0.0",
    "hints": [],
    "error_message": "No info found for: pkg:github/example/simple-utility",
    "error_code": "NO_INFO"
  },
  "status": {
    "status": "SUCCESS",
    "message": "Cryptographic hints Successfully retrieved"
  }
}
```

## ComponentsHintsInRange

Retrieves cryptographic hints for multiple components in a single request, returning the cryptographic protocols, libraries, SDKs and frameworks detected across all specified components.

### HTTP Request Example

```bash theme={null}
curl -X POST 'https://api.scanoss.com/v2/cryptography/hints/components' \
  -H 'Content-Type: application/json' \
  -H "X-Api-Key: $SC_API_KEY" \
  -d '{
    "components": [
      {"purl": "pkg:github/scanoss/engine", "requirement": ">=5.0.0"},
      {"purl": "pkg:github/scanoss/scanoss.py", "requirement": "~1.30.0"}
    ]
  }' | jq
```

## DownloadRuleset

Download cryptography detection rulesets as compressed `.tar.gz` archives. Rulesets are used to identify cryptographic algorithms across multiple programming languages and are compatible with tools such as Semgrep and OpenGrep.

### Ruleset Types

* **dca**: Deep Code Analysis rules for semantic detection using SCANOSS Crypto Finder
* **keywords**: eyword-based rules for pattern matching

### Version Specification

* **latest**: Most recent ruleset release
* **versioned**: Specific release (e.g., `v1.2.3`)

### HTTP Request Examples

```bash theme={null}
# Get DCA ruleset (latest version)
curl -X GET 'https://api.scanoss.com/v2/cryptography/rulesets/dca/latest/download' \
  -H "X-Api-Key: $SC_API_KEY"

# Get Keywords ruleset (specific version)
curl -X GET 'https://api.scanoss.com/v2/cryptography/rulesets/keywords/v1.2.3/download' \
  -H "X-Api-Key: $SC_API_KEY"
```

### Response Format

The API returns a binary `.tar.gz` file. Metadata is included in HTTP response headers.

#### Example Headers

```bash theme={null}
HTTP/1.1 200 OK
Content-Type: application/gzip
Content-Disposition: attachment; filename="scanoss-crypto-dca-v1.2.3.tar.gz"
X-Ruleset-Name: dca
X-Ruleset-Version: v1.2.3
X-Checksum-SHA256: a3f5d8b9e2c7f1a4b6d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

<binary tarball content>
```

#### Download & Extract

```bash theme={null}
# Download directly to file
curl -X GET 'https://api.scanoss.com/v2/cryptography/rulesets/dca/latest/download' \
  -H "X-Api-Key: $SC_API_KEY" \
  -o scanoss-crypto-dca-latest.tar.gz

# Extract immediately
tar -xzf scanoss-crypto-dca-latest.tar.gz
```

#### Inspect Headers

```bash theme={null}
# Download and capture headers
curl -X GET 'https://api.scanoss.com/v2/cryptography/rulesets/dca/latest/download' \
  -H "X-Api-Key: $SC_API_KEY" \
  -D headers.txt \
  -o scanoss-crypto-dca-latest.tar.gz

# View metadata from headers
cat headers.txt
```

#### Tarball Structure

```bash theme={null}
dca-v1.2.3/
├── java/                  # Java cryptography detection rules
│   ├── jca.yaml
│   ├── bouncycastle.yaml
│   └── ...
├── python/                # Python cryptography detection rules
│   ├── cryptography.yaml
│   ├── pycrypto.yaml
│   └── ...
├── go/                    # Go cryptography detection rules
│   └── ...
└── manifest.json          # Ruleset metadata and checksums
```

#### Manifest

Each ruleset includes a `manifest.json` file containing metadata:

```bash theme={null}
{
  "name": "dca",
  "version": "v1.2.3",
  "description": "Standard cryptography detection rules (to be used with SCANOSS Crypto Finder)",
  "created_at": "2025-11-10T10:00:00Z",
  "checksum_sha256": "abc123..."
}
```