Richiedere un nuovo account

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

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

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

  • Conferma i dati del tuo account una volta creato nel registro.

Prima di iniziare

Per completare questa guida, devi disporre 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 i test, questo progetto può essere lo stesso di quello con l'API Universal Ledger abilitata.

    In produzione, ti consigliamo di:

    • Scopri i diversi livelli di protezione supportati da Cloud KMS e scegli quello più adatto alle tue esigenze di sicurezza.
    • 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.

    Per saperne di più, consulta le best practice per la sicurezza diGoogle Cloud e l'approfondimento sulla crittografia e sulla gestione delle chiavi di Cloud KMS.

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

Crea le chiavi di firma asimmetriche

Ogni account che opera su un Universal Ledger richiede una coppia di chiavi pubbliche-private di firma asimmetrica. 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 passaggi seguenti 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 delle chiavi supportati, consulta il riferimento KeyFormat.

  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 una chiave automatizzata 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 ledger.
    • KEY_LOCATION: la località Google Cloud per il keyring, 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 serve per le tue esigenze organizzative e non deve essere registrato nel registro.
    • KEY_RING: il nome delle chiavi automatizzate che contengono la chiave.
    • KEY_LOCATION: la posizione Google Cloud della chiave.

    In questo modo viene creata una coppia di chiavi ECDSA sulla curva P-256 con un digest SHA-256 supportato da 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, ovvero 1 per le chiavi appena create.
    • KEY_NAME: il nome della chiave.
    • KEY_RING: il nome delle chiavi automatizzate contenenti 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 per l'utilizzo con l'API Universal Ledger, ad esempio:

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

Identifica chi può creare il tuo account

Il tipo di account che vuoi creare determina l'account con privilegi nel ledger che dispone dell'autorizzazione per crearlo. Devi identificare il proprietario di quell'account con privilegi. Per scoprire di più sui tipi di account nel Universal Ledger, consulta Concetti chiave.

Tipo di account È creato da Invio della transazione
Operatore di valuta Operatore della piattaforma CreateCurrencyOperator
Clearinghouse Operatore di valuta CreateClearinghouse
Account manager Operatore di valuta CreateAccountManager
Token Manager 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 località di Universal Ledger.
  • La parte pubblica della chiave di firma asimmetrica e il relativo KeyFormat. Se hai seguito i comandi gcloud di 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 archiviato nel ledger, ma non viene 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 Currency Operator devi anche specificare l'currency che verrà gestito dal nuovo operatore da creare.

Contatta gcul-help@google.com se non sai con certezza chi è il proprietario dell'account con privilegi pertinente per il tuo caso d'uso.

Conferma che il tuo account è stato creato

Una volta che la transazione inviata dall'account con privilegi è stata eseguita e finalizzata correttamente sul ledger, 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 verificare che il nuovo account sia presente nel ledger inviando la seguente richiesta REST:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://universalledger.LOCATION.rep.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 località dell'endpoint da raggiungere.
  • NETWORK_NAME: il nome della rete in cui è stato creato il tuo account.
  • ACCOUNT_ID: l'ID del tuo 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