TÜBİTAK MA3 API’yi kullanarak sistemlerimize e-İmza entegrasyonu yapmak istiyorum, API’yi nasıl temin edebilirim?

“yazilim.kamusm.gov.tr” adresindeki "Elektronik imza kütüphaneleri" kısmından MA3 API’nin en güncel versiyonunu indirip kod geliştirmeye başlayabilirsiniz.

“Lisans kontrolü başarısız” ('tr.gov.tubitak.uekae.esya.api.common.license.LV' tür başlatıcısı özel durum döndürdü.) hatasını almaktayım, çözümü için nasıl bir yol izlemeliyim?

API’nin çalışması için lisans dosyası gerekmektedir. Lisans dosyasının geçerlilik süresi 5 yıldır ve ücretsiz olarak verilmektedir. Lisans dosyası XML olarak API’nin içerisinde bulunmaktadır. Bu hatanın giderilmesi için lisans dosyasının kod içerisinden ayarlanması gerekmektedir.

MA3 API bundle’ının içerisindeki “lisans.xml” dosyası aşağıda gösterildiği gibi tanıtılmalıdır.

.NET API’de kullanılan örnek kod:
LicenseUtil.setLicenseXml(new FileStream(@"d:\lisans\Full_lisans.xml", FileMode.Open, FileAccess.Read));

Java API’de kullanılan örnek kod:
LicenseUtil.setLicenseXml(new FileInputStream("D:\\lisans\\Full_lisans.xml"));

“Kartta nitelikli sertifika bulunamadı” hatasını almaktayım, çözümü için nasıl bir yol izlemeliyim?

İçinde hiç nitelikli sertifika olmayan bir karttan, nitelikli sertifika getirilmeye çalışıldığında bu hata alınmaktadır. Takılı olan kartın içerisinde mali mühür ya da niteliksiz başka bir sertifika olabilir. Nitelikli veya niteliksiz sertifikaların getirilme tercihi SmartCardManager ve JSmartCardManager sınıflarında bulunan “getSignatureCertificate” metodunun boolean parametreleriyle ayarlama yapılarak sağlanır. (true,false) parametreleri verildiğinde yalnızca nitelikli sertifikalar, (false,true) parametreleri verildiğinde yalnızca niteliksiz sertifikalar, (false,false) verildiğinde ise hem nitelikli hem niteliksiz sertifikalar çekilmektedir. Yalnızca Nitelikli Elektronik Sertifikalarla çalışması gereken canlı sistemlerde (Elektronik Belge Yönetim Sistemi, Hastane Bilgi Yönetim Sistemi vb.) (true,false) paramereleriyle kullanılması gerekmektedir.

"İlklendirme için "config" yüklenemedi!" hatası almaktayım, çözümü için nasıl bir yol izlemeliyim?

Bu hata, MA3 API’nin konfigürasyon dosyalarına (policy, config) erişememesinden kaynaklanmaktadır. Politika dosyalarının yolları;

XAdES API’de “xmlsignature-config.xml“ içerisinden gösterilir. Bu XML dosyası, context oluşturulduktan sonra
context.config=new config(@"d:\proje\config\xmlsignature-config.xml");

Ortak (Common) API’de “esyasignature-config.xml“ içerisinden gösterilir. Bu XML dosyası, context oluşturulduktan sonra
context.config=new config(@"d:\proje\config\esyasignature-config.xml");

şeklinde girilmeli ve bu XML dosyası içerisinden iki adet politika dosyasının yolu doğru bir biçimde ayarlanmalıdır. XML yapısı bozulmuş “config” ya da “policy” dosyaları kullanıldığında da ilgili hata alınabilir.

“xmlsignature-config.xml” içerisinden politika dosyalarının yolu aşağıdaki gibi ayarlanabilir.
<certificate-validation-policy-file>d:/proje/config/certval-policy-test.xml</certificate-validation-policy-file>
<certificate-validation-policy-file for="MaliMuhurCertificate"> d:/proje/config/certval-policy-malimuhur.xml</certificate-validation-policy-file>

MA3 API’de imza oluşturma sırasında “Sertifika Zinciri tamamlanamadı, Güvenilir Kök bulunamadı!” hatası almaktayım, çözümü için nasıl bir yol izlemeliyim?

Bu hata, imza oluşturulurken kullanılan sertifikanın kök sertifikasının API tarafından kabul edilen bir kök olmamasından kaynaklanmaktadır.

Test Ortamında hata ile karşılaşılması durumunda

Test için üretilmiş olan sertifikalar ve test zaman damgası (“http://tzd.kamusm.gov.tr”) güvenilir bir kök tarafından üretilmemiştir. Bu sebeple test sertifikalarıyla imza oluşturulması ya da sertifikalarla oluşturulmuş imzaların doğrulanması sırasında ilgili hata alınır. Test ortamında imza oluşturma testlerinin ve imza doğrulama testlerinin yapılabilmesi adına (gerçek ortamda kaldırılmak üzere) test sertifikaları da güvenilir olarak API’ye tanıtılmalıdır.

API’ye test sertifikasının kökünün güvenilir olarak gösterilmesi için adımlar aşağıda anlatılmaktadır:

• Öncelikle test kök sertifikası bulunarak indirilmelidir. (Eğer test sertifikası Kamu SM’den alınmışsa "http://www.kamusm.gov.tr/hizmetler/test_sistemi/” den bulunarak indirilmelidir.
• İndirilen test kökü “C:\trustedsha2” gibi bir klasöre atılmalıdır.
• Bundle’ın içerisinde config klasöründe bulunan policy.xml dosyaları açılarak trustedcertificate tag’leri arasına dosya yolu bir önceki adımda oluşturulmuş klasörü gösterecek şekilde aşağıdaki koyu blok eklenmelidir.
  <trustedcertificate> <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation. find.certificate.trusted. TrustedCertificateFinderFromECertStore"/> <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation. find.certificate.trusted. TrustedCertificateFinderFromFileSystem"> <param name="dizin" value="C:\trustedsha2"/> </class> </trustedcertificate>

Gerçek Ortamda hata ile karşılaşılması durumunda

Hatanın sebebi:

• Elektronik Sertifika Hizmet Sağlayıcılar tarafından yeni bir sertifikanın üretilmiş olması

  Güncel SertifikaDeposu.svt de ESHS tarafından yeni yayınlanmış olan kökün bulunmaması durumunda yazilim@kamusm.gov.tr ye depoya eklenmesi gereken kökü bildirebilirsiniz.

• Güvenilir kök dosyasının sistemde bulunmaması ya da bir şekilde silinmiş olmasıdır.

  API güvenilir köklere sertifika deposundan bakmaktadır. Sertifikadeposu da “c:\users\....\.sertifikadeposu\” içerisinde sertifikadeposu.svt dosyasıdır. Hatanın alınması halinde depo.kamusm.gov.tr adresinden güncel sertifikadeposu.svt dosyası indirilerek “c:\users\....\.sertifikadeposu” dizinine kopyalanmalıdır. SertifikaDeposu.svt dosyası bir sqlite dosyasıdır. “.net API’de” API’nin sqlite dosyasını okuyabilmesi için sqlite dll inin “32- 64 bit” versiyonun koşan konfigürasyona göre refere edilmesi gerekmektedir. Ayrıca appconfig dosyasına da bundle da olduğu gibi parametrelerin girilmesi gerekmektedir.

Mali Mühür sertifikası ile MA3 API’de Zaman Damgalı (EST üstü) imza oluşturulması sırasında hata ile karşılaşılması durumunda

certval-policy-malimuhur.xml içerisinden “securitylevel“ parametresine aşağıdaki gibi “legal” değerini ekleyerek sorunu giderebilirsiniz.

<trustedcertificate> <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.find. certificate.trusted.TrustedCertificateFinderFromXml"> <param name="securitylevel" value="organizational,legal"/> <param name="storepath" value="http://depo.kamusm.gov.tr/depo/SertifikaDeposu.xml"/> </class> </trustedcertificate>

“PKI Status: 2, Status String: Used hash algorithm isn’t supported” hatasını almaktayım, çözümü için nasıl bir yol izlemeliyim?

Hata, sunucuya desteklenmeyen bir özet algoritması ile oluşturulmuş zaman damgası isteği gönderilmesinden kaynaklanmaktadır.

15.09.2014 tarihinden itibaren SHA-1 algoritması geçerli kabul edilmemektedir ve zaman damgası sunucuları SHA-1’li isteklere cevap vermemektedir. Özet algoritması SHA-2 olarak ayarlanmalıdır. Aşağıda XAdES ve CAdES için özet algoritmalarının nasıl ayarlanacağı gösterilmektedir.

XAdES ve Ortak (Common) API için Zaman Damgası Özet Algoritmasının Ayarlanması:

XAdES ve Ortak API için konfigürasyon ayarlamaları sırasıyla “xmlsignature-config.xml” dosyasından ve “esyasignature-config.xml dosyasından” yapılmaktadır. Kullanılacak config dosyası da aşağıda gösterildiği üzere kod kısmından verilmektedir.

XAdES:
context.Config = new Config(ROOT_DIR + @"docs\config\xmlsignature-config.xml");

Ortak API:
context.Config = new Config(ROOT_DIR + @"docs\config\esyasignature-config.xml");

Yukarıdaki şekilde dosya yolu gösterilmiş konfigürasyon dosyasının zaman damgası bilgilerinin girildiği kısımdaki DigestAlg tag’i SHA-256 olarak ayarlanmalıdır.

<timestamp-server>
 <host>http://zd.kamusm.gov.tr</host>
 <digest-alg>SHA-256</digest-alg>
 <!-- leave below settings blank, if not ESYA Timestamp Server! -->
 <userid>****</userid>
 <password>*********</password>
</timestamp-server>

CAdES API için Zaman Damgası Özet Algoritmasının Ayarlanması:

CAdES API’de zaman damgasının ayarlanması kod kısmında yapılmaktadır. Zaman damgası için parametre alan obje TSSettings sınıfından türetilmektedir. Bu objenin dört parametre alan yapılandırıcısı kullanılmakta ve dördüncü parametre olarak özet (digest) algoritması verilmektedir. Özet algoritması olarak geçerli bir özet algoritması girilmelidir.
TSSettings tsSettings=new TSSettings(“http://zd.kamusm.gov.tr”,21,”password”, DigestAlg.SHA256)

MA3 API ile “Web Service Security (WSS)” standardında istendiği üzere XML dosyalar imzalanabilir mi?

TUBİTAK API tarafından CAdES, XAdES, PAdES API’ler sağlanmaktadır. WSS standardında istenen imza yapısı ise “XML Signature Syntax and Processing (Second Edition)” standardıdır. Bu sebeple WSS için soap XML ler MA3 API tarafından imzalanamamaktadır.

Sertifika veya imza doğrulamayı daha hızlı yapmak için politika dosyalarında (certval-policy.xml) hangi ayarlamaları yapmalıyım?

İptal kontrolü, ESHS tarafından sağlanan Sertifika İptal Listeleri (SİL) veya OCSP (Online Certificate Status Protocol) servisi üzerinden yapılabilmektedir. OCSP ile iptal durumu anlık olarak öğrenilir. Alınan OCSP cevabı günceldir ve daha sonraki imzalar için kullanılamaz. SİL ise iptal olmuş sertifikaları içeren bir dosyadır ve ESHS’lerin belirlediği politikaya göre belli periyotlarla yayımlanır. ESHS’ler tarafından yayımlanan SİL’lerin belirlenmiş bir kullanım ömrü bulunmaktadır. SİL’leri kullanım ömrü boyunca birden çok sertifika için kullanmak ve her defasında yeniden indirmemek amacıyla politika dosyalarından (…policy.xml) aşağıda gösterildiği üzere “SİL Kaydediciler (CRL Saver)” kullanılabilir. SİL kaydediciler, kayıtlı olmayan yeni bir SİL yayımlandığında, SİL’i sertifika deposuna kaydeder ve sertifika doğrulama süresini kısaltır. Aynı yaklaşım sertifikalar için de kullanılabilir.

(.......................)
<save>
 <crl>
  <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.save. CertStoreCRLSaver"/>
 </crl>
 <certificate>
  <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.save. CertStoreCertificateSaver"/>
 </certificate>
</save>
(.....................)

SİL kaydediciler tarafından kaydedilen SİL’ler kullanım ömrü boyunca geçerlidirler ve kullanılabilirler. SİL’in kullanım ömrü dolmadan sertifikanın iptali gerçekleşirse bu durum uygulama tarafından yakalanamaz. Bu SİL için büyük bir dezavantajdır. Güvenliğin ön planda tutulduğu sistemlerde SİL yerine OCSP kullanımı tavsiye edilmektedir.

Kaydedilen SİL’lerin SİL Bulucular ile kullanılabilmesi adına da

“<class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.crl. CRLFinderFromECertStore"> <param name = "getactivecrl" value="true"/>”

satırı açılmalıdır.

<class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.cevap. certificate.revocation.RevocationFromCRLcevaper"> sınıfı aşağıda gösterildiği üzere RevocationFromOCSPcevaper’ın üstüne revocation tag’inin hemen sonrasına taşınmalıdır.

<revocation>
 <class name="tr.gov.tubitak.uekae.esya.api.certificate.validation.cevap. certificate.revocation.RevocationFromCRLcevaper">
  <param name ="cevrimdisicalis" value="false"/>
  <param name ="cevapallcrls" value="true"/>
  <param name ="devam" value="true"/>
  <find>
   <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.crl. CRLFinderFromECertStore">
   <param name = "getactivecrl" value="true"/>
   </class>
   <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.crl. CRLFinderFromECertStore"/>
  <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.crl. CRLFinderFromHTTP"/>
   <class name = "tr.gov.tubitak.uekae.esya.api.certificate.validation.find.crl. CRLFinderfromLDAP"/>
  </find>
……

Saver’ları kullanmanın diğer dezavantajı da sertifikadeposu.svt dosyasının zamanla büyümesidir. Bu problemi depo.kamusm.gov.tr adresindeki sertifikadeposu.svt dosyası ile bilgisayarınızdaki c:\users\....\.sertifikadeposu\sertifikadeposu.svt dosyasını belirli aralıklarla çalışan bir kod ile değiştirerek giderebilirsiniz.

Linux işletim sisteminde Zamane Konsol’u kullanarak zaman damgası alma işleminin ilk seferde çok yavaş olması ve sonrasında bir daha zaman damgası alınamaması sorununu nasıl çözebilirim?

Gönderilen sorgularda nonce değeri için random sayı üretilmektedir. Bazı Linux işletim sistemlerinde de random sayı üretecinin çok yavaş çalışması sebebiyle böyle bir hata oluşmaktadır. Aşağıdaki satırlar linux consoldan girildiğinde RNG tools uygulaması yüklenmektedir ve random sayı üretimi bu uygulama sayesinde hızlanmaktadır.

• > sudo -i
• > apt-get update
• > apt-get install rng-tools
• > rngd -r /dev/urandom

Redhat/Centos 7 için adımlar ise şu şekildedir:

• # yum install rng-tools
• /usr/lib/systemd/system/rngd.service dosyasında ExecStar aşağıdaki şekilde değiştirilir:

ExecStart=/sbin/rngd -f -r /dev/urandom

• # systemctl daemon-reload
• # systemctl start rngd
• # systemctl enable rngd     (isteniyorsa)

XAdES API’de büyük boyutlu dosyalarla (örneğin 150 Mb e-Defter dosyası) imza oluşturulması sırasında alınan hata nasıl çözülebilir?

XML veriler parse edilirken RAM de çok fazla yer kaplamaktadır. .Net API'yi kullanıyorsanız 64 bit dll'ler ile projenizi 64 bit derleyerek imzalama yapmalısınız. Java için ise “heap space” i artırmalısınız.

API ile yapılan e-Defter imzalama testlerinde;

• 50 Mb XML veri için 2Gb,
• 100 Mb XML veri için 4Gb,
• 200 Mb XML veri için 8Gb,

RAM kullanıldığı görülmüştür.

Tavsiyeler:

• Büyük dosyaları parçalara ayırmanızı,
• Kullandığınız bilgisayarda en az 16 Gb Ram ve 4 çekirdekli işlemci olmasını

tavsiye ederiz.

Kamu SM dışında farklı bir ESHS tarafından alınmış kartla imza oluşturulması sırasında hata alıyorum, nasıl çözebilirim?

API akıllı kartları ATR numarasından tanımaktadır ve ATR numarasına karşılık ilgili sürücü (dll) ile bağlantı kurmaktadır. Eğer API’de ilgili kart tanımlı değilse imza oluşturulamaz. API’ye yeni kart tanımlamak için smartcard-config.xml dosyasına ATR değeri girilmelidir. ATR değerini tespit etmek için aşağıdaki kod kullanılmaktadır.

String[] terminals = SmartOp.getCardTerminals();
String terminal = terminals[0];
TerminalFactory tf = TerminalFactory.getDefault();
CardTerminal ct = tf.terminals().getTerminal(terminal);
Card card = ct.connect("*");
String ATR = StringUtil.toString(card.getATR().getBytes());
JOptionPane.showMessageDialog(null, ATR);
System.out.println(ATR);


ATR değeri tespit edildikten sonra kartın kullandığı dll’in de tespit edilmesi gerekmektedir. “dll” tespit edildikten sonra “SmartCardConfig” e ATR değeri ve dll in adı eklenir. SmartCardConfig.xml dosyası projenin çalışma alanına (workdir) kopyalanır. Kopyalanan SmartCardConfig dosyasının kod kısmından aktif hale getirilmesi gerekmektedir. Bunun için SmartCardManager sınıfı içerisindeki getInstance() metodunun başına aşağıdaki kod eklenir

List cards = new SmartCardConfigParser().readConfig();
CardType.applyCardTypeConfig(cards);
//...