Project: Athenz (Provisioning / Key Management)
File: cert_signer.md

-- * Athenz supports service authentication with X.509 certificates. The services receive X509 certificates from ZTS which requires a cert signer implementation to sign and issue X509 certificates for Athenz Services. This feature, commonly referred as Copper Argos, is described in the following . For ZTS servers to issue X509 certificates, the following two interfaces must be implemented: . The job of the CertSignerFactory class is to implement a single `create()` method which returns an instance of CertSigner class implementation. . This class implements six methods listed below: generateX509Certificate(): This method generates a signed X509 Certificate based on the given request. It takes three parameters `csr (Certificate request)`, requested key usage `keyUsage` (null for both server and client, otherwise specified usage type: server or client) and `expiryTime` which specifies requested certificate expiration time in minutes and returns a X509 Certificate in PEM format getCACertificate(): This method is to retrieve the CA certificate in PEM format that will be returned along with the x509 certificate back to the client. generateSSHCertificate(): This method is to generate a SSH Certificate based on the given request. getSSHCertificate(): This method is to retrieve the SSH Signer certificate for the given type. getMaxCertExpiryTimeMins(): This method is to retrieve the certificate max expiry time supported by the given signer. close(): This method is for closing the certSigner signer object and release all allocated resources During server startup, ZTS servers will load the configured cert signer factory class and invoke the create method. Then it will use the CertSigner object returned to issue X509 certificates to requesting services. ZTS Servers expect the configured cert signer factory class name in its `athenz.zts.certsignerfactory_class` system property. For example, ``` -Dathenz.zts.certsignerfactory_class=com.yahoo.athenz.zts.cert.impl.HttpCertSignerFactory ``` If you're installing and running Athenz services using the binary packages provided, you can configure the cert signer factory class in the conf/zts_server/zts.properties file for ZTS server: ``` athenz.zts.certsignerfactory_class=com.yahoo.athenz.zts.cert.impl.HttpCertSignerFactory ``` Here is the list of Athenz provided certificate signer implementations with a brief description of each one. -- Class: com.yahoo.athenz.zts.cert.impl.SelfCertSignerFactory This factory class creates and returns an object of SelfCertSigner class The private key file name, private key password and the DN for self signer can be configured by using the following system properties: Key File: athenz.zts.selfsignerprivatekeyfname Key password: athenz.zts.selfsignerprivatekeypassword DN: athenz.zts.selfsignercert_dn The key file must be a PEM encoded either RSA or EC private key. -- Class: com.yahoo.athenz.zts.cert.impl.HttpCertSignerFactory This factory class creates and returns a object of HttpCertSigner class This signer assumes you have a certificate singing daemon that implements POST/GET REST /x509 and /ssh endpoints to sign and return x.509 certificates. The base uri of signer service and other settings can be configured by using the following system properties: Base Uri of Cert Signer Service: athenz.zts.certsignbaseuri Connect Timeout: athenz.zts.certsignconnecttimeout This setting specifies in seconds the connect timeout. We are setting it to 10. Request Timeout: athenz.zts.certsignrequesttimeout This setting specifies in seconds the request timeout. We are setting it to 5. Retry count: athenz.zts.certsignretrycount This setting specifies the number of times the request should be retried if it's not completed with the requested timeout value. We are setting it to 3.