gokalkan

package module
v0.0.0-...-d13dd57 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 27, 2023 License: MIT Imports: 14 Imported by: 0

README

gokalkan

pkg-img reportcard-img

Пакет gokalkan является оберткой над нативными методами библиотеки KalkanCrypt.

KalkanCrypt является основной библиотекой для работы с ЭЦП ключами от pki.gov.kz и позволяет подписывать, верифицировать, вытаскивать данные и много чего другого связанного с электронными подписями, цифровыми сертификатами и ключами.

Особенности пакета gokalkan:

  • Поддержка мультипоточности
  • Без зависимостей
  • Чистый код
  • Напрямую вызывает нативные методы KalkanCrypt

Перед использованием

Чтобы использовать библиотеку требуется провести подготовку:

1. Получить SDK

Обратиться в pki.gov.kz чтобы получить SDK. SDK представляет из себя набор библиотек для Java и C.

2. Установить CA сертификаты

Сертификаты лежат по пути SDK/C/Linux/ca-certs/Ubuntu. В папке находятся два типа сертификатов - production и test. Для их установки приготовлены скрипты в той же директории. При запуске понадобятся sudo права.

3. Скопировать .so файлы

Файлы лежат в директории SDK 2.0/C/Linux/C/libs/v2.0.4. Команда для копирования:

sudo cp -f libkalkancryptwr-64.so.2.0.4 /usr/lib/libkalkancryptwr-64.so

Установка

Версия Go 1.17+

go get github.com/AbdybaevAE/gokalkan

Загрузка хранилища PKCS12

Загрузка хранилища с ключом и сертификатом (например ЭЦП ключ, который начинается с RSA...):

package main

import (
	"fmt"
	"log"

	"github.com/AbdybaevAE/gokalkan"
)

var (
	certPath = "test_cert/GOSTKNCA.p12" // путь к хранилищу

	certPassword = "Qwerty12" // пароль
	// P.S. никогда не храните пароли в коде
)

func main() {
	// для теста
	opts := gokalkan.OptsTest

	// для прода
	// opts := gokalkan.OptsProd

	cli, err := gokalkan.NewClient(opts...)
	if err != nil {
		log.Fatal("new kalkan client create error", err)
	}
	// Обязательно закрывайте клиент, иначе приведет к утечкам ресурсов
	defer cli.Close()

	// Подгружаем хранилище с паролем
	err = cli.LoadKeyStore(certPath, certPassword)
	if err != nil {
		log.Fatal("load key store error", err)
	}
}

Следует отметить, что при инициализации gokalkan клиента нужно указывать опцию. Есть две опции - OptsTest и OptsProd. Нужно выбрать одну из них в зависимости от окружения.

Подпись XML документа

Для того чтобы подписать XML документ, нужно передать документ в виде строки:

signedXML, err := cli.SignXML("<root>GoKalkan</root>")

fmt.Println("Подписанный XML", signedXML)
fmt.Println("Ошибка", err)
Проверка подписи на XML документе

Проверка подписи документа вернет ошибку, если документ подписан неверно либо срок у сертификата с которым подписан истёк.

serial, err := cli.VerifyXML(signedXML)

fmt.Println("Серийный номер", serial)
fmt.Println("Ошибка", err)
Подпись XML документа для SmartBridge

Для того чтобы подписать XML документ в формате SignWSSE, нужно передать документ в виде строки и id для SOAP Body. Функция обернет документ в soap:Envelope и запишет внутри soap:Body.

signedXML, err := cli.SignWSSE("<root>gokalkan</root>", "12345")

fmt.Println("Подписанный XML в формате WSSE", signedXML)
fmt.Println("Ошибка", err)

Бенчмарки

Команда запуска бенчмарка:

go test -bench SignXML -run=^$ -benchmem

Характеристики хост машины:

  • goos: linux
  • goarch: amd64
  • cpu: Intel(R) Core(TM) i5-8500 CPU @ 3.00GHz
Бенчмарк Кол-во циклов Средн. время выполнения Средн. потребление ОЗУ Средн. кол-во аллокаций
BenchmarkSignXML-6 2809 422310 ns/op 2792 B/op 8 allocs/op

Контрибьютеры ✨


Zulbukharov Abylaikhan
Tlekbai Ali
Kilibayev Azat

Лицензия

The MIT License (MIT) 2021 - Abylaikhan Zulbukharov.

Please have a look at the LICENSE.md for more details.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	OptsProd = []Option{
		WithLogger(defaultLogger),
		WithTSP(prodTSP),
		WithOCSP(prodOCSP),
	}
	OptsTest = []Option{
		WithLogger(defaultLogger),
		WithTSP(testTSP),
		WithOCSP(testOCSP),
	}
)
View Source 
var (
	ErrInit    = errors.New("unable to refer to KC_GetFunctionList")
	ErrHTTPCli = errors.New("http cli error")
)
View Source 
var ErrLoadKey = errors.New("load key error")

Functions

func WrapWithWSSESoapEnvelope 

func WrapWithWSSESoapEnvelope(dataXML, id string) (result string)

WrapWithWSSESoapEnvelope оборачивает XML документ в SOAP формат, а точнее записывает содержимое под тегом soap:Body

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(opts ...Option) (*Client, error)

NewClient возвращает клиента для работы с KC.

func (*Client) Close 

func (cli *Client) Close() (err error)

func (*Client) GetCertFromCMS 

func (cli *Client) GetCertFromCMS(cms []byte, signID int) (string, error)

GetCertFromCMS обеспечивает получение сертификата из CMS.

func (*Client) HashGOST95 

func (cli *Client) HashGOST95(data []byte) (hashed []byte, err error)

func (*Client) HashSHA256 

func (cli *Client) HashSHA256(data []byte) (hashed []byte, err error)

func (*Client) LoadCertFromBytes 

func (cli *Client) LoadCertFromBytes(cert []byte, certType ckalkan.CertType) (err error)

func (*Client) LoadCerts 

func (cli *Client) LoadCerts() error

func (*Client) LoadKeyStore 

func (cli *Client) LoadKeyStore(path, password string) error

LoadKeyStore загружает PKCS12.

func (*Client) LoadKeyStoreFromBytes 

func (cli *Client) LoadKeyStoreFromBytes(key []byte, password string) (err error)

LoadKeyStoreFromBytes загружает PKCS12.

func (*Client) Options 

func (cli *Client) Options() Options

func (*Client) Sign 

func (cli *Client) Sign(data []byte, isDetached, withTSP bool) (signature []byte, err error)

Sign подписывает данные и возвращает CMS с подписью.

func (*Client) SignWSSE 

func (cli *Client) SignWSSE(xmlData, id string) (string, error)

func (*Client) SignXML 

func (cli *Client) SignXML(xmlData string) (string, error)

SignXML подписывает данные в формате XML.

func (*Client) Underlying 

func (cli *Client) Underlying() *ckalkan.Client

func (*Client) ValidateCert 

func (cli *Client) ValidateCert(cert string) (string, error)

func (*Client) ValidateCertOCSP 

func (cli *Client) ValidateCertOCSP(cert string, url ...string) (string, error)

func (*Client) Verify 

func (cli *Client) Verify(signature []byte) (string, error)

Verify обеспечивает проверку подписи CMS в base64.

func (*Client) VerifyData 

func (cli *Client) VerifyData(signature []byte) (*ckalkan.VerifiedData, error)

func (*Client) VerifyDetached 

func (cli *Client) VerifyDetached(signature, data []byte) (string, error)

VerifyDetached обеспечивает проверку отделенной подписи CMS (detached signature) в base64.

func (*Client) VerifyXML 

func (cli *Client) VerifyXML(signedXML string) (result string, err error)

VerifyXML обеспечивает проверку подписи данных в формате XML.

func (*Client) X509CertificateGetInfo 

func (cli *Client) X509CertificateGetInfo(inCert string, prop ckalkan.CertProp) (string, error)

type Kalkan 

type Kalkan interface {
	LoadKeyStore(path, password string) (err error)
	LoadKeyStoreFromBytes(key []byte, password string) (err error)

	Sign(data []byte, isDetached, withTSP bool) (signature []byte, err error)
	SignXML(xml string) (signedXML string, err error)
	SignWSSE(xml, id string) (signedXML string, err error)

	Verify(signature []byte) (string, error)
	VerifyData(signature []byte) (*ckalkan.VerifiedData, error)
	VerifyXML(signedXML string) (string, error)
	VerifyDetached(signature, data []byte) (string, error)

	GetCertFromCMS(cms []byte, signID int) (string, error)

	ValidateCert(cert string) (string, error)
	ValidateCertOCSP(cert string, url ...string) (string, error)

	HashSHA256(data []byte) ([]byte, error)
	HashGOST95(data []byte) ([]byte, error)
	X509CertificateGetInfo(inCert string, prop ckalkan.CertProp) (string, error)
	Underlying() *ckalkan.Client
	Close() error
}

Kalkan - это обертка над методами KalkanCrypt.

type Logger 

type Logger interface {
	Debug(args ...interface{})
	Error(args ...interface{})
}

type Option 

type Option func(o *Options)

func WithCert 

func WithCert(cert *x509.Certificate, typ ckalkan.CertType) Option

func WithCerts 

func WithCerts(c []OptionsCert) Option

func WithLogger 

func WithLogger(logger Logger) Option

func WithOCSP 

func WithOCSP(u string) Option

func WithRemoteProdCerts 

func WithRemoteProdCerts(ctx context.Context) Option

func WithRemoteTestCerts 

func WithRemoteTestCerts(ctx context.Context) Option

func WithTSP 

func WithTSP(u string) Option

type Options 

type Options struct {
	TSP       string        `json:"tsp"`   // URL метки времени
	OCSP      string        `json:"ocsp"`  // URL сервиса онлайн проверки статуса сертификата
	Certs     []OptionsCert `json:"certs"` // Корневые сертификатам
	LoadCerts bool          `json:"load_certs"`
	// contains filtered or unexported fields
}

type OptionsCert 

type OptionsCert struct {
	Cert *x509.Certificate
	Type ckalkan.CertType
}

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.