Command Line Client

The Command Line Client using the WS-API can be used for reference on how to use the WS-API.

The client has the following functions:

  • cvcrequest: Adds a new user and requests a CV Certificate.
  • cvcgetchain: Retrieves the last certificate chain for a user.
  • cvcprint: Used to parse and print CV Certificate and requests.

Enter the command to retrieve usage information:

ejbca> cd dist/clientToolBox
ejbca/dist/clientToolBox> ./ejbcaClientToolBox.sh CvcWsRaCli
Usage: cvcrequest cvcgetchain cvcprint cvcpem
  
ejbca/dist/clientToolBox> ./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest
Usage : cvcrequest <username> <password> <subjectdn> <sequence> <caname> <signatureAlg> ...
...
  
ejbca/dist/clientToolBox> ./ejbcaClientToolBox.sh CvcWsRaCli cvcprint
Usage : cvcprint <filename> [verifycert]
...

CLI Authentication and Privileges

The CLI uses Client Certificate Authentication, enabling performing administrative tasks in EJBCA as long as your client certificate has the correct RA administrator privileges in EJBCA.

To issue certificates for a request, an end entity must first be added in EJBCA. Unauthenticated requests entered using the CLI is authenticated using a one-time password set during entity registration. 

However, authenticated requests are verified, granted or rejected based on the verification of the outer signature on the request. If an end entity already exists, and have a previously issued certificate, the previous certificate can authenticate the request and automatically grant it. 

For DV requests authenticated with a CVCA certificate, the CVCA certificate instead of a previously issued certificate can authenticate the request.

CLI Examples

The CLI is part of the Client Tool Box.

Run the following to build the Client Tool Box (that can be used from any remote computer):

ant clientToolBox
cd dist/clientToolBox

Example 1: Receiving request from a Foreign DV

The following displays an example command to receive a request from a foreign DV:

./ejbcaClientToolBox.sh EjbcaWsRaCli edituser dv-de foo123 false "CN=dvca,C=DE" NULL NULL CVCAPK 1 USERGENERATED NEW DV DV  
./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest dv-de foo123 "CN=dvca,C=DE" SE001 SHA256WithRSA 2048 false dedv

Where

  • your CVCA is called CVCAPK in EJBCA and uses algorithm SHA256WithRSA with 2048 bit keys.
  • an End entity profile, DV, is created with CN and C as required DN fields, and DV as available certificate profiles.
  • a Certificate profile, DV, is created of type SubCA.
  • the received request is stored in a file dedv.cvreq.

The first command adds the end entity in EJBCA and only has to be run the first time. foo123 is the one-time password set to authenticate the request.

If the request is an authenticated request signed by a CVCA and that CVCA has been imported in EJBCA (Edit Certificate Authorities->Import CA certificate), the request will be verified and granted. For authenticated request the one-time password is not used.

Example 2: Generating Keys and Request for an IS

The following displays an example command to generate keys and a request for an IS using SHA256WithECDSA and secp256r1 curve:

./ejbcaClientToolBox.sh EjbcaWsRaCli edituser issecp foo123 false "CN=ISSECP,C=SE" NULL NULL DVCA 1 USERGENERATED NEW IS IS

This command adds the IS as end end entity in EJBCA. It only has to be done the first time, or if the IS previous certificates expire. When using authenticated requests these are used instead of the one-time password, but if the previous certificate expires, a new one-time password is needed to authenticate the request.

./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest issecp foo123 "C=SE,CN=ISSECP" 00005 SHA256WithECDSA secp256r1 true issecp

Where

  • your DV is called DVCA in EJBCA and uses algorithm SHA256WithECDSA with secp256r1 curve. Where an End entity profile, IS, is created with CN and C as required DN fields, and IS as available certificate profiles.
  • a Certificate profile, IS, is created of type EndEntity.
  • the generated request is stored in a file issecp.cvreq, the generated private key in issecp.pkcs8.

The issued IS certificate is stored in the file issecp.cvcert.

If the request is an authenticated request signed by a CVCA and that CVCA has been imported in EJBCA, the request will be verified and granted.

To create an authenticated request for this user you can issue the following command, which authenticates the new request with the old key and certificate.

./ejbcaClientToolBox.sh CvcWsRaCli cvcrequest issecp foo123 "C=SE,CN=ISSECP" 00006 SHA256WithECDSA secp256r1 true issecpnew issecp.pkcs8 issecp.cvcert

The request will be automatically granted (the password passed will be ignored) and the new certificate will be written to issecpnew.cvcert.