Accessing Members
The TRISAMembers
service is an experimental service that provides extra, secure access to the directory service for verified TRISA members. Only members of the TRISA network (e.g. members who have been issued valid identity certificates) can access detailed directory service data about the network using this service. Note: Once validated, this service will be moved into the official TRISA specification.
The TRISAMembers
Service
This section describes the protocol buffers for the TRISAMembers
endpoint, which can be found here. This file can be compiled into the language of your choice (example for Go). Note: You will need to download and install the protocol buffer compiler if you have not already.
Currently, the TRISAMembers
service is comprised of three RPCs — the List
, Summary
, and Details
RPCs. Other experimental, secure RPCs may be made available in the future.
service TRISAMembers {
// List all verified VASP members in the Directory Service.
rpc List(ListRequest) returns (ListReply) {};
// Get a short summary of the verified VASP members in the Directory Service.
rpc Summary(SummaryRequest) returns (SummaryReply) {};
// Get details for a VASP member in the Directory Service.
rpc Details(DetailsRequest) returns (MemberDetails) {};
}
Listing Verified Members
The List
RPC returns a paginated list of all verified TRISA members to facilitate TRISA peer lookups. The RPC expects as input a ListRequest
and returns a ListReply
.
ListRequest
A ListRequest
can be used to manage pagination for the VASP list request. If there are more results than the specified page size, the ListReply
will return a page token that can be used to fetch the next page (so long as the parameters of the original request are not modified, e.g. any filters or pagination parameters).
The page_size
specifies the number of results per page and cannot change between page requests; it’s default value is 100. The page_token
specifies the page token to fetch the next page of results.
message ListRequest {
int32 page_size = 1;
string page_token = 2;
}
ListReply
A ListReply
returns an abbreviated listing of VASP details intended to facilitate peer-to-peer key exchanges or more detailed lookups against the Directory Service.
The vasps
are a list of VASPs (see definition of VASPMember
below), and the next_page_token
, if specified, is notification that another page of results exists.
message ListReply {
repeated VASPMember vasps = 1;
string next_page_token = 2;
}
VASPMember
A VASPMember
contains enough information to facilitate peer-to-peer exchanges or more detailed lookups against the Directory Service. The ListReply
will contain a list of none, one, or multiple VASPMembers
.
message VASPMember {
// The uniquely identifying components of the VASP in the directory service
string id = 1;
string registered_directory = 2;
string common_name = 3;
// Address to connect to the remote VASP on to perform a TRISA request
string endpoint = 4;
// Extra details used to facilitate searches and matching
string name = 5;
string website = 6;
string country = 7;
trisa.gds.models.v1beta1.BusinessCategory business_category = 8;
repeated string vasp_categories = 9;
string verified_on = 10;
}
Summarizing Verified VASP Members in the Directory Service
The Summary
RPC returns a brief summary of information about verified VASP members in the Directory Service. The RPC expects as input a SummaryRequest
and returns a SummaryReply
.
SummaryRequest
A SummaryRequest
allows the caller to request VASP summary information from the Global Directory Service (GDS). If desired, the caller can indicate a start date to return a count of how many new members have been added since a previous query. The caller can also include a VASP ID to return that VASP’s record in the summary.
message SummaryRequest {
// The start date for determining how many members are new - optional
string since = 1;
// Include your VASP ID to return details about your VASP record in the summary - optional
string member_id = 2;
}
SummaryReply
A SummaryReply
returns summary info about the members in the Directory Service. This information includes a count of registered VASPs and certificates issued within the Directory Service. SummaryReply
also provides a count of new members and details about a particular member VASP, if requested.
message SummaryReply {
// Counts of VASPs and certificates
int32 vasps = 1;
int32 certificates_issued = 2;
int32 new_members = 3;
// Details for the requested VASP
VASPMember member_info = 4;
}
Getting TRIXO and IVMS101 LegalPerson
Details
The Details
RPC returns a detailed record for the requested VASP, including the VASPMember
details described earlier in this page, as well as the TRIXO form and IVMS101 record for the VASP. The RPC expects as input a DetailsRequest
and returns a MemberDetails
message.
DetailsRequest
A DetailsRequest
allows the caller to specify the VASP member to retrieve details for from the Global Directory Service (GDS). The member_id
is expected to be the VASP’s TRISA member ID, a unique identifier to the GDS.
message DetailsRequest {
string member_id = 1;
}
MemberDetails
A MemberDetails
message provides details about the requested VASP member, which includes not only their high level VASPMember
summary, but also the IVMS101 legal person record and responses to the TRIXO questionnaire (both of which are a required component of all TRISA certificate requests).
message MemberDetails {
// Summary information about the VASP member
VASPMember member_summary = 1;
// The IVMS101 legal person identifying the VASP member
ivms101.LegalPerson legal_person = 2;
// The TRIXO questionnaire used to register the VASP
trisa.gds.models.v1beta1.TRIXOQuestionnaire trixo = 3;
}
Connecting with mTLS
To use the TRISAMembers
service, you must authenticate with mTLS using the TRISA identity certificates you were granted during registration.
The gRPC documentation on authentication provides code samples for connecting using mTLS in a variety of languages, including Java, C++, Golang, Ruby, and Python.
For example, if you were using Golang to connect to the Directory Service, you would use the tls
, x509
, and credentials
libraries to load your TRISA identity certificates from their secure location on your computer and construct TLS credentials to mutually validate the connection with the server. Finally you would use the compiled members protocol buffer code to create a members client. Note: the protocol buffer definitions are described more fully earlier in this page.
import (
"crypto/tls"
"crypto/x509"
members "github.com/trisacrypto/directory/pkg/gds/members/v1alpha1"
"google.golang.org/grpc/credentials"
)
func (m *MyProfile) Connect() (_ members.TRISAMembersClient, err error){
config := &tls.Config{
Certificates: []tls.Certificate{m.Cert}, // m.Cert is your TRISA certificate parsed into a *x509.Certificate
MinVersion: tls.VersionTLS12,
CurvePreferences: []tls.CurveID{
tls.CurveP521,
tls.CurveP384,
tls.CurveP256,
},
PreferServerCipherSuites: true,
CipherSuites: []uint16{
tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
tls.TLS_RSA_WITH_AES_256_GCM_SHA384,
tls.TLS_RSA_WITH_AES_128_GCM_SHA256,
},
ClientAuth: tls.RequireAndVerifyClientCert, // this will ensure an mTLS connection
ClientCAs: m.Pool, // m.Pool is a *x509.CertPool that must contain the RA and IA public certs from your TRISA certificate chain
}
var creds *credentials.TransportCredentials
if creds, err = credentials.NewTLS(config); err != nil {
return nil, err
}
var cc *grpc.ClientConn
if cc, err = grpc.NewClient(m.Endpoint, grpc.WithTransportCredentials(creds)); err != nil {
return nil, err
}
return members.NewTRISAMembersClient(cc), nil
}
Note that there are currently two TRISA directories; the TRISA TestNet, which allows users to experiment with the TRISA interactions, and the VASP Directory, which is the production network for TRISA transactions. If you have registered for the TestNet and have TestNet certificates, the endpoint you will pass into the dialing function will be members.trisatest.net:443
. Alternatively, if you wish to access members of the VASP Directory and are already a registered member, you will use the endpoint members.vaspdirectory.net:443
.