Richiedere un nuovo account

I nuovi account in una rete Universal Ledger devono essere creati da un account principale già presente nel ledger. Questo account genitore deve firmare e inviare una transazione per creare il nuovo account.

Questa guida descrive come richiedere un nuovo account in una rete Universal Ledger. Scopri come:

  • Crea chiavi di firma asimmetriche per il nuovo account utilizzando Cloud Key Management Service.

  • Identifica il proprietario dell'account genitore appropriato per creare il tuo account.

  • Conferma i dettagli dell'account una volta creato nel libro mastro.

Prima di iniziare

Per completare questa guida, avrai bisogno di quanto segue:

  • Un progetto Google Cloud con l'API Universal Ledger abilitata.

  • Un ruolo IAM come roles/universalledger.networkViewer per poter almeno eseguire query sullo stato degli account in una rete Universal Ledger.

  • Un progetto Google Cloud con Cloud KMS abilitato.

    Durante il test, questo progetto può essere lo stesso in cui è abilitata l'API Universal Ledger.

    In produzione, ti consigliamo di:

    • Utilizza un progetto dedicato per le risorse Cloud KMS, separato dalle altre risorse. Google Cloud
    • Crea un progetto Google Cloud separato per gestire le chiavi Cloud KMS per ogni rete Universal Ledger che utilizzi.

  • Il ruolo IAM Amministratore Cloud KMS (roles/cloudkms.admin) nel progetto con Cloud KMS abilitato o in una risorsa padre.

Creare le chiavi di firma asimmetriche

Ogni account che opera su un Universal Ledger richiede una coppia di chiavi asimmetriche di firma pubblica-privata. La chiave privata viene utilizzata per firmare le transazioni, mentre la chiave pubblica viene registrata nel ledger per identificare il tuo account e verificare le firme.

I seguenti passaggi ti guidano nella creazione di una coppia di chiavi adatta utilizzando Cloud KMS e nel recupero della chiave pubblica. Puoi utilizzare altri approcci di gestione delle chiavi, purché producano chiavi e firme compatibili con i requisiti di Universal Ledger, ad esempio chiavi ECDSA P-256 con digest SHA-256.

  1. Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

  2. Imposta il progetto predefinito:

    gcloud config set project KEYS_PROJECT

    Sostituisci KEYS_PROJECT con l'ID del progetto da utilizzare per le risorse Cloud KMS.

  3. Se non l'hai ancora fatto, crea un portachiavi per contenere le chiavi utilizzando il comando gcloud kms keyrings create:

    gcloud kms keyrings create KEY_RING \
    --location=KEY_LOCATION

    Sostituisci quanto segue:

    • KEY_RING: il nome delle chiavi automatizzate da creare, ad esempio test-gcul-keys. Questo nome è per le tue esigenze organizzative e non deve essere registrato nel registro.
    • KEY_LOCATION: la posizione Google Cloud delle chiavi automatizzate, ad esempio global.

  4. Per ogni account che vuoi utilizzare nel ledger, crea una chiave di firma asimmetrica utilizzando il comando gcloud kms keys create:

    gcloud kms keys create KEY_NAME \
    --keyring=KEY_RING \
    --location=KEY_LOCATION \
    --purpose="asymmetric-signing" \
    --default-algorithm="ec-sign-p256-sha256"

    Sostituisci quanto segue:

    • KEY_NAME: il nome della chiave da creare, ad esempio usd-operator o eur-clearinghouse. Questo nome è per le tue esigenze organizzative e non deve essere registrato nel libro mastro.
    • KEY_RING: il nome del portachiavi in cui archiviare la chiave.
    • KEY_LOCATION: la Google Cloud posizione della chiave.

    Viene creata una coppia di chiavi ECDSA sulla curva P-256 con un digest SHA-256 come supportato dal Universal Ledger. Per un elenco dei formati supportati, consulta il riferimento KeyFormat.

  5. Recupera la parte della chiave pubblica di una versione della chiave utilizzando il comando gcloud kms keys versions get-public-key:

    gcloud kms keys versions get-public-key KEY_VERSION \
    --key=KEY_NAME \
    --keyring=KEY_RING \
    --location=KEY_LOCATION

    Sostituisci quanto segue:

    • KEY_VERSION: la versione della chiave da recuperare, 1 per le chiavi appena create.
    • KEY_NAME: il nome della chiave.
    • KEY_RING: il nome delle chiavi automatizzate che contengono la chiave.
    • KEY_LOCATION: la Google Cloud posizione della chiave.

    Questo comando restituisce la chiave pubblica in un formato con codifica PEM (KEY_FORMAT_PEM_EC_P256_SHA256) adatto all'uso con l'API Universal Ledger come:

    -----BEGIN PUBLIC KEY-----
MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ/vWkd5wgakFbVD25k8WM9Ll6We+
c8RVDS0R4G8xetsmFjfNW/ZxwWeB86IvMjxY8ZsdU9+W7BL5YM6rUB5yCQ==
-----END PUBLIC KEY-----

Identificare chi può creare il tuo account

Il tipo di account che vuoi creare determina l'account principale nel libro mastro che ha l'autorizzazione per crearlo. Devi identificare il proprietario di questo account genitore. Per informazioni sui tipi di account nel Universal Ledger, vedi Concetti chiave.

Tipo di account Creato da Invio della transazione
Currency Operator Operatore della piattaforma CreateCurrencyOperator
Clearinghouse Currency Operator CreateClearinghouse
Account manager Currency Operator CreateAccountManager
Token Manager Currency Operator CreateTokenManager
Account utente Account manager CreateAccount

Una volta identificato, dovrai coordinarti e condividere i seguenti dettagli con il proprietario dell'account principale che può creare il tuo account:

  • Il nome della rete in cui vuoi creare l'account. Per l'anteprima privata, consulta l'elenco delle reti disponibili.
  • La parte pubblica della chiave di firma asimmetrica e il relativo KeyFormat. Se hai seguito i comandi gcloud in questa guida, il formato è KEY_FORMAT_PEM_EC_P256_SHA256.
  • Una stringa di commento dell'account con tutte le informazioni pertinenti da registrare nel libro mastro associato al tuo nuovo account. Si tratta di un valore opaco che viene memorizzato nel ledger, ma non interpretato in altro modo dal Universal Ledger. Una volta creato, questo campo è immutabile e leggibile da chiunque abbia accesso alla rete.
  • Eventuali dettagli aggiuntivi necessari per compilare la transazione da inviare al momento della creazione dell'account. Ad esempio, per creare un operatore di valuta devi anche specificare la currency che verrà gestita dal nuovo operatore da creare.

Durante l'anteprima privata, contatta il tuo referente Google se non sai chi sia il proprietario dell'account genitore pertinente per il tuo caso d'uso.

Conferma la creazione dell'account

Una volta che la transazione inviata dall'account genitore viene eseguita correttamente e finalizzata nel registro, la risposta del metodo QueryTransactionState includerà un TransactionCertificate con un evento transaction_output contenente l'ID account dell'account appena creato.

L'ID sarà simile al seguente esempio:

1:USR:XTS:025sAZ55EqGKF6vpXEpSS8X891nNDEQU9yFQKYkcFzAb6

Puoi confermare che il nuovo account è presente nel registro inviando la seguente richiesta REST:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://universalledger.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/NETWORK_NAME:queryAccount?account_id=ACCOUNT_ID

Sostituisci quanto segue:

  • PROJECT_ID: l'ID del progetto in cui è abilitata l'API Universal Ledger.
  • LOCATION: la posizione dell'endpoint da raggiungere.
  • NETWORK_NAME: il nome della rete in cui è stato creato il tuo account.
  • ACCOUNT_ID: l'ID dell'account appena creato.

Vedrai un output simile al seguente:

{
  "account": {
    "publicKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1pJemowQ0FRWUlLb1pJemowREFRY0RRZ0FFSi92V2tkNXdnYWtGYlZEMjVrOFdNOUxsNldlKwpjOFJWRFMwUjRHOHhldHNtRmpmTlcvWnh3V2VCODZJdk1qeFk4WnNkVTkrVzdCTDVZTTZyVUI1eUNRPT0KLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0t",
    "roundId": "10962032",
    "comment": "My Test Account",
    "userDetails": {
      "accountManager": {
        "id": "1:ACT:XTS:02f4VSHyPsXeMZmcogbNx7bP4kfn5DYvc7d2K52RYAFd3"
      },
      "tokenManager": {
        "id": "1:TKN:XTS:024fqJS87dJ94ETN9PGhTCGd86btXj9iyWLxGQWgC3dde"
      },
      "roles": [
        "ROLE_PAYER",
        "ROLE_RECEIVER"
      ],
      "accountStatus": "ACCOUNT_STATUS_ACTIVE",
    }
  }
}

Passaggi successivi