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
- func BuildSignedValue(signatureXML []byte, seal *Seal, certDER []byte, key *sm2.PrivateKey, ...) ([]byte, error)
- func BuildSignedValueWithOptions(signatureXML []byte, seal *Seal, certDER []byte, key *sm2.PrivateKey, ...) ([]byte, error)
- func CertificateAuthorized(typ int64, listDER, certificate []byte) error
- func CertificateHash(method string, certificate []byte) ([]byte, error)
- func IsIA5(s string) bool
- func MarshalPrivateKeyPEM(key *sm2.PrivateKey) ([]byte, error)
- func NewSelfSignedCertificate(commonName, organization string, now time.Time) (*sm2.PrivateKey, *ecdsa.PublicKey, []byte, error)
- func ParseCertificateDER(data []byte) ([]byte, error)
- func ParsePrivateKey(data []byte) (*sm2.PrivateKey, error)
- func PictureTypeAndSize(data []byte) (string, int, int, error)
- func ValidateSealForSigner(seal *Seal, signer []byte, at time.Time) error
- func ValidateSigningCertificate(cert *smx509.Certificate, at time.Time) error
- func ValidateSigningKey(der []byte, key *sm2.PrivateKey, at time.Time) error
- type CertificateDigest
- type Extension
- type Header
- type Picture
- type Property
- type Seal
- type SealInfo
- type SealParams
- type SignedValue
- type SigningOptions
- type TBSSign
- type TimestampProof
Constants ¶
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 CertificateAuthorized ¶
CertificateAuthorized 校验完整 DER 证书或其杂凑是否获印章授权(§7.3 c)。 检查整张列表的结构,不能因前面的项目匹配而忽略后续无效项目。
func CertificateHash ¶
CertificateHash 只用于印章授权列表,不影响 OFD References 的摘要算法集合。
func IsIA5 ¶
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 ¶
ParseCertificateDER 解析证书,支持 PEM 或 DER,统一返回 DER 字节。
func ParsePrivateKey ¶
func ParsePrivateKey(data []byte) (*sm2.PrivateKey, error)
ParsePrivateKey 解析 SM2 私钥,支持 PKCS#8 的 PEM 或 DER 编码。
func PictureTypeAndSize ¶
PictureTypeAndSize 返回印章图片的格式名与宽高。 格式名来自 image.DecodeConfig("png"、"jpeg"、"gif"、"bmp"),可直接用于 SES_ESPictrueInfo.Type。
func ValidateSealForSigner ¶
ValidateSealForSigner 是 §7.2 a) 的本地签署前检查;信任链和状态证据由 SigningOptions.Validate 接入,不隐式访问网络或系统根证书。
func ValidateSigningCertificate ¶
func ValidateSigningCertificate(cert *smx509.Certificate, at time.Time) error
func ValidateSigningKey ¶
ValidateSigningKey 防止用不匹配的证书、私钥或非签名用途证书生成签章。
Types ¶
type CertificateDigest ¶
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 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 ¶
MarshalDER 输出 SES_Seal 的 DER 编码,即 Seal.esl 的文件内容。
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 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)。