Certificate Authority API¶
Each of the CA services is split into two GRPC interfaces, namely a public one (indicated by a P suffix) and an administrator one (indicated by an A suffix).
Enrollment Certificate Authority¶
The administrator interface of the ECA provides the following functions:
service ECAA { // admin
rpc RegisterUser(RegisterUserReq) returns (Token);
rpc ReadUserSet(ReadUserSetReq) returns (UserSet);
rpc RevokeCertificate(ECertRevokeReq) returns (CAStatus); // not yet implemented
rpc PublishCRL(ECertCRLReq) returns (CAStatus); // not yet implemented
}
The RegisterUser
function allows you to register a new user by
specifiying their name and roles in the RegisterUserReq
structure.
If the user has not been registered before, the ECA registers the new
user and returns a unique one-time password, which can be used by the
user to request their enrollment certificate pair via the public
interface of the ECA. Otherwise an error is returned.
The ReadUserSet
function allows only auditors to retrieve the list
of users registered with the blockchain.
The public interface of the ECA provides the following functions:
service ECAP { // public
rpc ReadCACertificate(Empty) returns (Cert);
rpc CreateCertificatePair(ECertCreateReq) returns (ECertCreateResp);
rpc ReadCertificatePair(ECertReadReq) returns (CertPair);
rpc ReadCertificateByHash(Hash) returns (Cert);
rpc RevokeCertificatePair(ECertRevokeReq) returns (CAStatus); // not yet implemented
}
The ReadCACertificate
function returns the certificate of the ECA
itself.
The CreateCertificatePair
function allows a user to create and read
their enrollment certificate pair. For this, the user has to do two
successive invocations of this function. Firstly, both the signature and
encryption public keys have to be handed to the ECA together with the
one-time password previously returned by the RegisterUser
function
invocation. The request has to be signed by the user’s private signature
key to demonstrate that the user is in possession of the private
signature key. The ECA in return gives the user a challenge encrypted
with the user’s public encryption key. The user has to decrypt the
challenge, thereby demonstrating that they are in possession of the
private encryption key, and then re-issue the certificate creation
request - this time with the decrypted challenge instead of the one-time
password passed in the invocation. If the challenge has been decrypted
correctly, the ECA issues and returns the enrollment certificate pair
for the user.
The ReadCertificatePair
function allows any user of the blockchain
to read the certificate pair of any other user of the blockchain.
The ReadCertificatePairByHash
function allows any user of the
blockchain to read a certificate from the ECA matching a given hash.
Transaction Certificate Authority¶
The administrator interface of the TCA provides the following functions:
service TCAA { // admin
rpc RevokeCertificate(TCertRevokeReq) returns (CAStatus); // not yet implemented
rpc RevokeCertificateSet(TCertRevokeSetReq) returns (CAStatus); // not yet implemented
rpc PublishCRL(TCertCRLReq) returns (CAStatus); // not yet implemented
}
The public interface of the TCA provides the following functions:
service TCAP { // public
rpc ReadCACertificate(Empty) returns (Cert);
rpc CreateCertificate(TCertCreateReq) returns (TCertCreateResp);
rpc CreateCertificateSet(TCertCreateSetReq) returns (TCertCreateSetResp);
rpc RevokeCertificate(TCertRevokeReq) returns (CAStatus); // not yet implemented
rpc RevokeCertificateSet(TCertRevokeSetReq) returns (CAStatus); // not yet implemented
}
The ReadCACertificate
function returns the certificate of the TCA
itself.
The CreateCertificate
function allows a user to create and retrieve
a new transaction certificate.
The CreateCertificateSet
function allows a user to create and
retrieve a set of transaction certificates in a single call.
TLS Certificate Authority¶
The administrator interface of the TLSCA provides the following functions:
service TLSCAA { // admin
rpc RevokeCertificate(TLSCertRevokeReq) returns (CAStatus); not yet implemented
}
The public interface of the TLSCA provides the following functions:
service TLSCAP { // public
rpc ReadCACertificate(Empty) returns (Cert);
rpc CreateCertificate(TLSCertCreateReq) returns (TLSCertCreateResp);
rpc ReadCertificate(TLSCertReadReq) returns (Cert);
rpc RevokeCertificate(TLSCertRevokeReq) returns (CAStatus); // not yet implemented
}
The ReadCACertificate
function returns the certificate of the TLSCA
itself.
The CreateCertificate
function allows a user to create and retrieve
a new TLS certificate.
The ReadCertificate
function allows a user to retrieve a previously
created TLS certificate.