Richiedere un nuovo account

I nuovi account in una rete Universal Ledger devono essere creati da un account amministratore con privilegi già presente nel registro. Questo account con privilegi 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:

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

  • Identificare il proprietario dell'account con privilegi appropriato che può creare il tuo account.

  • Confermare i dettagli dell'account una volta creato nel registro.

Prima di iniziare

Per completare questa guida, avrai bisogno di quanto segue:

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

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

  • Un Google Cloud progetto con Cloud KMS abilitato.

    Durante i test, questo progetto può essere lo stesso con l'API Universal Ledger abilitata.

    In produzione, ti consigliamo di:

    • Utilizzare un progetto dedicato per le risorse Cloud KMS, separato da altre Google Cloud risorse.
    • Creare un progetto separato Google Cloud 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 registro Universal Ledger richiede una coppia di chiavi pubblica-privata di firma asimmetrica. La chiave privata viene utilizzata per firmare le transazioni, mentre la chiave pubblica viene registrata nel registro per identificare il tuo account e verificare le firme.

I seguenti passaggi ti guideranno 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. Per informazioni dettagliate sui formati di chiave supportati, consulta il KeyFormat riferimento.

  1. Nella Google Cloud console, 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 una chiave automatizzata per contenere le chiavi utilizzando il gcloud kms keyrings create comando:

    gcloud kms keyrings create KEY_RING \
    --location=KEY_LOCATION

    Sostituisci quanto segue:

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

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

    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 registro.
    • KEY_RING: il nome della chiave automatizzata che contiene la chiave.
    • KEY_LOCATION: la Google Cloud posizione per la chiave.

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

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

    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, che è 1 per le chiavi appena create.
    • KEY_NAME: il nome della chiave.
    • KEY_RING: il nome della chiave automatizzata che contiene 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'utilizzo con l'API Universal Ledger, ad esempio:

    -----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 con privilegi nel registro che ha l'autorizzazione a crearlo. Devi identificare il proprietario di questo account con privilegi. Per scoprire di più sui tipi di account in the Universal Ledger, consulta Concetti chiave.

Tipo di account Creato da Invio della transazione
Operatore di valuta Operatore della piattaforma CreateCurrencyOperator
Camera di compensazione Operatore di valuta CreateClearinghouse
Account manager Operatore di valuta CreateAccountManager
Gestore token Operatore di valuta CreateTokenManager
Account utente Account manager CreateAccount

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

  • Il nome della rete in cui vuoi creare l'account. Per un elenco delle regioni supportate, consulta Reti e regioni 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 registro associato al tuo nuovo account. Si tratta di un valore opaco che viene archiviato nel registro, ma non viene interpretato in altro modo da 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 durante la 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, contatta il tuo referente Google se non sai chi è il proprietario dell'account con privilegi pertinente per il tuo caso d'uso.

Confermare la creazione dell'account

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

L'ID avrà un aspetto simile al seguente esempio:

1:USR:XTS:025sAZ55EqGKF6vpXEpSS8X891nNDEQU9yFQKYkcFzAb6

Puoi verificare che il tuo nuovo account sia 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 del tuo nuovo account 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