Plugins

*** Overview ***

The time stamp server generates time stamp tokens and have the support for the following options:

• Set of accepted policies
• Set of accepted algorithms
• Set of accepted extensions
• Accuracy microseconds
• Accuracy milliseconds
• Accuracy seconds
• Included certificate chain (currently doesn't include CRLs)
• Ordering
• TSA name

The time stamp signer currently don't support:

• CRL inclusion
• Signed attributes
• Unsigned attributes

Timestamps requests are served through a http service at the URL:

'http://<host name>/signserver/process?workerId=<worker Id>'
                        

If no 'worker Id' parameter is specified then will the id of 1 be used as default.

The time-stamp signer requires a time-stamp certificate with the extended key usage 'time-stamp' only. The extended key usage extension must be critical.

*** Available Properties ***

The following properties can be configured with the signer:

TIMESOURCE = property containing the fully qualified name of the class implementing the ITimeSource that should be used (OPTIONAL). Below are the built-in TimeSourceS available:

org.signserver.server.LocalComputerTimeSource

This is the default TimeSource and uses the time from the local computer and always returns the time.

org.signserver.server.StatusReadingLocalComputerTimeSource

This TimeSource returns the time from the local computer but only if the status property INSYNC is returned as true from the Status Repository.

ACCEPTEDALGORITHMS = A ';' separated string containing accepted algorithms, can be null if it shouldn't be used. (OPTIONAL, Strongly recommended) Supported Algorithms are: GOST3411, MD5, SHA1, SHA224, SHA256, SHA384, SHA512, RIPEMD128, RIPEMD160, RIPEMD256

ACCEPTEDPOLICIES = A ';' separated string containing accepted policies, can be null if it shouldn't be used. (OPTIONAL, Recommended)

ACCEPTEDEXTENSIONS = A ';' separated string containing accepted extensions, can be null if it shouldn't be used. (OPTIONAL)

DEFAULTTSAPOLICYOID = The default policy ID of the time stamp authority (REQUIRED, if no policy OID is specified in the request then will this value be used.)

ACCURACYMICROS = Accuracy in micro seconds, Only decimal number format, only one of the accuracy properties should be set (OPTIONAL)

ACCURACYMILLIS = Accuracy in milliseconds, Only decimal number format, only one of the accuracy properties should be set (OPTIONAL)

ACCURACYSECONDS = Accuracy in seconds. Only decimal number format, only one of the accuracy properties should be set (OPTIONAL)

ORDERING = The ordering (OPTIONAL), default false. Only false is supported.

TSA = General name of the Time Stamp Authority. (OPTIONAL)

 'bin/signserver.sh module add dist-server/mrtdsigner.mar'
                    

*** Overview ***

The MRTD Signer performs a RSA signing operation on incoming data. The data should already be padded. This signer i used to sign 'Machine Readable Travel Documents' i.e. electronic passports.

*** Available Properties ***

No configuration properties exists.

*** Overview ***

The main purpose of the PDF signer is to add digital signatures to PDF documents.

The signer supports the addition of visible or invisible signatures. Both visible and invisible signatures serve the same purpose of signing document, and technically are equivalent in that sense. The difference is that when visible signature is applied to a document, signature image (in shape of rectangle) is placed at the specified place in the document, clicking on which will allow seeing properties of the signature (Adobe Acrobat Reader). On the other hand when invisible signature is applied, signature properties are accessed through menu items. For visible signatures properties such as : custom signature image, signature rectangle, page at which signature rectangle to be drawn and others can be specified (see Available Properties below)

PDF Signer can also apply timestamp to a signature. If the signature is timestamped, it can be viewable through signature properties in Adobe Acrobat Reader. Timestamping is used to prove that document was signed before the time specified by timestamp token. If the signature is not timestamped then the signature time specified in the signature properties is not considered to be trusted. It is strongly advised to apply timestamp to a signature, and the TSA module can be used for this purpose.

Also CRL or OCSP Response of the signer's certificate can be embedded inside the signature package. Embedding CRL or OCSP response with the package will help validate signature even after the signer's certificate is expired. (Though it will not totally guarantee the long term signature preservation. Topic of long term signature preservation for archival purposes is a large one and is discussed to be implemented in future versions of SignServer).

The PDF Signer can also be configured to enforce that certain PDF permissions are not available in the signed document and/or that certain permissions should be removed.

*** PDF passwords ***

PDF documents can optionally be protected by a password.

There are two different types of passwords:

• User password:
  Also sometimes referred to as "open password" or "document password". It can be used for reading an encrypted document.
• Owner password:
  Also sometimes referred to as "permission password" or "security restriction password". It can be used for reading an encrypted document and making changes to a document that has permissions.

If a document is protected by an owner password it has to be supplied with the request for SignServer to sign the document. If the document is protected by a user password, either the user password or the owner password has to be supplied with the request for SignServer to sign the document.

*** PDFSigner Requests ***

PDF signing requests can be served using either web services or the web server interface (HTTP). See Integration for general information about the different interfaces.

For the web server interface the GenericProcessServlet can be used. The PDFSigner supports the extra request field "pdfPassword" letting the client supply a PDF password to be used for opening the PDF for signing (not required unless the PDF is already password protected).

For the web services interface the request should contain an encoded GenericProcessesRequest and the response will be an GenericProcessResponse. It is possible to supply a PDF password by including it in the requestMetaData with the key "pdfPassword".

*** Worker Properties ***

The following properties can be configured with the signer:

REASON	The reason included in the PDF signature and displayed by the PDF reader. Default: "Signed by SignServer".
LOCATION	The location included in the PDF signature and displayed by the PDF reader. Default: "SignServer".
ADD_VISIBLE_SIGNATURE	Setting that control whether signature to be added should be visible or invisible. Possible values: True or False. Default: "False"
VISIBLE_SIGNATURE_PAGE	Specifies the page on which the visible signature will be drawn. This property is ignored if ADD_VISIBLE_SIGNATURE is set to False. Possible values: "First" : signature drawn on first page of the document, "Last" : signature drawn on last page of the document, page_number : signature is drawn on a page specified by numeric argument. If specified page number exceeds page count of the document ,signature is drawn on last page. If page_number specified is not numeric (or negative number) the signature will be drawn on first page Default: "First".
VISIBLE_SIGNATURE_RECTANGLE	Specifies the rectangle signature is going to be drawn in. This property is ignored if ADD_VISIBLE_SIGNATURE is set to False. Format is : (llx,lly,urx,ury). Here : llx =left lower x coordinate, lly=left lower y coordinate, urx =upper right x coordinate, ury = upper right y coordinate Default: "400,700,500,800".
VISIBLE_SIGNATURE_CUSTOM_IMAGE_BASE64 & VISIBLE_SIGNATURE_CUSTOM_IMAGE_PATH	If we want the visible signature to contain custom image, specify image as base64 encoded byte array. Alternatively custom image can be specified by giving a path to image on file system. Note: if specifying a path to an image "\" should be escaped (thus C:\photo.jpg => "C:\\photo.jpg") Note: if specifying image as base64 encoded byte array "=" should be escaped (this "BBCXMI==" => "BBCXMI\=\=") If both of these properties are set then VISIBLE_SIGNATURE_CUSTOM_IMAGE_BASE64 will take priority. If we do not want this feature then do not set these properties. Default: not set (no custom image). These properties are ignored if ADD_VISIBLE_SIGNATURE is set to False. NOTE: in clustered environment it is more manageable and advised to specify image as base64 string, since image data will be stored in central database. Otherwise each node should contain copy of the image, and each image managed separately (ex: on image updates, or insertion of new image for different worker)
VISIBLE_SIGNATURE_CUSTOM_IMAGE_SCALE_TO_RECTANGLE	If we want our custom image to be resized to specified rectangle (set by VISIBLE_SIGNATURE_RECTANGLE) then set to True. If set to True image might look different that original (as an effect of resizing). If set to False the rectangle drawn will be resized to specified image's sizes. If set to False llx and lly coordinates specified by VISIBLE_SIGNATURE_RECTANGLE property will be used for drawing rectangle (urx and ury will be calculated from specified image's size). This property is ignored if ADD_VISIBLE_SIGNATURE is set to False or if custom image to use is not specified. Possible values: True, False. Default: "True".
CERTIFICATION_LEVEL	Set this property to have the document certified with a certifying signature. Possible values: NOT_CERTIFIED: The document is not certified. FORM_FILLING: The document is certified but the form can be filled in without invalidating the signature. FORM_FILLING_AND_ANNOTATIONS: The document is certified but the form can be filled in and annotations added without invalidating the signature. NO_CHANGES_ALLOWED: The document is certified and no changes can be made. Default: "NOT_CERTIFIED".
TSA_URL	If we want to timestamp document signature, specify timestamp authority URL. If we do not want to timestamp document signature, do not set property. Note: if path contains characters "\" or "=" , these characters should be escaped (thus "\" = "\\", "=" =>"\=") Default: not set (no timestamping).
TSA_USERNAME & TSA_PASSWORD	If the TSA requires authentication for timestamping, specify username and password. If the TSA does not require authentication, do not set these properties. These properties are ignored if TSA_URL is not set (no timestamping). Default: not set (tsa does not require authentication).
EMBED_CRL	If we want to embed the CRL for signer certificate inside the signature package set to True, otherwise set to False. Default: "False".
EMBED_OCSP_RESPONSE	If we want to embed the OCSP response for the signer certificate inside the signature package set to True, otherwise set to False. Note: issuer certificate (of signing certificate) should be in certificate chain. Default: "False".
ARCHIVETODISK	If we want the produced signed document to be stored in the local file system set this property to true and add the ARCHIVETODISK_PATH_BASE property explained below. Default: "False".
ARCHIVETODISK_PATH_BASE	The file path to the folder to store the signed documents in. Required if ARCHIVETODISK is True.
ARCHIVETODISK_PATH_PATTERN	Pattern used for creating sub-folders under the ARCHIVETODISK_PATH_BASE folder. Current date can be put in by adding ${DATE:yyyy} where yyyy can be replaced be the same syntax as defined in the class java.text.SimpleDateFormat. Other fields are: ${WORKERID} ${WORKERNAME} ${REMOTEIP} ${REQUESTID} ${TRANSACTIONID} ${USERNAME} Default: "${DATE:yyyy/MM/dd}".
ARCHIVETODISK_FILENAME_PATTERN	Pattern used for creating the filename. The same fields and syntax as for the ARCHIVETODISK_PATH_PATTERN property can be used. Default: "${WORKERID}-${REQUESTID}-${DATE:HHmmssSSS}.pdf".
REFUSE_DOUBLE_INDIRECT_OBJECTS	True if PDF documents containing multiple indirect objects with the same name should be refused. Used to mitigate a collision signature vulnerability described in http://pdfsig-collision.florz.de/.
REJECT_PERMISSIONS	Reject signing of the document if any of the permissions in the comma separated list would be in the document. Available permissions: ALLOW_PRINTING ALLOW_MODIFY_CONTENTS ALLOW_COPY ALLOW_MODIFY_ANNOTATIONS ALLOW_FILL_IN ALLOW_SCREENREADERS ALLOW_ASSEMBLY ALLOW_DEGRADED_PRINTING Default: unset/empty (no permissions are rejected)
SET_PERMISSIONS	Replace the current permissions (if any) with the permissions specified in this comma separated list of permissions. Available permissions: The same permission names as for the property REJECT_PERMISSIONS. This property can not be specified if REMOVE_PERMISSIONS is used. Notice 1: This property and the REMOVE_PERMISSIONS property only sets the permissions setting in the document. All permissions might not be enforced by the PDF reader and some permissions even though specified by this property to be allowed might not be allowed when opening the final document (i.e. if that would invalidate the signature and/or certification). Notice 2: If the document is not already protected by an owner password and the SET_OWNERPASSWORD is not specified a random password will be used as owner password. Default: unset (permissions are not set by this property)
REMOVE_PERMISSIONS	Remove all permissions specified in this comma separated list from the document. Available permissions: The same permission names as for the property REJECT_PERMISSIONS. This property can not be specified if SET_PERMISSIONS is used. Notice: This property only removes the permissions listed even if some permissions (i.e. ALLOW_PRINTING) by the standard gives more permissions (i.e. also ALLOW_DEGRADED_PRINTING). To remove all permissions to print remove both ALLOW_PRINTING and ALLOW_DEGRADED_PRINTING. To still have ALLOW_DEGRADED_PRINTING it is possible to specify to only remove ALLOW_PRINTING. See also Notice 1 and Notice 2 for REMOVE_PERMISSIONS which also applies to this setting. Removing only ALLOW_DEGRADED_PRINTING has no effect as degraded printing is implicitly allowed if printing is allowed. Default: unset/empty (no permissions are removed)
SET_OWNERPASSWORD	Sets the specified password as owner password in the document. The same permissions as before will be used (unless other properties will change them). The same encryption algorithm as the original document will be used. If the original document did not use any encryption then the default encryption algorithm will be used. Default: unset (if the permissions are changed, the existing owner password will be used or if no such password is used in the document a semi-random password will be created)

*** Overview ***

ODF Signer, which stands for Open Document Format Signer is a plug-in to SignServer that applies server side signature to documents in ODF format. It has been tested with OpenOffice.org 3.1.

ODF Signer supports only "invisible" signatures, that is unlike PDF signer there's no pictorial representation of the digital signature. When you open signed document in OpenOffice.org you can verify signature using toolbars, or the notifier in status bar (red mark), which notifies user that the document is digitally signed.

*** Available Properties ***

Other than standard worker properties, ODF Signer does not have any other custom ODF signer specific properties.

*** Overview ***

The XML Signer creates enveloped XML signatures using XMLDSig.

The signed XML document can be validated using the XML Validator.

*** Available Properties ***

This signer has no extra properties above the standard worker properties.

*** Overview ***

OOXML Signer, which stands for Office Open XML Signer is a plug-in to SignServer that applies server side signature to documents in OOXML format. It has been tested with MS Office 2007.

Currently OOXML Signer supports only "invisible" signatures , that is unlike PDF signer there's no pictorial representation of the digital signature. When you open signed document in MS Office you can verify signature using toolbars, or the notifier in status bar (red mark), which notifies user that the document is digitally signed.

*** Available Properties ***

Other than standard worker properties, OOXML Signer does not have any other custom OOXML signer specific properties.

NOTE : In later versions of OOXML Signer it is planned to add support for visible signatures and custom signature image.

*** Overview ***

The CMS signer can sign arbitrary data and produces a CMS (RFC 3852) SignedData structure in binary format.

Currently the signed content is always embedded as well as the signer certificate.

*** Overview ***

The XML validator validates the signature of XML documents. The certificate is checked by the configured certificate validation service.

*** Available Properties ***

VALIDATIONSERVICEWORKER = Name or id of validation service worker for handling certificate validation

RETURNDOCUMENT = True if the response should contain the validated document

STRIPSIGNATURE = True if the signature should be removed from the document if it is returned

*** Overview ***

Dispatches the request to the first of the configured workers that has an active cryptotoken. This dispatcher can be useful if you want to have one worker to call that forwards the request to any of the configured workers that has a valid certificate etc.

*** Available Properties ***

WORKERS = Comma separated list of workerNameS to try to forward requests to.

*** Overview ***

The default validation service have a set of Validators. A validator is responsible to checking the validity against one or more issuers using for example CRL check or OCSP/XKMS lookup or just by checking some database. Currently there are no ready to use validators, these remain to be developed in future versions of the SignServer.

The Default Validation Service supports validations to be cached for some or all issuers for a specified amount of time.

If not configured otherwise will the validation service use the DefaultX509CertTypeChecker that determines the certificate type from the key usage in the certificate. Key Encipherment and Digital Signature indicates a IDENTIFICATION type and Non-reputation indicates ELECTRONIC SIGNATURE.

There exists a validation specific WebService that can be used for platform independent client calls. The WebService must be enabled during the build and isn't by default. The WebService WSDL file is located at the URL http://<hostname>:8080/signserver/validationws/validationws?wsdl and it contains two calls one is 'isValid' that performs the validation check and the other is a getStatus call that checks the health of the node and its underlying systems. The last calls can be used by clients for monitoring or implementing redundancy.

Important, Due to class path conflict in JBoss 4.2.x own JBoss WebService stack and the JAX-WS stack used by the SignServer must the JBoss WebService stack be removed before the WebService is used. This is done by going to JBOSS_HOME/server/default/deploy and remove the directory jbossws.sar.

*** Available Properties ***

The following properties can be configured with the default validation service:

The validation service have three types of properties, general properties (that applies for the service and all configured validators), validator properties (that only applies for a specific validator) and issuer properties (that only applies for an issuer configured in a specific validator).

General Properties:

CACHEDISSUERS = A ';' separated list of issuer names (usually issuer DNs) (Optional, no validation is cached if unset.)

CERTTYPECHECKER = Certificate type checker that should be used to determine the type of certificate (Optional, default is org.signserver.validationservice.server.DefaultX509CertTypeChecker)

TIMEINCACHE = Time in seconds a certificates validation should be cached (Optional, default is 10 seconds)

Validator properties:
Validator properties is specified with the prefix of 'validator<validatorId>.' or 'val<validatorId>.' were validator Id should be an integer between 1 and 255. For instance, to specify the type of a validator with an id of 1 then specify 'val1.classpath=some.classpath.SomeClass'. This validator will be initialized with all its validator specific properties (with 'val<id>.' prefix removed) as well as the general ones.

CLASSPATH = Class path to the validator that should be used. (Required for each configured validator)

Issuer properties: Issuer properties are specified as 'val<val id>.issuer<issuer id>.<property>' were issuer id is a positive integer between 1 and 255. All generic and validator specific properties (with the given validator id) will also be propagated to the specific issuer configuration.

CERTCHAIN = The certificate path of the CA certificates used to verify the certificate. Should be a appended BASE64 string. (Required for each configured issuer).

Here is an example configuration of a validation service to clarify things even further

# Set up the worker -> validation service wrapper
GLOB.WORKER1.CLASSPATH= org.signserver.validationservice .server.ValidationServiceWorker
#Uncomment and set class path to custom validation service, othervise is default #used.
#WORKER1.TYPE=

# Name of Service (Optional)
WORKER1.NAME=ValidationService1

# Define TestCA2 and TestCA3 as a cached for 15 seconds, TestCA1 is Not cached.
WORKER1.CACHEDISSUERS=CN=TestCA2;CN=TestCA3
WORKER1.TIMEINCACHE=15

# Define a validator in charge of issuer TestCA1 and TestCA2
WORKER1.VAL1.CLASSPATH=<Class path to some validator>
WORKER1.VAL1.ISSUER1.CERTCHAIN=EFWAASDFADFASDFKASDKFW1231.....
WORKER1.VAL1.ISSUER2.CERTCHAIN=EFWAASDFADFASDFKASDKFW1231.....

# Define a validator in charge of issuer TestCA3
WORKER1.VAL2.CLASSPATH=<Class path to some validator>
WORKER1.VAL2.ISSUER1.CERTCHAIN=EFWAASDFADFASDFKASDKFW1231.....
                        

*** Overview ***

The group key service framework is used to manage and distribute group keys to clients in an organisation. The keys can be generated on demand or pre-generated at times when the system is not utilized a lot. The group keys can be both symmetric and asymmetric but one service can only distribute one type of key. If several kinds of keys are required should multiple services be set up within the same server.

The group keys are stored encrypted in database. The encryption key can be configured to be switched automatically after a defined number of encryptions to avoid overexposure of the cryptographic data. It is also possible to switch the encryption key manually.

The Framework requires an ExtendedCryptoToken, the difference are that the extended token have additional support for key export and symmetric key operations.

The Group Key Service have CLI commands for administration of the service such as pre-generate keys, manual switch of encryption key and removal of group keys.

The communication to the group key service is mainly done through the main Web Service interface. But other ways of communicating with the server might come in the future.

Authorization to group keys is very important and therefore should a special plug-in be developed that looks up which clients that should have access to a specific group key which fit into the organisation needs. See the authorization chapter of how to develop a customized authorization plug-in.

The basic configuration of a group key service is very similar to that of a validation service. Two entries is required in the global configuration. The first is the class path for the Worker to GroupKeyService wrapper, then a class path reference to the extended crypto token used with the service. If not the default group key service should be used it is possible to define a custom one by specifying its class path in the TYPE worker property.

*** Available Properties ***

USEPREGENERATION = Setting defining of keys should be pre-generated or generated on the fly when needed. If the pool of pre-generated keys gets empty will new keys always be generated automatically. (Optional, default is true)

ENCKEYALG = Encryption algorithm used to encrypt the group keys stored in database. (Optional, default is "AES")

ENCKEYSPEC = Specification of the encryption key. (Optional, default is "256")

GROUPKEYALG = Defines the type of group keys that this service should generate (Optional, default is "AES")

GROUPKEYSPEC = Specification of the generated group keys. (Optional, default is "256")

KEYSWITCHTHRESHOLD = Setting defining the number of group keys that should be encrypted by the same encryption key before it's switched. (Optional, default is 100000)

*** Overview ***

The RenewalWorker can be used to generate new keys and then contact EJBCA using web services to get a new certificate. The worker accepts GenericPropertiesRequestS and returns GenericPropertiesResponseS.

*** Worker Properties ***

EJBCAWSURL = URL to the EJBCA. Example: https://ca-server:8443/ejbca

TRUSTSTOREPATH = Path to the keystore containing the CA's SSL server certificate as a trusted entry.

TRUSTSTORETYPE = Type of keystore. JKS is supported.

TRUSTSTOREPASSWORD = Password protecting the truststore keystore.

*** Properties of renewee ***

KEYALG = Algorithm for the key generation. Examples: RSA, DSA or ECDSA

KEYSPEC = Key length (for RSA or DSA) or curve name (for ECDSA). Examples: 2048, 4096, secp256r1

EXPLICITECC = True if explicit domain parameters should be used instead of NamedCurves. Default: false

DEFAULTKEY = Key alias for the current key.

NEXTCERTSIGNKEY = Key alias for the next key.

*** Request Properties ***

WORKER = Name of the worker that should be renewed.

FORDEFAULTKEY = If the current key should be used instead of the next key or a new key. (Optional, default: false)

*** Response Properties ***

RESULT = "OK" if the renewal succeded otherwise "FAILURE".

MESSAGE = Error message if any.

*** Renewal modes ***

Renewee		Request	Result
DEFAULTKEY	NEXTCERTSIGNKEY	FORDEFAULTKEY	DEFAULTKEY	NEXTCERTSIGNKEY
-	-	-	New key and alias	Removed
present	-	-	New key and alias	Removed
-	present	-	Alias from nextcertsignkey	Removed
present	present	-	Alias from nextcertsignkey	Removed
present	-	TRUE	Same alias	Same alias
present	present	TRUE	Same alias	Same alias

*** Overview ***

A CryptoToken using a PKCS#12 (.p12/.pfx) key-store in the local file-system.

In a clustered environment the key store must placed at the same location at all nodes.

The P12CryptoToken, doesn't support the destroyKey() method

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.JKSCryptoToken

*** Available Properties ***

KEYSTOREPATH: The full path to the key-store file to load. (required)

KEYSTOREPASSWORD: The password that locks the key-store. Used for automatic activation.

DEFAULTKEY: The key to use. If not specified the first found key is used. (optional)

*** Overview ***

A CryptoToken using a Java Key Store (.jks) in the file-system.

In a clustered environment must the key store be at the same location at all nodes.

The JKSCryptoToken, doesn't support the destroyKey() method

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.P12CryptoToken

*** Available Properties ***

KEYSTOREPATH: The full path to the key-store to load. (required)

KEYSTOREPASSWORD: The password that locks the key-store. Used for automatic activation.

DEFAULTKEY: The key to use. If not specified the first found key is used. (optional)

NEXTCERTSIGNKEY: The next key to use. See PKCS11CryptoToken. (optional)

*** Overview ***

Using PrimeCardHSM it's possible to use a SmartCard to generate 2048-bit RSA signatures. The SmartCard can perform about one signature a second. PrimeCardHSM is proprietary software by PrimeKey Solutions AB.

PrimeCardHSM requires PCSCD software and SmartCard drivers. See separate documentation about installing PrimeCardHSM.

The PrimeCardHSMCryptoToken, doesn't support the destroyKey() method.

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.PrimeCardHSMCryptoToken

*** Available Properties ***

DEFAULTKEY = Hash value of the signing key on the card. See PrimeCardHSM documentation for more information.(Required)

NEXTCERTSIGNKEY: The next key to use. See PKCS11CryptoToken. (optional)

AUTHCODE = Authentication code for automatic activation (Optional).

*** Overview ***

Using PKCS11 it's possible to use a HSM that has a PKCS11 module, such as Utimaco, nCipher, SafeNet or AEP KeyPer. SignServer uses the same underlying implementation of PKCS11 crypto tokens as EJBCA. To find out more about supported devices and get information how to configure them you can visit the HSM documentation at EJBCA.org. The only thing that differs are the token labels strings, which you should use from below for SignServer. A very useful tool from EJBCA is the ClientToolBox. If you can generate anbd test PKCS11 keys using the clientToolBox, you can use them with SignServer.

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.PKCS11CryptoToken

*** Available Properties ***

DEFAULTKEY = The key alias. (Required)

NEXTCERTSIGNKEY = The next key to use. This property can be used to hold the name of the next key to use. Certificate signing requests (CSR) can be made for this key can while to the current key (DEFAULTKEY) is still in production. After uploading the new certificate the value of NEXTCERTSIGNKEY can be moved to DEFAULTKEY. (optional)

PIN = Authentication code for activation. (Required)

SHAREDLIBRARY = Full path to the library containing the PKCS11 interface. (Required)

SLOT or SLOTLISTINDEX = Slot number or the index of the slot to use. (Required and only one of them can be used.)

ATTRIBUTESFILE = Path to file with PKCS#11 attributes used for key generation.

Sample p11attributes.cfg working with SafeNet Luna:

attributes(generate,*,*) = {
  CKA_TOKEN = true
}
attributes(generate,CKO_PUBLIC_KEY,*) = {
  CKA_ENCRYPT = true
  CKA_VERIFY = true
  CKA_WRAP = true
}
attributes(generate, CKO_PRIVATE_KEY,*) = {
  CKA_EXTRACTABLE = false
  CKA_DECRYPT = true
  CKA_SIGN = true
  CKA_UNWRAP = true
}
                        

*** Example usage ***

Edit qs_pdfsigner_configuration.properties and choose the sign token setting for the PKCS11 sign token. Run the following command to set up a PDF signer using the PKCS11 properties configured: bin/signserver.sh setproperties qs_pdfsigner_configuration.properties

Generate a keypair for the signer: bin/signserver.sh generatekey 8 -alias defaultKey -keyalg RSA -keyspec 2048

Test the keypair: bin/signserver.sh testkey 8

You also need a certificate for the signer. Generate a certificate request with the command: bin/signserver.sh generatecertreq 8 "CN=PKCS11 Signer token" SHA1WithRSA /tmp/certreq.pem

Add a user in EJBCA with a certificate profile suitable for signing, and enrol for a "Server Certificate" using the public web pages.

Create the certificate chain file with the command: cat /tmp/cert.pem /tmp/AdminCA1.pem > /tmp/certchain.pem

The signer certificate must be first, and the root CA certificate last.

Upload the signing certificate chain to the signer using the command: bin/signserver.sh uploadsignercertificatechain 8 GLOB /tmp/certchain.pem

After the certificate chain has been uploaded to the server, the configuration must be reloaded and the server must be restarted. It is not sufficient to only reload the configuration.

*** Overview ***

The SoftCryptoToken is a simple token managing it's own soft keys instead of using a PKCS12 file. It can be used for test and demonstration purposes. The keys are stored in the worker's properties and is generated when genCertificateRequest is called. One key is used for all purposes and a new key is generated for every certificate request.

The method destroyKey is not supported.

There is also a tool available for constructing the properties from a PKCS12 file in CryptoTokenUtils.java. To run the tool outside the IDE first build SignServer by running "ant". After that the tool can be executed with something similar to:

java -cp dist-server/signserver-ejb.jar:lib/1.6/bcprov-jdk.jar:dist-server/lib/SignServer-Common.jar:lib/ejbca-util.jar org.signserver.server.cryptotokens.CryptoTokenUtils createsoft src/test/dss10/dss10_signer1.p12 "signer 1" foo123
                        

*** SIGNERTOKEN.CLASSPATH ***

The fully qualified class name is: org.signserver.server.cryptotokens.SoftCryptoToken

*** Available Properties ***

KEYDATA = The serialized KeyPair generated by genCertificateRequest, usually is this setting configured by the SoftCryptoToken itself.

KEYALG = The algorithm used when generating new keys. (Optional, default is "RSA")

KEYSPEC = The key specification used when generating new keys. (Optional, default is "2048")

*** Example usage ***

First change the global property of WORKER<ID>.CRYPTOTOKEN.CLASSPATH of the worker you want to use the SoftCryptoToken with. After reload will an empty and inactive SoftCryptoToken be created.

Then generate a certificate request with the command, in this step will new keys be generated

bin/signserver.sh generatecertreq <id> "CN=Soft Signer token" SHA1WithRSA /tmp/certreq.pem
                        

Then upload the signing certificate to the worker using the command:

bin/signserver.sh uploadsignercertificatechain <id> GLOB /tmp/cert.pem
                        

After the certificate chain has been uploaded to the server, the configuration must be reloaded and the SoftCryptoToken will be active and ready to use.