EDITRAN/XAdES XAdES Signing and verification z/os Installation Manual INDRA April 2018
EDITRAN/XAdES z/os. Installation Manual CONTENTS 1. INTRODUCTION... 1-1 2. INSTALLATION AND REQUIREMENTS... 2-1 2.1. Installation Requirements.... 2-1 2.2. Install in USS.... 2-1 3. INSTALLATION OF CERTIFICATES... 3-1 3.1. Truststore File... 3-1 3.2. Keystore File... 3-1 3.3. Configuration of the certificate revocation status query... 3-2 3.4. Authentication of the LDAP Server... 3-2 4. ANNEX A... 4-1 4.1. Result codes of the server... 4-1 INDRA. All rights reserved. EDITRAN
1 INTRODUCTION 1. INTRODUCTION The purpose of this document is to explain the functionality developed by EDITRAN that allows signing and verifying files signed in XAdES format, up to the EPES: EDITRAN/XAdES protection level. EDITRAN/XAdES is a Java server that admits requests made from EDITRAN/FF for the signing and verification of the files with the XAdES-EPES signature. For the signature, valid certificates will be all those installed in the USS system in any usergenerated keystore. The verification process includes the extraction of the signed data that will then be processed by the client's applications. This document describes the actions needed to: Install EDITRAN/ XAdES (in the USS part of the z/os). Information on the management of certificates (keystores) Operating mode. INDRA. All rights reserved. EDITRAN Page 1-1
2 INSTALLATION AND REQUIREMENTS 2. INSTALLATION AND REQUIREMENTS The signing and verification provided by EDITRAN are developed as a Java server that will be installed in the z/os Unix services. 2.1. Installation Requirements. At least, IBM 31-bit SDK for z/os, Java Technology Edition, V6 must be installed and have access to JZOS for access to MVS files. The files for this are in $JAVA_HOME/lib/ext. In order to overcome the limitations on the size of the cryptographic keys used in signatures, the restricted policy files US_export_policy.jar and local_policy.jar from the $JAVA_HOME/lib/security directory, with which IBM delivers the SDK, must be replaced for others of unrestricted version that are in $JAVA_HOME/demo/jce/policy-files/unrestricted. A TCP java server, which must have an address and a port to listen to the requests made from the EDITRAN in MVS. Access to ZOS UNIX services. EDItran V5R1F02 minimum version. 2.2. Install in USS. 1. It is recommended to create a directory in the Unix partition of z/os (USS) to install the signature verification software, for example: /u/edixd. 2. To send the XAdES-zos.Vn.n-YYYY-MM-DD.tar package to the USS in binary mode. Any file transfer utility can be used, such as ftp. 3. To connect to the USS and unzip the file into the created directory (u/edixd>tar -xof XAdES-zos.Vn.n-YYYY-MM-DD.tar). A structure will be displayed as in the example below: /u/edixd: >ls -l total 25456 -rw-r----- 1 KI10139 KISNCE 12953600 Apr 28 15:44 XAdES-zos.V2.2-2015-04-28.tar drwxr-xr-x 2 KI1056E KISNCE 8192 Feb 11 10:13 bin drwxr-xr-x 2 KI1056E KISNCE 8192 Apr 29 11:16 conf drwxr-xr-x 2 KI1056E KISNCE 8192 Apr 28 15:37 crl drwxr-xr-x 3 KI1056E KISNCE 8192 Apr 29 11:16 lib drwxr-xr-x 2 KI1056E KISNCE 8192 Apr 28 15:37 logs drwxr-xr-x 2 KI1056E KISNCE 8192 Apr 29 11:16 plantillas drwxr-xr-x 2 KI1056E KISNCE 8192 Apr 29 11:16 politicas drwxr-xr-x 4 KI1056E KISNCE 8192 Feb 13 09:49 rsc The product configuration scripts are in the bin directory and we must ensure that they have write and run permission. These scripts must be modified with the JAVA_HOME directory of the installation. It is also recommended the log folder to have write permission, at least for the user group. 4. Executing /u/edixd/bin/configuracionxades.sh the product configuration will be adapted to the installation itself. The command returns us: INDRA. All rights reserved. EDITRAN Page 2-1
2 INSTALLATION AND REQUIREMENTS Los valores con contrasena (passproxy y passtruststore) se guardan codificados y los demas en claro. Si se quisiera se pueden editar los valores en claro con un editor de texto plano, pero no los valores codificados. Valor del archivo conf/xades.properties #Parametros de EDITRAN/XAdES (Obligatorio) ipeditranxades=127.0.0.1 puertoeditranxades=7760 #TrustStore de las CAs (Obligatorio) pathtruststore=rsc/truststore/truststore.pfx passtruststore=******** #KeyStore por defecto (Opcional) pathkeystore=rsc/keystore/keystore.pfx #Conexion con EDITRAN/OCSP remoto (Opcional, se rellena si se usa EDITRAN/OCSP remoto) ipeditranocsp= puertoeditranocsp= #Conexion con proxy para la conexion a Internet. Es necesario en el caso de querer usar OCSP o CRL para verificar la revocacion #de certificados o para el caso de querer firmar con TimeStamp para lo que se necesita la conexion con un servidor ipproxy= puertoproxy= userproxy= passproxy= #Sistema Operativo donde se instala EDITRAN/XAdES. En el caso de Sistemas Operativos Windows, Unix o AS400, su valor debe ser N(No). #En el caso de Sistemas Operativos z/os, su valor debe ser S(Si) zos=s Modificar las propiedades del fichero conf/xades.properties? (S/N)S By entering S, the parameter values will be requested; only those that need to be modified will have to be entered. It is recommended to use port 7760 for the EDITRAN/XAdES server and to change the TrustStore password (see section 3). If the certificates used in the applications require OCSP validation and this is performed remotely, the EDITRAN/OCSP server is required, and the address and port on which it is installed must be configured. In order to verify the OCSP/CRL of the certificates and also for the signature with TimeStamp to connect to the server that seals the signature time, normally a proxy will be needed to exit the Host. In that case the proxy port and address, as well as a user and password, must be implemented to access the Internet through it. Below is the example dialog where the default truststore and keystore files have been left and no OCSP/CRL validation has been configured: INDRA. All rights reserved. EDITRAN Page 2-2
IP EDITRAN/XAdES: nnn.nnn.nnn.nnn Puerto EDITRAN/XAdES: 7760 Path TrustStore: Password TrustStore: Path KeyStore: IP EDITRAN/OCSP: Puerto EDITRAN/OCSP: IP Proxy: Puerto Proxy: Usuario Proxy: Password Proxy: Sistema Operativo z/os (S/N):S 2 INSTALLATION AND REQUIREMENTS This configuration will be saved in the xades.properties file of the conf directory (in the example: /u/edixd/conf/xades.properties). We describe below all these properties: Mandatory properties: o EDITRAN/XAdES IP: IP where the EDITRAN/XAdES Java Server is started. o EDITRAN/XAdES Port: Port where the EDITRAN/XAdES Java Server is started. o Path of the truststore: It is the path of the certificate store where the TGSS (CA) certificate and all the CAs we must trust are stored. In addition to this store, CAs that are in the installed Windows store are trusted. o Password: Password of the truststore. Optional properties: o Remote EDITRAN/OCSP: Only necessary if we want to use EDITRAN/OCSP remotely. By default it is used locally if we want to verify the certificates: EDITRAN/OCSP IP: IP address of the machine where the Remote EDITRAN/OCSP server is installed and executed. EDITRAN/OCSP Port: Port of the EDITRAN/OCSP server to connect to it. o Proxy: Use of proxy for EDITRAN/XAdES Internet connection. It is necessary in case of verification of certificates both by CRL or OCSP, and also for signing with TimeStamp to connect to the server that seals the signature time: Proxy IP: Proxy port EDITRAN/XAdES needs to connect to. Proxy Port: Proxy port for Internet connection. Proxy User: If necessary, proxy user for Internet connection. Proxy Password: Password of the proxy user. z/os system: Indicates whether the system where the Java program is running is a z/os machine or not. 5. To start and stop the process, use:./start_xades.sh and./stop.sh INDRA. All rights reserved. EDITRAN Page 2-3
3 INSTALLATION OF CERTIFICATES 3. INSTALLATION OF CERTIFICATES The certificates used in EDITRAN/XAdES are stored, depending on their use, in two files: TrustStore, for the certificates of the CAs we must trust, and keystore, for the signatories' certificates.. 3.1. Truststore File In the installation of EDITRAN/XAdES a TrustStore file, truststore.pfx is provided in the /rsc/truststore/ folder (in the example /u/edixd/rsc/rsc/truststore/truststore.pfx), with several CAs already built in. The CA incorporated are those of the DNI, EDITRAN, FNMT and TGSS. This store is of type PKCS12, but it does not contain keys, only certificates that are public. To change the password of this file ("password" by default), it will be transmitted in binary to Windows, it will be managed with a suitable tool - for example Portecle http://portecle.sourceforge.net/ - and it will be resent to USS. In addition to the truststore, the certificates for some of the CAs included in the truststore are attached. With these certificates we can create our own truststore file using the utilities provided by the IBM Java installation (keytool, ikeyman) with the limitations for PKCS12 type keystores in password management. It is advisable to use the above-mentioned tool to incorporate or delete CA. 3.2. Keystore File The keystore file is a file containing one or more certificates that will be used for signing. The certificates are obtained by the user of the application and should be stored in a USS folder or incorporated into one or more keystores whose path must be configured in each EDITRAN/FF user (see manual EFF51USUI.doc IMS - and EFF51USUC.doc CICS-) or, if there is only one, in the default path (running ConfiguracionXades.sh, located in the bin directory). To configure this type of stores, the processing file by FicheroKeyStores.sh batches, located in the bin directory must be executed. This configuration is saved in the file FicheroKeyStores.sh in the conf directory (/u/edixd/conf/feykeystores.txt file). When running the program, if the file already exists, it shows the values that we already have saved. Otherwise, they will be blank: The options we have are to save a new key (G), delete an existing key (B) or do nothing (N). The data to be saved for each signatory are: Keystore Path: Keystore path where the signatory's key pair is stored. Keystore Password: Password of the keystore. Alias: Alias of the key pair we want to use to sign. Key password: Password of the key. It can be the same as that of the keystore. In this case is left blank. To be able to test the product without our own certificates, the keystore.pfx file in the rsc/keystore directory is also attached with a test certificate (in the example: /u/edixd/rsc/keystore/keystore/keystore.pfx); the alias of the saved certificate is "XAdES test certificate" (password: "password"). INDRA. All rights reserved. EDITRAN Page 3-1
3 INSTALLATION OF CERTIFICATES This store is already configured in the FicheroKeyStores.txt file and is the default keystore file in the initial configuration. 3.3. Configuration of the certificate revocation status query The use of the revocados.properties file, located in the conf folder, allows enlarging the places where the revocation status of the certificates can be queried with respect to the information that the certificate contains. This facility has been implemented in order to make use of those certificates that do not provide this information in a self-sufficient way; for example, when they include the name of the crl list, but not the address where to query it. The contents of the file can have as many blocks as needed, as follows: nombre.ca.0=nombre CA ldap.0= ocsp.0= crl.0.0= crl.0.1= crl.0.2= A keyword must be entered in the "name.ca.n=" record that identifies all certificates issued by the same CA. They can be found both in the DN of the issuer of the signatory certificate and in all the DNs of the certificates of the certificate path, e.g. "FMNT", "DNIE", "SWIFT", etc. In the "ocsp.0=" record, enter the URL to connect to the OCSP server, for example http://ocsp.dnie.es. In the "ldap.0=" record, enter the LDAP address to connect to the server. Where such information is already included in the certificate, it need not be indicated. In the "crl.0.n=" records, as many as are necessary for each CA will be referred to, addresses will be indicated where the CRL list and even simply the names of the CRLs will be queried. In this case, the list must be downloaded in the crl subfolder. The query is first made where the certificate indicates. If the information is not selfsufficient and the search cannot be performed, then the downloaded list is searched in the crl folder. If it is not there either, continue to search in the places indicated in the revocados.properties file, in the same order in which the entries of the corresponding CA appear (according to the example, search first in ocsp.0, then in crl.0.0, crl.0.1, etc.). 3.4. Authentication of the LDAP Server If the LDAP Server requests authentication, the LDAP authentication script can be run in the bin folder. This will allow LDAP addresses that are already registered in the revocados.properties file to add a username and password if necessary. This program only INDRA. All rights reserved. EDITRAN Page 3-2
3 INSTALLATION OF CERTIFICATES edits the LDAP addresses in that file, so we must first fill in the LDAP address before running it. INDRA. All rights reserved. EDITRAN Page 3-3
EDITRAN/XAdES z/os. Installation Manual 4 ANNEX A 4. ANNEX A 4.1. Result codes of the server Correct results 00- Correct certificate 01- Warning. It was not found or it was not possible to connect to the OCSP or CRL Url in the certificate. This warning occurs with a certificate that has been asked for OCSP verification and it has not been able to do it whether it is revoked or not. It is up to the customer to treat this code as an error or not. By default it is valid even if a warning is triggered. 02- Warning. The signature has been made with Warnings. This may occur when signing a document in a format other than the one originally requested because the requested format cannot be used. Signature verification errors 10- Signature policy included. The policy has not been implemented. 11- There is no trust in one of the signatory certificates, invalid CA 12- OCSP server returns incorrect certificate(s) 13- OCSP server or CRL list returns revoked certificate(s) 14- Expired certificate(s) 15- Modified document 16- Unauthorized signatory(ies) in the account (This is a further validation of the signature against the EDITRAN/XAdES profiles). Reading the data of the connection with the EDITRAN/XAdES Java Server 17- Request not built correctly 18- Error when reading the length of the frame from the reading buffer 19- Unrecognized petitioner function 20- Unrecognized type of signature 21- Unrecognized source machine language 22- Unrecognized CRLS validation value 23- Unrecognized zip value 24- Unrecognized encryption value 25- Unrecognized conversion value to base 64 26- Unrecognized input file identifier 27- Unrecognized external detached file identifier 28- Unrecognized output file identifier 29- The path of the input file must be greater than 0 30- The path of the external detached file must be greater than 0 31- The output file path must be greater than 0 32- The path of the DN output file must be greater than 0 33- The keystore path must be greater than or equal to 0 34- The alias or DN of the certificate must be greater than 0 35- No signatory certificate has been reported 36- Unrecognized template identifier 37- The name of the template must be greater than 0 38- The geographical place must be greater than or equal to 0 39- The signatory's role must be greater than 0 40- The signatory's action must be greater than 0 41- Failure to read the xades.properties configuration file INDRA. All rights reserved. EDITRAN Page 4-1
EDITRAN/XAdES z/os. Installation Manual 4 ANNEX A Reading the signed file 48- Error when reading the source file 49- Error when parsing the xml of the source file 50- The Signature element is not found in the document 51- Error when parsing the Signature element 52- Error in the signature validation process 53- Error obtaining invalid signature information 54- The certificate signed inside the document has not been found. 55- Error reading the truststore Output file writing 64- Error when writing the destination file 65- Error when writing the dn file OCSP and CRL validation 80- Error when encoding the certificate 81- EDITRAN/OCSP connection error 82- EDITRAN/OCSP error when reading the Connection Message 83- The versions do not correspond to each other 84- EDITRAN/OCSP Error when writing Connection Answer 85- EDITRAN/XAdES Error when reading Connection Answer 86- EDITRAN/OCSP Error when reading the Request Message 87- EDITRAN/OCSP cannot connect OCSP Server 88- Error when trying to find the CRL list of the certificate File signature 96- Error reading the keystore 97- The keystore key could not be extracted 98- The template is incorrect 99- The Signed Info element could not be created 100- The KeyInfo element could not be created 101- The QualifyingProperties element could not be created 102- Incorrect URL for the signature TimeStamp 103- The signatory for the counter-signature has not been found 104- Error when signing Memory error 112- OutOfMemoryError (When this error occurs, the memory allocation parameters that are in the start_xades.bat file of the bin folder must be increased). Unexpected error 113- Unexpected error in the Java EDITRAN/XAdES server. Undefined error 114- Value not defined. It should not be attainable (This value should never occur, it is the value assigned to the program input. INDRA. All rights reserved. EDITRAN Page 4-2
EDITRAN/XAdES z/os. Installation Manual 4 ANNEX A ecommerce Competence Centers Avda. de Bruselas 35 28108 Alcobendas. Madrid, Spain T. +34 91 480 80 80 T. +34 91 480 50 00 www.indracompany.com INDRA. Todos los derechos reservadoseditran Pág. 4-1