Magazyn certyfikatów dostępny jest w postaci znacznik <LocalStore>. Znacznik ten zawiera elementy z zakodowanymi w Base64 certyfikatami podmiotów świadczących usługi certyfikacyjne <CACertificate> oraz adresy HTTP/HTTPS/LDAP wskazujące na podmioty udzielające informacji na temat ważności certyfikatów w formie list CRL lub odpowiedzi OCSP.

<LocalStore>
 
<CACertificate><!-- [ 02 ] PL
	VALIDITY: 2002-06-11 => 2027-06-11
	SUBJECT : C=PL; O=Unizeto Sp. z o.o.; CN=Certum CA
	ISSUER  : C=PL; O=Unizeto Sp. z o.o.; CN=Certum CA
	SERIAL  : 010020
--><X509Certificate>
MIIDDDCCAfSgAwIBAgIDAQAgMA0GCSqGSIb3DQEBBQUAMD4xCzAJBgNVBAYTAlBMMRswGQYDVQQKExJVbml6ZXRvIFNwLiB6IG8uby4xEjAQBgNVBAMTCUNlcnR1bSBDQTAeFw0wMjA2MTExMDQ2MzlaFw0yNzA2
MTExMDQ2MzlaMD4xCzAJBgNVBAYTAlBMMRswGQYDVQQKExJVbml6ZXRvIFNwLiB6IG8uby4xEjAQBgNVBAMTCUNlcnR1bSBDQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAM6xwS7TT3zNJc4YPk/E
jG+AanPIW1H4m9LcuwBcsaD8dQPugfCI7iNS6eYVM42sLQnFdvkrOYCJ5JdLkKWoePhzQ3ukYbDYWMzhbGZ+nPMJXlVjhNWo7/OxLjBos8Q82KxujZlakE403Daaj4GIULdtlkIJ89eVgw1BS7Bqa/j8D35in2fE
7SZfECYPCE/wpFcozo+47UX2bu4lXapuOb7kky/ZR6By6/qmW6/KUz/iDsaWVhFu9+lmqSbYf5VT7QqFiLpPKaVCjF62/IUgAKpoC6EahQGcxEZjgoi2IrHu/qpGWX7PNSzVttpd90gzFFS269lvzs2I1qsb2pY7
HVkCAwEAAaMTMBEwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAuI3O7+cUus/usESSbLQ5PqKEbq24IXfS1HeCh+YgQYHu4vgRt2PRFze+GXYkHAQaTOs9qmdvLdTN/mUxcMUbpgIKumB7bVjC
mkn+YzILa+M6wKyrO7Do0wlRjBCDxjTgxSvgGrZgFCdsMneMvLJymM/NzD+5yCRCFNZX/OYmQ6kd5YCQzgNUKD73P9P4Te1qCjqTE5s7FCMTY5w/0YcneeVMUeMBrYVdGjux1XMQpNPyvG5k9VpWkKjHDkx0Dy5x
O/fIR/RpbxXyEV6DHpx8Uq79AtoSqFlnGNu8cN2bsWntgM6JQEhqDjXKKWYVIZQs6GAqm4VKQPNriiTsBhYscw==</X509Certificate>
	<CRLAddress>https://crl.certum.pl/ca.crl</CRLAddress>
</CACertificate>
 
...
 
</LocalStore>

W celu skorzystania z certyfikatu programowego (niekwalifikowanego) należy wygenerować własny certyfikat oraz umieścić odwołanie do niego wraz z kluczem publicznym w pliku konfiguracyjnym settings_cryptoproviders.

1. Aby programowo wygenerować własny certyfikat należy mieć na komputerze zainstalowane środowisko java (jre lub jdk). Należy wejść do katalogu bin, np. d:\PlusWorkflow\Java\jdk1.8.0_161\bin\ i wydać polecenie:

   Code Block
   keytool -genkeypair -keystore certyfikat.p12 -storetype PKCS12 -storepass suncode -alias certyfikat -keyalg RSA -keysize 2048 -validity 99999 -dname "CN=Imie Nazwisko, O=Suncode, L=Poznan, ST=Wlkp, C=PL"

2.  Aby z wygenerowanego certyfikatu pobrać klucz publiczny należy wykonać następujące polecenie:

   Code Block
   keytool -exportcert -keystore certyfikat.p12 -storepass suncode -alias certyfikat -rfc -file public-certificate.pem

3. W celu podłączenia wygenerowanego certyfikatu do pliku konfiguracyjnego settings_cryptoproviders należy dodać klucz publiczny w sekcjach: <CACertificate> <X509Certificate>

   Code Block
   <!-- <LocalStore> ... --> <CACertificate> <X509Certificate> {tekstowa zawartosc pliku public-certificate.pem} </X509Certificate> <CRLAddress>http://crl.omniroot.com/ctglobal.crl</CRLAddress> </CACertificate> <!-- ... </LocalStore> -->

4. A następnie w sekcji <SoftwareProvider> dodać wskazanie na wygenerowany wcześniej certyfiakt:

   Code Block
   <!-- <CryptoProviders> ... --> <SoftwareProvider> <Name>PKCS#12</Name> <URI>file:///d:/Certyfikaty/certyfikat.p12</URI> </SoftwareProvider> <!-- ... </CryptoProviders> -->

   Info
   title UWAGA
   Podane przy generowaniu certyfikatu hasło w parametrze storepass (suncode) jest PIN'em, który należy podać przy podpisywaniu dokumentów.

Adresy list CRL dla poszczególnych certyfikatów zawarte są w znaczniku <CRLAddress> umieszczonym w kontenerze <CACertificate>. Dla każdego podmiotu możliwe jest również dołączenie adresów z historycznymi listami CRL, za pomocą elementu <HistoricalCRLAddress> umieszczonego za elementem <CRLAddress> Każda z lokalizacji list CRL musi być zapisana w postaci zgodnej z URI. W przypadku gdy CA nie obsługuje CRL należy ustawić wartość <CRLAddress>NO_CRLDISTRIBUTIONPOINT</CRLAddress>.

Wskazanie na adres usługi OCSP dla poszczególnych urzędów certyfikacji odbywa się poprzez znacznik <OCSPAddress>, umieszczony za elementami wskazującymi na listy CRL w kontenerze <CACertificate>. Lokalizacja usługi OCSP musi być zapisana w postaci zgodnej z URI (HTTP/HTTPS). Dodatkowo, za sekcją <LocalStore> musi pojawić się wpis <UseOCSPOverCRL>true</UseOCSPOverCRL>; w przypadku jego braku, komponenty Szafir SDK będą używały list CRL. Jeśli usługa OCSP będzie niedostępna, wykorzystywane będą listy CRL.

Sekcja <Signing> pozwala na wybranie odpowiedniego rodzaju certyfikatu lub bezpośrednio certyfikatu używanego do składania podpisu elektronicznego, poprzez odfiltrowanie pozostałych certyfikatów. Domyślnie nie ma ograniczeń na certyfikat (<AnyCertificate>). Możliwe są ponadto opcje:

• <AnyQualifiedCertificate> - dowolny kwalifikowany certyfikat
• <AnyNonQualifiedCertificate> - dowolny niekwalifikowany certyfikat
• <OneCertificate> - jeden certyfikat, identyfikowany za pomocą <Issuer> (wystawca w postaci DN, po przecinkach) oraz <Serial> (numer seryjny w postaci DEC – dziesiętnej – można odczytać go przy pomocy Szafir bezpośrednio, lub z poziomu Windows, konwertując z HEX do DEC przy użyciu kalkulatora Windows).

<Signing>
	<SigningCertificate>
		<OneCertificate>
			<Issuer>organizationIdentifier=VATPL-5260300517,CN=COPE SZAFIR -Kwalifikowany,O=Krajowa Izba Rozliczeniowa S.A.,C=PL</Issuer>
			<Serial>Numer_seryjny _certyfikatu_w_postaci_DEC</Serial>
		</OneCertificate>
	</SigningCertificate>
</Signing>

Parametry usługi znakowania czasem konfigurowane są w znaczniku <TimeStamping>. Znacznik <TimeStampingCertificate>, analogicznie jak <SigningCertificate>, określa rodzaj certyfikatu używanego do podpisywania żądania oznaczenia czasem. Żądanie znakowania czasem jest podpisywane w celach identyfikacji subskrybenta usługi. Możliwe jest wyłączenie podpisywania żądań znakowania czasem, poprzez ustawienie wartości atrybutu Authorization=”false” znacznika <TimeStamping>. Gwarantowana jest obsługa procesu znakowania czasem dokumentów znacznikiem czasu wydanym przez KIR. W przypadku korzystania z usług znakowania czasem KIR S.A., atrybut Authorization musi mieć wartość domyślną „true”. Znacznik <Host> określa adres usługi znakowania czasem. Ujęcie sekcji <TimeStamping> w komentarz blokuje wykorzystanie usługi.

<TimeStamping Authorisation="true">
	<TimeStampingCertificate>
		<AnyCertificate />
	</TimeStampingCertificate>
	<!-- KIR Szafir TSA -->
	<Host>http://www.ts.kir.com.pl/HttpTspServer</Host>
	<!-- Certum Public QLTS -->
	<!-- <Host>http://public-qlts.certum.pl</Host> -->
	<!-- CUZ Sigillum QTSA1 -->
	<!-- <Host>http://tsa.sigillum.pl</Host> -->
</TimeStamping>

Konfiguracja dostawców kryptografii odbywa się w sekcji znacznika <CryptoProviders>. Komunikacja z urządzeniami kryptograficznymi (karta kryptograficzna lub moduł kryptograficzny HSM) odbywa się z wykorzystaniem interfejsu PKCS#11 i stosuje się znacznik <HardwareProvider>. W istniejącej konfiguracji settings_cryptoproviders domyślnie zdefiniowany jest sprzętowy dostawca kryptografii do obsługi kart kryptograficznych CryptoTech Carbon, CryptoTech Graphite oraz CryptoTech CloudSigner:

<CryptoProviders>
 
<!-- PKCS11 KIR Carbon -->

<HardwareProvider>
	<Name>PKCS#11 Type A</Name>
	<URI>CCP11s.dll</URI>
</HardwareProvider>

<!-- PKCS11 KIR Graphite -->

<HardwareProvider>
	<Name>PKCS#11 Type A</Name>
	<URI>CCGraphitep11.dll</URI>
</HardwareProvider>

<!-- PKCS11 KIR mSzafir -->

<HardwareProvider>
 	<Name>PKCS#11 Type A</Name>
 	<URI>file:///c:/Program%20Files/CryptoTech/CryptoCard/CloudSignerP1164.dll</URI>
</HardwareProvider>
<HardwareProvider>
 	<Name>PKCS#11 Type A</Name>
 	<URI>file:///c:/Program%20Files%20(x86)/CryptoTech/CryptoCard/CloudSignerP11.dll</URI>
</HardwareProvider>
 
</CryptoProviders>

Możliwe jest używanie wielu różnych dostawców kryptografii poprzez wskazanie wielu znaczników <HardwareProvider>.

Standard kryptografii klucza publicznego PKCS#12 pozwala na użycie plików w formacie .p12 lub .pfx, które przechowują klucz prywatny i certyfikaty. Definicja tego wariantu odbywa się przy pomocy znacznika <SoftwareProvider>.

<CryptoProviders>
 
<SoftwareProvider>
	<Name>PKCS#12</Name>
	<URI>file:///c:/example.p12</URI>
</SoftwareProvider>


</CryptoProviders>

Elementy URI dostawców kryptografii muszą zawierać wpisy zgodne ze standardem URI. Obecnie dla dostawców kryptografii wspierane są URI wskazujące na pliki lokalne (file:///) oraz zasoby sieciowe (http:// i https://). Możliwe jest używanie URI względnych, należy jednak pamiętać, aby biblioteki umieścić w ścieżce widocznej pod System.getProperty(„java.library.path”) maszyny wirtualnej Java.

Dla biblioteki w standardzie PKCS#12 alternatywną formą do podania ścieżki URI jest podanie całego pliku w postaci zakodowanej w Base64.

<SoftwareProvider>
	<Name>PKCS#12</Name>
	<Base64Binary>JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRs</Base64Binary>
</SoftwareProvider>

Komponenty Szafir SDK domyślnie nie pozwalają na wykorzystanie certyfikatów kwalifikowanych w trybie działania innym niż natywne okno Szafir. Niemniej jednak jeśli Integrator chce zaimplementować własny sposób prezentacji danych, może wykorzystać certyfikaty kwalifikowane używając inny tryb działania niż okno Szafir poprzez następujące ustawienie w pliku znacznika <AllowNonWindowForQC>.

<Settings>
	…
	<Algorithms>……..</Algorithms>
	<AllowNonWindowForQC>true</AllowNonWindowForQC>
</Settings>

The certificate store is available in the form of the <LocalStore> tag. This tag contains elements with Base64 encoded certificates of certification service providers <CACertificate> and HTTP / HTTPS / LDAP addresses pointing to entities providing information on the validity of certificates in the form of CRL lists or OCSP responses.

<LocalStore>
 
<CACertificate><!-- [ 02 ] PL
	VALIDITY: 2002-06-11 => 2027-06-11
	SUBJECT : C=PL; O=Unizeto Sp. z o.o.; CN=Certum CA
	ISSUER  : C=PL; O=Unizeto Sp. z o.o.; CN=Certum CA
	SERIAL  : 010020
--><X509Certificate>
MIIDDDCCAfSgAwIBAgIDAQAgMA0GCSqGSIb3DQEBBQUAMD4xCzAJBgNVBAYTAlBMMRswGQYDVQQKExJVbml6ZXRvIFNwLiB6IG8uby4xEjAQBgNVBAMTCUNlcnR1bSBDQTAeFw0wMjA2MTExMDQ2MzlaFw0yNzA2
MTExMDQ2MzlaMD4xCzAJBgNVBAYTAlBMMRswGQYDVQQKExJVbml6ZXRvIFNwLiB6IG8uby4xEjAQBgNVBAMTCUNlcnR1bSBDQTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAM6xwS7TT3zNJc4YPk/E
jG+AanPIW1H4m9LcuwBcsaD8dQPugfCI7iNS6eYVM42sLQnFdvkrOYCJ5JdLkKWoePhzQ3ukYbDYWMzhbGZ+nPMJXlVjhNWo7/OxLjBos8Q82KxujZlakE403Daaj4GIULdtlkIJ89eVgw1BS7Bqa/j8D35in2fE
7SZfECYPCE/wpFcozo+47UX2bu4lXapuOb7kky/ZR6By6/qmW6/KUz/iDsaWVhFu9+lmqSbYf5VT7QqFiLpPKaVCjF62/IUgAKpoC6EahQGcxEZjgoi2IrHu/qpGWX7PNSzVttpd90gzFFS269lvzs2I1qsb2pY7
HVkCAwEAAaMTMBEwDwYDVR0TAQH/BAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEAuI3O7+cUus/usESSbLQ5PqKEbq24IXfS1HeCh+YgQYHu4vgRt2PRFze+GXYkHAQaTOs9qmdvLdTN/mUxcMUbpgIKumB7bVjC
mkn+YzILa+M6wKyrO7Do0wlRjBCDxjTgxSvgGrZgFCdsMneMvLJymM/NzD+5yCRCFNZX/OYmQ6kd5YCQzgNUKD73P9P4Te1qCjqTE5s7FCMTY5w/0YcneeVMUeMBrYVdGjux1XMQpNPyvG5k9VpWkKjHDkx0Dy5x
O/fIR/RpbxXyEV6DHpx8Uq79AtoSqFlnGNu8cN2bsWntgM6JQEhqDjXKKWYVIZQs6GAqm4VKQPNriiTsBhYscw==</X509Certificate>
	<CRLAddress>https://crl.certum.pl/ca.crl</CRLAddress>
</CACertificate>
 
...
 
</LocalStore>

In order to use a software (non-qualified) certificate, you need to generate your own certificate and place a reference to it along with the public key in the settings_cryptoproviders configuration file.

1. To programmatically generate your own certificate, you must have java (jre or jdk) installed on your computer. Enter the bin directory, e.g. d:\PlusWorkflow\Java\jdk1.8.0_161\bin\ and run the command:

   Code Block
   language text
   keytool -genkeypair -keystore certyfikat.p12 -storetype PKCS12 -storepass suncode -alias certyfikat -keyalg RSA -keysize 2048 -validity 99999 -dname "CN=Imie Nazwisko, O=Suncode, L=Poznan, ST=Wlkp, C=PL"

2. To retrieve the public key from the generated certificate, run the following command:

   Code Block
   language text
   keytool -exportcert -keystore certyfikat.p12 -storepass suncode -alias certyfikat -rfc -file public-certificate.pem

3. In order to connect the generated certificate to the settings_cryptoproviders configuration file, add the public key in the sections: <CACertificate> <X509Certificate>

   Code Block
   language xml
   <!-- <LocalStore> ... --> <CACertificate> <X509Certificate> {tekstowa zawartosc pliku public-certificate.pem} </X509Certificate> <CRLAddress>http://crl.omniroot.com/ctglobal.crl</CRLAddress> </CACertificate> <!-- ... </LocalStore> -->

4. And then in the <SoftwareProvider> section, add an indication of the previously generated certificate:

   Code Block
   language xml
   <!-- <CryptoProviders> ... --> <SoftwareProvider> <Name>PKCS#12</Name> <URI>file:///d:/Certyfikaty/certyfikat.p12</URI> </SoftwareProvider> <!-- ... </CryptoProviders> -->

   Info
   title Warning
   The password provided when generating the certificate in the storepass (suncode) parameter is the PIN that should be entered when signing the documents.

CRL addresses for individual certificates are contained in the <CRLAddress> tag located in the <CACertificate> container. For each entity, it is also possible to include addresses with historical CRLs, using the <HistoricalCRLAddress> element behind the <CRLAddress> element. Each of the CRL locations must be written in a form compatible with the URI. If the CA does not support CRL, set the value to <CRLAddress>NO_CRLDISTRIBUTIONPOINT</CRLAddress>.

Indicating the address of the OCSP service for individual certification authorities is done through the <OCSPAddress> tag, placed after the elements pointing to the CRL lists in the <CACertificate> container. The location of the OCSP service must be written in a URI compliant form (HTTP/HTTPS). Additionally, the <LocalStore> section must be followed by an entry <UseOCSPOverCRL>true</UseOCSPOverCRL>; in its absence, the Szafir SDK components will use CRL lists. If the OCSP service is unavailable, CRLs will be used.

The <Signing> section allows you to select the appropriate type of certificate or directly the certificate used to create the electronic signature by filtering the remaining certificates. By default, there is no restriction on the certificate (<AnyCertificate>). There are also options:

• <AnyQualifiedCertificate> - any qualified certificate
• <AnyNonQualifiedCertificate> - any unqualified certificate
• <OneCertificate> - one certificate, identified with <Issuer> (issuer in the form of DN, after commas) and <Serial> (serial number in the form of DEC - decimal - you can read it with Szafir directly or from Windows, converting from HEX to DEC using a Windows calculator).

<Signing>
    <SigningCertificate>
        <OneCertificate>
            <Issuer>organizationIdentifier=VATPL-5260300517,CN=COPE SZAFIR -Kwalifikowany,O=Krajowa Izba Rozliczeniowa S.A.,C=PL</Issuer>
            <Serial>Certificate_serial_number_in_the_form_of_the_DEC</Serial>
        </OneCertificate>
    </SigningCertificate>
</Signing>

Time stamping service parameters are configured in the <TimeStamping> tag. The <TimeStampingCertificate> tag, like <SigningCertificate>, specifies the type of certificate used to sign the timestamp request. Marking request sometimes it is signed to identify the subscriber to the service. You can disable the signing of time stamping requests by setting the Authorization = "false" attribute of the <TimeStamping> tag. Support for the process of time-stamping documents with a time stamp issued by KIR is guaranteed. When using the KIR S.A. time stamping services, the Authorization attribute must have a default value of "true". The <Host> tag specifies the address of the time stamping service. Commenting the <TimeStamping> section blocks the service usage.

<TimeStamping Authorisation="true">
    <TimeStampingCertificate>
        <AnyCertificate />
    </TimeStampingCertificate>
    <!-- KIR Szafir TSA -->
    <Host>http://www.ts.kir.com.pl/HttpTspServer</Host>
    <!-- Certum Public QLTS -->
    <!-- <Host>http://public-qlts.certum.pl</Host> -->
    <!-- CUZ Sigillum QTSA1 -->
    <!-- <Host>http://tsa.sigillum.pl</Host> -->
</TimeStamping>

Cryptography providers are configured in the <CryptoProviders> tag section. Communication with cryptographic devices (cryptographic card or HSM cryptographic module) takes place using the PKCS#11 interface and the <HardwareProvider> tag is used. In the existing settings_cryptoproviders configuration, a hardware cryptography provider is defined by default to support CryptoTech Carbon, CryptoTech Graphite and CryptoTech CloudSigner cryptographic cards.

<CryptoProviders>
  
<!-- PKCS11 KIR Carbon -->
 
<HardwareProvider>
    <Name>PKCS#11 Type A</Name>
    <URI>CCP11s.dll</URI>
</HardwareProvider>
 
<!-- PKCS11 KIR Graphite -->
 
<HardwareProvider>
    <Name>PKCS#11 Type A</Name>
    <URI>CCGraphitep11.dll</URI>
</HardwareProvider>
 
<!-- PKCS11 KIR mSzafir -->
 
<HardwareProvider>
    <Name>PKCS#11 Type A</Name>
    <URI>file:///c:/Program%20Files/CryptoTech/CryptoCard/CloudSignerP1164.dll</URI>
</HardwareProvider>
<HardwareProvider>
    <Name>PKCS#11 Type A</Name>
    <URI>file:///c:/Program%20Files%20(x86)/CryptoTech/CryptoCard/CloudSignerP11.dll</URI>
</HardwareProvider>
  
</CryptoProviders>

It is possible to use many different cryptography providers by specifying multiple <HardwareProvider> tags.

The PKCS # 12 public key cryptography standard allows the use of .p12 or .pfx files that store the private key and certificates. This variant is defined using the <SoftwareProvider> tag.

<CryptoProviders>
  
<SoftwareProvider>
    <Name>PKCS#12</Name>
    <URI>file:///c:/example.p12</URI>
</SoftwareProvider>
</CryptoProviders>

Cryptography provider URIs must contain URI-compliant entries. Currently, URIs pointing to local files (file:///) and network resources (http:// and https://) are supported for cryptography providers. It is possible to use relative URIs, but remember to put the libraries in the path shown under System.getProperty ("java.library.path") in the Java Virtual Machine.

For the library in the PKCS#12 standard, an alternative form of specifying the URI path is to specify the entire file in Base64 encoded form.

<SoftwareProvider>
    <Name>PKCS#12</Name>
    <Base64Binary>JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRs</Base64Binary>
</SoftwareProvider>

Szafir SDK components by default do not allow the use of qualified certificates in a mode of operation other than the native Szafir window. However, if Integrator wants to implement its own data presentation method, it can use qualified certificates using a different operating mode than the Szafir window by setting the <AllowNonWindowForQC> tag file as follows.

<Settings>
    …
    <Algorithms>……..</Algorithms>
    <AllowNonWindowForQC>true</AllowNonWindowForQC>
</Settings>