Administration CLI

The SignServer Administration CLI (AdminCLI) is one of the available interfaces to administrate SignServer. It supports configuration of workers and associated key management as well as querying the audit log and archive.

Other options for administration includes the Administration Web and the Administration Web Services interfaces.

The SignServer administration command line interface (Admin CLI) is started using bin/signserver (or bin/signserver.cmd for Windows).

Every worker is identified by an ID and an optional name that can be used in all CLI commands.

You can configure a worker while it is in production since all configuration commands are cached until a reload command is issued and the configuration becomes active.

The following describes the SignServer Administration CLI (AdminCLI) commands:

General Commands

getstatus

Returns the status of the given worker, stating if its crypto token is active or not, and the loaded 'active' configuration. It is possible to get a brief summary or a complete listing for one worker or all configured workers. If all workers are displayed, all the global configuration parameters will also be displayed.

getconfig

Returns the current worker or global configuration depending on options. Note that for worker configuration, this configuration might be inactive until a reload command is issued.

setproperty

Sets a custom property used by the worker or crypto token. For available properties, refer to the respective section in the SignServer Reference for the given Worker and CryptoToken.

getproperty

List the value of a worker or global property.

Usage:

BASH

signserver getproperty <signerid | signerName | global | node> <propertykey>

setproperties

Used to batch a set of properties, both for the global and worker configuration. The command can be used to configure a Signer in a test environment, dump all the properties and upload it into production.

The setproperties command reads all the configuration properties form a property file, and depending on the contents of the key, it then sets the given property. All properties are set according to the following defined rule set.

Rule	Comment
Properties starting with id<num>.	Sets the property to the value of the given ID to the worker with the given id.
Properties starting with name<name>.	Sets the property to a worker with the given name. If the name does not exists, a unique ID will be generated and assigned.
Property keys containing GENID<NUM>, example WORKERGENID1 or GLOB. WORKERGENID1	The SignServer will find a free unique ID and assign substitute all GENID<num> with this ID.
Properties starting with glob.	Sets a global property with global scope.
Properties starting with node.	Sets a global property with node scope.
Properties starting with -<other prefix><value>	Removes the property, either worker or global.

For examples, see the directory sample-configs.

removeproperty

Removes a configured property.

dumpproperties

Dumps all configured properties for one or all workers in the system into a property file. If the configuration for one worker is dumped, the dumpproperties tool can be used to transfer the configuration from one installation to another. If all configurations are dumped, it can be used as a backup tool.

uploadsignercertificate

Used to upload the certificate when the worker only needs the actual signing certificate and not the entire chain.

uploadsignercertificatechain

Used when uploading a complete certificate chain to the worker.

Note that the correct command to use for upload depends on the worker and crypto token used.

importcertificatechain

Used to import a certificate chain into a crypto token. It takes a worker ID of the crypto worker (or a worker ID of a worker with the crypto token configured in the legacy way), and a path pointing to a file containing the certificate chain and a key alias to import to. Currently supported by the PKCS11 and keystore crypto token implementations.

generatecertreq

Used to generate a certificate request for a worker to be signed by a certificate authority. The command takes distinguished name and signature algorithm as parameters, and writes the request in PEM format to file. An optional key alias can be specified to generate a request given a specific key alias from the crypto token.

activatecryptotoken

Used to activate crypto tokens. Authentication code is usually the PIN used to unlock the keys on the HSM. Not used if the token is set to auto-activation.

deactivatecryptotoken

Brings a crypto token off-line. Not used if token is set to auto-activation.

renewsigner

Sends a request for renewal of the specified worker to the specified renewal worker. If the authcode parameter is omitted, the command will renew the certificate without an authcode, assuming the crypto token is auto-activated, or the worker is using a separate crypto worker (recommended). To use the previous behavior of prompting for the authcode, specify the -authprompt option. When the authcode is not passed as a parameter or prompted for, an explicit activation of the token will not be performed. For more information, see RenewalWorker.

Authorization Related

Authorization related commands are used to configure the client authorization rules for a worker when the Client Certificate Authorizer is used as AUTHTYPE.

authorizedclients

Command for adding, removing or listing a worker's client authorization rules. Replaces the legacy commands addauthorizedclient, removeauthorizedclient and listauthorizedclient.

CODE

Usage: signserver authorizedclients -worker <worker name or ID> -list 

       signserver authorizedclients -worker <worker name or ID> <-add/-remove> 
          -matchSubjectWithType <SUBJECT_MATCH_TYPE> -matchSubjectWithValue <value> \
          [-matchIssuerWithType <ISSUER_MATCH_TYPE>] -matchIssuerWithValue <issuer DN> \
          [-description <textual description>]

       signserver authorizedclients -worker <worker name or ID> <-add/-remove> \
          -matchSubjectWithType <SUBJECT_MATCH_TYPE> \
          [-matchIssuerWithType <ISSUER_MATCH_TYPE>] \
          [-description <textual description>] \
          -cert <PEM file>

Supported values for -matchSubjectWithType:

Type	Description
CERTIFICATE_SERIALNO	Serial number of the certificate.
SUBJECT_RDN_CN	Common Name (CN) RDN in textual representation from Subject DN.
SUBJECT_RDN_SERIALNO	Serial number (serialNumber/SN) RDN in textual representation from Subject DN.
SUBJECT_RDN_C	Country (C) RDN in textual representation from Subject DN.
SUBJECT_RDN_DC	Domain Component (DC) RDN in textual representation from Subject DN.
SUBJECT_RDN_ST	State or Province (ST) RDN in textual representation from Subject DN.
SUBJECT_RDN_L	Locality (L) RDN in textual representation from Subject DN.
SUBJECT_RDN_O	Organization (O) RDN in textual representation from Subject DN.
SUBJECT_RDN_OU	Organizational Unit (OU) RDN in textual representation from Subject DN.
SUBJECT_RDN_TITLE	Title (title) RDN in textual representation from Subject DN.
SUBJECT_RDN_UID	Unique ID (UID) RDN in textual representation from Subject DN.
SUBJECT_RDN_E	E-mail address in DN (E) RDN in textual representation from Subject DN.
SUBJECT_ALTNAME_RFC822NAME	RFC822Name Subject Alternative Name.
SUBJECT_ALTNAME_MSUPN	MS UPN Subject Alternative Name.

Supported values for -matchIssuerWithType:

Type	Description
ISSUER_DN_BCSTYLE	Issuer DN in textual EJBCA/BC DN style.

Example 1:

CODE

signserver authorizedclients -worker CMSSigner -list

Example 2:

CODE

signserver authorizedclients -worker CMSSigner -add 
 -matchSubjectWithType SUBJECT_RDN_CN -matchSubjectWithValue "Client One"
 -matchIssuerWithValue "CN=AdminCA1, C=SE"

Example 3:

CODE

signserver authorizedclients -worker CMSSigner -add 
 -matchSubjectWithType SUBJECT_RDN_CN -matchSubjectWithValue "Client One"
 -matchIssuerWithType ISSUER_DN_BCSTYLE -matchIssuerWithValue "CN=AdminCA1, C=SE" -description "my rule"

Example 4:

CODE

signserver authorizedclients -worker CMSSigner -add 
 -matchSubjectWithType CERTIFICATE_SERIALNO -matchIssuerWithType ISSUER_DN_BCSTYLE 
 -cert /tmp/admin.pem

Example 5:

CODE

signserver authorizedclients -worker CMSSigner -remove 
 -matchSubjectWithType CERTIFICATE_SERIALNO 
 -matchIssuerWithType ISSUER_DN_BCSTYLE 
 -cert /tmp/admin.pem

addauthorizedclient

The addauthorizedclient command is deprecated and only supports legacy rules. Use the authorizedclients command instead.

Adds a client certificate to a processable workers list of acceptable clients using this worker. Specify certificate serial number in hex and the Issuer DN of the client certificate. If DN components contains commas, these need to be escaped with backslashes. Alternatively, a certificate file (PEM or DER format) can be specified, from which the serial number and issuer DN is fetched.

Usage example 1:

BASH

signserver addauthorizedclient 1 EF34242D2324 "CN=Test Root CA"

Usage example 2:

BASH

signserver addauthorizedclient 1 EF3456789ABC "CN=Client,O=Test Organization,C=SE"

Usage example 3:

BASH

signserver addauthorizedclient 1 client.pem

removeauthorizedclient

The removeauthorizedclient command is deprecated and only supports legacy rules. Use the authorizedclients command instead.

Removes added client certificate entries.

listauthorizedclients

The listauthorizedclients command is deprecated and only supports legacy rules. Use the authorizedclients command instead.

Displays the current list of acceptable clients.

Database Related

resync

The resync command is used if a SignServer had a complete database failure. When this happens, the Global Configuration switches to Off-line mode and it is not possible for the nodes to communicate internally and the Global Configurations will no longer be in sync. When the database is up again, the resync command can be sent to the node that has the most valid Global Configuration to write it to the database. After the resynchronization is performed, the Global Configuration will re-enter On-line mode.

Archive Related

The archive commands can be used for processable workers with archiving enabled to find specific archived responses. Whether a worker or Archiver supports being queried using the archive commands, is governed by their respective implementation. For Archivers other than the default OldDatabaseArchiver and Base64DatabaseArchiver, querying might have to be performed directly in a database, filesystem, or by some custom application.

archive findfromarchiveid

Used to extract archived data from database identified by the archive ID. The ID depends on the worker. For example, in case of the TSA, the TimeStampInfo serial number is used. The data is stored with the same file title as the archive ID, and with the file extension depending on the type of item, for example .request or .response.

archive findfromrequestip

Used to extract all archived data requested from a specified IP address. All data is stored as separate files with the archive ID as file title, and the file extension depending on the type of item.

archive findfromrequestcert

Used to extract all archived data requested from a client by its specified certificate serial number and issuer DN. All data is stored as separate files with the archive ID as file title and the file extension depending on the type of item.

archive query

Used to query contents of the archive. Actual archived data is not fetched by this command.

Usage:

BASH

signserver archive query -limit <number> [-criteria  "<field> <op> <value>" [-criteria...]] [-from <index>] [-header] [-request|-response]

Option	Description
<field>	Field name from the archive: archiveId, requestCertSerialNumber, requestIP, requestIssuerDN, signerid, time, type.
<op>	Relational operator: GT, GE, LT, LE, EQ, NEQ, LIKE,NULL, NOTNULL.
-request	Shows only entries for requests.
-response	Shows only entries for responses.

Examples:

BASH

signserver archive query -limit 10 -criteria "signerid EQ 1"
signserver archive query -limit 10 -criteria "signerid EQ 1" -request
signserver archive query -limit 10 -criteria "time GT 1359623137000" -criteria "requestIP EQ 127.0.0.1
signserver archive query -limit 10 -criteria "signerid EQ 1" -outpath /tmp/out\n\n"

Administrators Related

wsadmins -list

Lists administrator certificates (certificate serial number and issuer DN) for administrators authorized to use the Admin Web Service interface to administrate SignServer.

wsadmins -add

Authorizes an administrator to use the Admin Web Service interface by certificate serial number (in hexadecimal) and issuer DN with space after each comma separating DN components. If DN components contains commas, these needs to be escaped with backslashes.

The following displays how to enter the issuer DN when using a certificate issued from EJBCA with the default (as specified by EJBCA) LDAP DN order:

TEXT

C=SE, O=TestOrganization, CN=IssuingCA

The following displays using escaped DN components:

TEXT

C=SE, O=TestOrganization\, The, CN=IssuingCA\, Th

Note that the order is reversed, compared to how the issuer DN is stored in the certificate.

The following displays how to enter the issuer DN when using a certificate issued from EJBCA with the Use LDAP DN order option disabled:

TEXT

CN=ReverseIssuingCA, O=TestOrganization, C=S

Alternatively, a certificate file can be specified from which the serial number and issuer DN will be taken.

Usage example 1:

BASH

signserver wsadmins -add -certserialno 123ABCDEF -issuerdn "CN=Neo Morpheus, C=SE"

Usage example 2:

BASH

signserver wsadmins -add -cert wsadmin.pe

wsadmins -remove

Removes an administrator from the list of authorized administrators.

wsadmins -allowany

Specifies whether any administrator with a certificate accepted by the web server/proxy is authorized or not. When set (true) it overrides the WSADMINS global property. Takes an optional boolean parameter, if left out sets to true (allow all). This can be used for initial setup.

Auditors Related

wsauditors -list

Lists auditor certificates (certificate serial number and issuer DN) for administrators authorized to use the Admin Web Service interface to query the audit log of SignServer.

wsauditors -add

Authorizes an auditor to use the Admin Web Service interface by certificate serial number (given in hexadecimal) and issuer DN.

wsauditors -remove

Removes an auditor from the list of authorized administrators.

Archive Auditors Related

wsarchiveauditors -list

Lists archive auditor certificates (certificate serial number and issuer DN) for auditors authorized to use the Admin Web Service interface to query the archive of SignServer.

wsarchiveauditors -add

Authorizes an auditor, by specifying a certificate serial number (in hexadecimal) and issuer DN, to use the Admin Web Service interface for querying the archive.

wsarchiveauditors -remove

Removes an auditor from the list of authorized archive auditors.

auditlog -query

Query the CESeCore audit log.

Usage:

BASH

signserver auditlog -query -limit <number> [-criteria "<field> <op> <value>" [-criteria...]] [-from <index>] [-header]

Option	Description
-limit	Sets the maximum number of rows matched. Required to avoid putting too much load on the server.
<field>	Field name from the audit log: additionalDetails, authToken, customId, eventStatus, eventType, module, nodeId, searchDetail1, searchDetail2, sequenceNumber, service, timeStamp.
<op>	Relational operator: GT, GE, LT,LE, EQ, NEQ, LIKE,NULL, NOTNULL.
-from	Lower index in search result (0-based).
-header	Outputs a column header before the results.

Note that if databaseprotection.enableverify is enabled at the server side, the signature of each row displayed is verified. If the verification fails for any of the rows matching the search criteria, an error message is displayed. The error message contains information about the first row that failed.

querytokenentries

Queries the entries (key alias, certificates etc) in a CryptoToken. If no limit is given, all entries are queried and printed (10 at a time). You can specify to start query from an index in the result. Search conditions can be added to only search for entries with certain key aliases.

Usage:

BASH

signserver querytokenentries -token <id or name> -limit <number> [-criteria  "<field> <op> <value>" [-criteria...]] [-from <index>] [-v]

Option	Description
-limit	Sets the maximum number of rows matched. Required to avoid putting too much load on the server.
<field>	Field name from the token: alias.
<op>	Relational operator: EQ, NEQ or LIKE.
-v	Means verbose and if given, the output also includes type, as well as any certificates or additional information available in each entry.

Peer Systems Related

wspeersystems -list

Lists certificates (certificate serial number and issuer DN) for peer systems (i.e. EJBCA) authorized to use the Peer Systems interface to query available key bindings and perform certificate renewal/rekeying.

wspeersystems -add

Authorizes a peer system to use the Peer Systems interface by certificate serial number (given in hexadecimal) and issuer DN.

wspeersystems -remove

Removes a peer system from the list of authorized peer systems.