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

# Configurazione della coppia di chiavi ES256

> Generare, verificare, proteggere, registrare e sostituire la coppia di chiavi ES256 utilizzata per l’accesso macchina-macchina all’API di Credit Benchmark.

Si ritroverà con due file:

* `es256-private.pem`: conservi questa chiave sul computer che effettua le chiamate alla nostra API. Non la condivida mai tramite e-mail, chat, ticket o repository di codice.
* `es256-public.pem`: inviateci questo per l’onboarding.

## Prima di iniziare

È necessario **OpenSSL 3.0 o versione successiva**. Verifichi con:

```bash theme={null}
openssl version
```

* **Windows:** installatelo tramite winget, Chocolatey o Git per Windows.
* **macOS:** la versione integrata potrebbe essere LibreSSL. Eseguire `brew install openssl` se l’output non riporta OpenSSL 3 o versioni successive.

Se il Suo terminale segnala che `openssl` qualora il comando non venga riconosciuto, installi il pacchetto e apra una nuova finestra del terminale.

> [!NOTE]
>
> Generare le chiavi sull’endpoint che effettuerà le chiamate alla nostra API, sia esso un server o un laptop, in modo che la chiave privata non debba mai essere copiata altrove.

## Passaggio 1: Generare le chiavi

Esegua questi comandi in PowerShell, Prompt dei comandi, bash o zsh. Il primo crea la chiave privata (EC P-256, formato PKCS#8). Il secondo ricava la chiave pubblica corrispondente.

```bash theme={null}
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -pkeyopt ec_param_enc:named_curve -out es256-private.pem
openssl pkey -in es256-private.pem -pubout -out es256-public.pem
```

## Fase 2: Verifica delle chiavi

Esegua questi comandi prima di inviare qualsiasi cosa.

```bash theme={null}
openssl pkey -in es256-private.pem -check -noout
openssl pkey -pubin -in es256-public.pem -text -noout
```

Verifichi che:

* Il primo comando visualizza `Key is valid`.
* Il secondo mostra `ASN1 OID: prime256v1` e `NIST CURVE: P-256`.
* `es256-private.pem` inizia con `-----BEGIN PRIVATE KEY-----`.
* `es256-public.pem` inizia con `-----BEGIN PUBLIC KEY-----`.

Se la chiave privata inizia con `BEGIN EC PRIVATE KEY`, convertitela in PKCS#8:

```bash theme={null}
openssl pkcs8 -topk8 -nocrypt -in old-key.pem -out es256-private.pem
```

## Fase 3: Proteggere la chiave privata

> [!WARNING]
>
> Chiunque disponga di `es256-private.pem` chiunque ne sia in possesso può richiedere token a nome della vostra organizzazione. Trattatela come una password di produzione.

Limiti l’accesso all’account che gestisce la Sua integrazione:

```bash Linux or macOS theme={null}
chmod 600 es256-private.pem
```

```powershell Windows PowerShell theme={null}
icacls es256-private.pem /inheritance:r /grant:r "$($env:USERNAME):R"
```

* In ambiente di produzione, conservi la chiave privata in un gestore di segreti come Azure Key Vault, AWS Secrets Manager o HashiCorp Vault.
* Non inviatela mai via e-mail, non allegatela a un ticket, non incollatela in una chat né la inserite in un repository. Se effettuate dei test con Postman, conservatela nel Postman Vault o solo come valore corrente.
* Se ritiene che vi sia stata una fuga di informazioni, ci informi immediatamente.

## Fase 4: Inviare la chiave pubblica

Invii esclusivamente `es256-public.pem` al Suo referente di Credit Benchmark. Includa:

* Nome della Sua organizzazione
* L’ambiente (Sandbox o Produzione)
* Un referente tecnico
* Gli ambiti di cui ha bisogno
* L’impronta digitale della chiave

Utilizziamo l’impronta digitale per confermare che la chiave non sia stata alterata durante il trasferimento. La calcoli utilizzando:

```bash theme={null}
openssl pkey -pubin -in es256-public.pem -outform DER -out es256-public.der
openssl dgst -sha256 es256-public.der
```

Utilizzi una coppia di chiavi separata per ciascun ambiente. Prima di inviare, verifichi che l’allegato sia `es256-public.pem` e che non sia allegato alcun file di chiave privata. Potremmo contattare il Suo referente tecnico per fargli ripetere l’impronta digitale prima di attivare la chiave.

Una volta registrata la chiave, Le invieremo il Suo pacchetto di onboarding. Consulti [ciò che riceverà in risposta](/api-reference/authentication/overview#what-you-receive-back).

## Rotazione delle chiavi

Sostituisca la coppia di chiavi almeno ogni 12 mesi, oppure immediatamente qualora la chiave privata possa essere stata compromessa.

**1. Generare una nuova coppia**

Ripetete i passaggi 1 e 2 utilizzando nuovi nomi di file, ad esempio `es256-private-2027.pem`.

**2. Invii la nuova chiave pubblica.**

Invii la richiesta come indicato nel Passo 4, indicando nell’oggetto `M2M API key rotation - [Your organisation name] - [Environment]` e la Sua chiave attuale `OAuthClientId`.

**3. Riceva un nuovo KID**

Le risponderemo con una nuova `KID`. La sua `OAuthClientId` non subisce alcuna modifica.

**4. Completare la transizione**

Passare l'integrazione alla nuova chiave privata e `KID`, quindi ci informi. Provvederemo a revocare la vecchia `KID` e Lei provvederà a eliminare in modo sicuro la vecchia chiave privata.

> [!WARNING]
>
> In caso di sospetta compromissione, eviti la fase di sovrapposizione e ci chieda di revocare immediatamente la vecchia chiave.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.