Help us shape the future of Go! Take the 2026 Go Developer Survey

ses

package
v0.1.5 Latest Latest
Warning

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

Go to latest
Published: Oct 21, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package ses 实现 GB/T 38540-2020 规定的 SES 电子印章数据格式。

SEAL(印章)把印章信息(名称、证书、有效期、印章图片)和对它的 SM2 签名 打包成一份 DER 编码的 ASN.1 结构;它可以单独落盘(Seal.esl),也会被嵌入 TBS_Sign / SignedValue.dat,成为 OFD 内嵌签名的一部分。

本包提供组装 SES 结构的入口,字段的 ASN.1 顺序与 GB/T 38540 严格一致, 修改结构定义必须保持标准的顺序与类型。

Index

Constants

View Source
const (
	// HeaderID 是 SES_Header.ID 的固定值,GM/T 0031 规定为 "ES"。
	HeaderID = "ES"
	// SealVersion 是 SES 结构版本号;与 OFD 规范配套的版本是 V4。
	SealVersion = 4
	// DefaultValidity 是证书/印章的默认有效期。
	DefaultValidity = 10 * 365 * 24 * time.Hour
)

Variables

This section is empty.

Functions

func BuildSignedValue

func BuildSignedValue(signatureXML []byte, seal *Seal, certDER []byte, key *sm2.PrivateKey, propertyInfo string, now time.Time) ([]byte, error)

BuildSignedValue 以 TBS_Sign 为待签名数据,生成 SignedValue.dat。 signatureXML 的 SM3 摘要写入 TBS_Sign.DataHash,propertyInfo 是签名 XML 的 包内路径(例如 "/Doc_0/Signatures/Signature_sign-1.xml")。

func BuildSignedValueWithOptions

func BuildSignedValueWithOptions(signatureXML []byte, seal *Seal, certDER []byte, key *sm2.PrivateKey, propertyInfo string, now time.Time, options SigningOptions) ([]byte, error)

func CertificateAuthorized

func CertificateAuthorized(typ int64, listDER, certificate []byte) error

CertificateAuthorized 校验完整 DER 证书或其杂凑是否获印章授权(§7.3 c)。 检查整张列表的结构,不能因前面的项目匹配而忽略后续无效项目。

func CertificateHash

func CertificateHash(method string, certificate []byte) ([]byte, error)

CertificateHash 只用于印章授权列表,不影响 OFD References 的摘要算法集合。

func IsIA5

func IsIA5(s string) bool

IsIA5 判断字符串是否只含 IA5(ASCII)字符。

SES_Header.VID、ESID 等字段在 GB/T 38540 里定义为 IA5String。CLI 层可以在 生成证书之前就用它给出友好提示,BuildSeal 内部也会再校验一次。

func MarshalPrivateKeyPEM

func MarshalPrivateKeyPEM(key *sm2.PrivateKey) ([]byte, error)

MarshalPrivateKeyPEM 输出 PKCS#8 私钥的 PEM 编码。

func NewSelfSignedCertificate

func NewSelfSignedCertificate(commonName, organization string, now time.Time) (*sm2.PrivateKey, *ecdsa.PublicKey, []byte, error)

NewSelfSignedCertificate 生成 SM2 自签名证书,返回私钥、公钥与证书 DER。 仅用于演示、测试与本地评估:自签证书不建立可验证的信任链,生产环境应导入 有合法信任链的证书与私钥。

func ParseCertificateDER

func ParseCertificateDER(data []byte) ([]byte, error)

ParseCertificateDER 解析证书,支持 PEM 或 DER,统一返回 DER 字节。

func ParsePrivateKey

func ParsePrivateKey(data []byte) (*sm2.PrivateKey, error)

ParsePrivateKey 解析 SM2 私钥,支持 PKCS#8 的 PEM 或 DER 编码。

func PictureTypeAndSize

func PictureTypeAndSize(data []byte) (string, int, int, error)

PictureTypeAndSize 返回印章图片的格式名与宽高。 格式名来自 image.DecodeConfig("png"、"jpeg"、"gif"、"bmp"),可直接用于 SES_ESPictrueInfo.Type。

func ValidateSealForSigner

func ValidateSealForSigner(seal *Seal, signer []byte, at time.Time) error

ValidateSealForSigner 是 §7.2 a) 的本地签署前检查;信任链和状态证据由 SigningOptions.Validate 接入,不隐式访问网络或系统根证书。

func ValidateSigningCertificate

func ValidateSigningCertificate(cert *smx509.Certificate, at time.Time) error

func ValidateSigningKey

func ValidateSigningKey(der []byte, key *sm2.PrivateKey, at time.Time) error

ValidateSigningKey 防止用不匹配的证书、私钥或非签名用途证书生成签章。

Types

type CertificateDigest

type CertificateDigest struct {
	Type  string `asn1:"printable"`
	Value []byte
}

CertificateDigest 对应 GB/T 38540—2020 §6.1.2.4 的 CertDigestObj。

type Extension

type Extension struct {
	OID      asn1.ObjectIdentifier
	Critical bool `asn1:"optional,default:false"`
	Value    []byte
}

Extension 对应 §6.1.2.6 的 ExtData,false 是 DER 中省略的默认值。

type Header struct {
	ID      string `asn1:"ia5"`
	Version int
	VID     string `asn1:"ia5"`
}

type Picture

type Picture struct {
	Type   string `asn1:"ia5"`
	Data   []byte
	Width  int
	Height int
}

type Property

type Property struct {
	Type            int
	Name            string `asn1:"utf8"`
	CertificateType int
	CertList        asn1.RawValue
	CreateTime      time.Time `asn1:"generalized"`
	ValidFrom       time.Time `asn1:"generalized"`
	ValidTo         time.Time `asn1:"generalized"`
}

type Seal

type Seal struct {
	SealInfo           SealInfo
	Certificate        []byte
	SignatureAlgorithm asn1.ObjectIdentifier
	Signature          asn1.BitString
}

Seal 是 GB/T 38540 定义的 SES_Seal。Certificate 与 SignatureAlgorithm 是对 SealInfo 的 SM2 签名(SM2WithSM3)。

func BuildSeal

func BuildSeal(params SealParams, certDER []byte, key *sm2.PrivateKey, now time.Time) (*Seal, error)

BuildSeal 组装 SES_Seal_Info 并对它签名,产出符合 GB/T 38540 的 SES_Seal。 certDER 必须是 privateKey 对应证书的 DER 编码。

func (*Seal) MarshalDER

func (s *Seal) MarshalDER() ([]byte, error)

MarshalDER 输出 SES_Seal 的 DER 编码,即 Seal.esl 的文件内容。

type SealInfo

type SealInfo struct {
	Header     Header
	ESID       string `asn1:"ia5"`
	Property   Property
	Picture    Picture
	Extensions []Extension `asn1:"optional"`
}

type SealParams

type SealParams struct {
	// Provider 写入 SES_Header.VID。
	Provider string
	// ESID 是印章的全局唯一编号,通常使用 email 形态的标识。
	ESID string
	// Name 写入 SES_ESPropertyInfo.Name。
	Name string
	// PictureType 是印章图片格式,取自 image.DecodeConfig 的格式名(png、jpeg、gif、bmp)。
	PictureType string
	// PictureData 是印章图片的原始字节。
	PictureData []byte
	// Width、Height 是显示宽高,单位毫米(§6.1.2.5),与像素尺寸无关。
	Width  int
	Height int
	// SignerCertificates 是获授权的签章者证书;缺省时授权制章者证书。
	SignerCertificates [][]byte
	// SignerDigests 与 SignerCertificates 互斥,对应 certListType=2。
	SignerDigests []CertificateDigest
	Extensions    []Extension
	// ValidFrom、ValidTo 是印章的有效期;零值时从 now 开始使用 DefaultValidity。
	ValidFrom time.Time
	ValidTo   time.Time
}

SealParams 描述一枚待生成的电子印章。

type SignedValue

type SignedValue struct {
	TBS                TBSSign
	Certificate        []byte
	SignatureAlgorithm asn1.ObjectIdentifier
	Signature          asn1.BitString
	TimeStamp          asn1.BitString `asn1:"optional,explicit,tag:0"`
}

SignedValue 对应 OFD SignedValue.dat 的外层结构(SES_Signature)。

type SigningOptions

type SigningOptions struct {
	Extensions []Extension
	// Validate 用于签署前的证书信任、吊销及印章状态校验;返回错误时不签署。
	Validate func(seal *Seal, signerCertificate []byte, at time.Time) error
	// Timestamp 接收签名值字节,返回 DER 时间戳令牌(不是整个响应包)。
	Timestamp func(signature []byte) ([]byte, error)
}

SigningOptions 为签署前的状态校验及可选时间戳提供调用方接入点。

type TBSSign

type TBSSign struct {
	Version      int
	Seal         Seal
	SignTime     time.Time `asn1:"generalized"`
	DataHash     asn1.BitString
	PropertyInfo string      `asn1:"ia5"`
	Extensions   []Extension `asn1:"optional,explicit,tag:0"`
}

type TimestampProof

type TimestampProof struct {
	Time         time.Time
	Signer       *smx509.Certificate
	Certificates []*smx509.Certificate
}

TimestampProof 是时间戳令牌的数学、摘要绑定与用途验证结果。 证书信任链及吊销状态必须由调用方按 Time 进一步验证。

func CheckTimestamp

func CheckTimestamp(token, signature []byte) (*TimestampProof, error)

CheckTimestamp 校验 DER TimeStampToken 对签名值的绑定(GB/T 38540 §7.1.6、 §7.3 h;GB/T 20520 / RFC 3161 的 CMS SignedData + TSTInfo)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL