Golang标准库——crypto(4)

• x509
• x509/pkix

x509

x509包解析X.509编码的证书和密钥。

Constants

const (
    PEMCipherDES
    PEMCipher3DES
    PEMCipherAES128
    PEMCipherAES192
    PEMCipherAES256
)

可能会被EncryptPEMBlock加密算法使用的值。

Variables

var ErrUnsupportedAlgorithm = errors.New("x509: cannot verify signature: algorithm unimplemented")

当试图执行包含目前未实现的算法的操作时，会返回ErrUnsupportedAlgorithm。

var IncorrectPasswordError = errors.New("x509: decryption password incorrect")

当检测到不正确的密码时，会返回IncorrectPasswordError。

type PEMCipher

type PEMCipher int

type PublicKeyAlgorithm

type PublicKeyAlgorithm int
const (
    UnknownPublicKeyAlgorithm PublicKeyAlgorithm = iota
    RSA
    DSA
    ECDSA
)

type SignatureAlgorithm

type SignatureAlgorithm int
const (
    UnknownSignatureAlgorithm SignatureAlgorithm = iota
    MD2WithRSA
    MD5WithRSA
    SHA1WithRSA
    SHA256WithRSA
    SHA384WithRSA
    SHA512WithRSA
    DSAWithSHA1
    DSAWithSHA256
    ECDSAWithSHA1
    ECDSAWithSHA256
    ECDSAWithSHA384
    ECDSAWithSHA512
)

type SystemRootsError

type SystemRootsError struct {
    Err error
}

当从系统装载根证书失败时，会返回SystemRootsError。

func (SystemRootsError) Error

func (e SystemRootsError) Error() string

type HostnameError

type HostnameError struct {
    Certificate *Certificate
    Host        string
}

当认证的名字和请求的名字不匹配时，会返回HostnameError。

func (HostnameError) Error

func (h HostnameError) Error() string

type UnknownAuthorityError

type UnknownAuthorityError struct {
    Cert *Certificate
    // hintErr contains an error that may be helpful in determining why an
    // authority wasn't found.
    hintErr error
    // hintCert contains a possible authority certificate that was rejected
    // because of the error in hintErr.
    hintCert *Certificate
}

当证书的发布者未知时，会返回UnknownAuthorityError。

func (UnknownAuthorityError) Error

func (e UnknownAuthorityError) Error() string

type ConstraintViolationError

type ConstraintViolationError struct{}

当请求的用途不被证书许可时，会返回ConstraintViolationError。如：当公钥不是证书的签名密钥时用它检查签名。

func (ConstraintViolationError) Error

func (ConstraintViolationError) Error() string

type UnhandledCriticalExtension

type UnhandledCriticalExtension struct{}

func (UnhandledCriticalExtension) Error

func (h UnhandledCriticalExtension) Error() string

type CertificateInvalidError

type CertificateInvalidError struct {
    Cert   *Certificate
    Reason InvalidReason
}

当发生其余的错误时，会返回CertificateInvalidError。本包的使用者可能会想统一处理所有这类错误。

func (CertificateInvalidError) Error

func (e CertificateInvalidError) Error() string

type KeyUsage

type KeyUsage int

KeyUsage代表给定密钥的合法操作集。用KeyUsage类型常数的位图表示。（字位表示有无）

const (
    KeyUsageDigitalSignature KeyUsage = 1 << iota
    KeyUsageContentCommitment
    KeyUsageKeyEncipherment
    KeyUsageDataEncipherment
    KeyUsageKeyAgreement
    KeyUsageCertSign
    KeyUsageCRLSign
    KeyUsageEncipherOnly
    KeyUsageDecipherOnly
)

type ExtKeyUsage

type ExtKeyUsage int

ExtKeyUsage代表给定密钥的合法操作扩展集。每一个ExtKeyUsage类型常数定义一个特定的操作。

const (
    ExtKeyUsageAny ExtKeyUsage = iota
    ExtKeyUsageServerAuth
    ExtKeyUsageClientAuth
    ExtKeyUsageCodeSigning
    ExtKeyUsageEmailProtection
    ExtKeyUsageIPSECEndSystem
    ExtKeyUsageIPSECTunnel
    ExtKeyUsageIPSECUser
    ExtKeyUsageTimeStamping
    ExtKeyUsageOCSPSigning
    ExtKeyUsageMicrosoftServerGatedCrypto
    ExtKeyUsageNetscapeServerGatedCrypto
)

type VerifyOptions

type VerifyOptions struct {
    DNSName       string
    Intermediates *CertPool
    Roots         *CertPool // 如为nil，将使用系统根证书池
    CurrentTime   time.Time // 如为零值，将使用当前时间
    // KeyUsage指定了可以接受哪些密钥扩展用途，空列表代表ExtKeyUsageServerAuth。
    // 密钥用途被作为生成证书链的限制条件（类似Windows加密应用程序接口的行为，但不完全一样）
    // 要接受任何密钥用途，可以使本字段包含ExtKeyUsageAny。
    KeyUsages []ExtKeyUsage
}

VerifyOptions包含提供给Certificate.Verify方法的参数。它是结构体类型，因为其他PKIX认证API需要很长参数。

type InvalidReason

type InvalidReason int
const (
    // NotAuthorizedToSign表示给本证书签名的证书不是CA证书
    NotAuthorizedToSign InvalidReason = iota
    // Expired表示证书已过期，根据VerifyOptions.CurrentTime判断
    Expired
    // CANotAuthorizedForThisName表示中间证书或根证书具有名字限制，且不包含被检查的名字
    CANotAuthorizedForThisName
    // TooManyIntermediates表示违反了路径长度限制
    TooManyIntermediates
    // IncompatibleUsage表示证书的密钥用途显示它只能用于其它目的
    IncompatibleUsage
)

type Certificate

type Certificate struct {
    Raw                     []byte // 原始、完整的ASN.1 DER内容（证书、签名算法、签名）
    RawTBSCertificate       []byte // ASN.1 DER 内容的证书部分
    RawSubjectPublicKeyInfo []byte // 原始DER编码的SubjectPublicKeyInfo
    RawSubject              []byte // 原始DER编码的Subject
    RawIssuer               []byte // 原始DER编码的Issuer
    Signature          []byte
    SignatureAlgorithm SignatureAlgorithm
    PublicKeyAlgorithm PublicKeyAlgorithm
    PublicKey          interface{}
    Version             int
    SerialNumber        *big.Int
    Issuer              pkix.Name
    Subject             pkix.Name
    NotBefore, NotAfter time.Time // 有效期前后界，本时间段之外无效
    KeyUsage            KeyUsage
    // Extensions保管原始的X.509扩展。当解析证书时，本字段用于摘录本包未解析的不关键扩展。
    // 序列化证书时，Extensions字段会被忽略，参见ExtraExtensions。
    Extensions []pkix.Extension
    // ExtraExtensions包含应被直接拷贝到任何序列化的证书中的扩展。
    // 本字段保管的值会覆盖任何其它字段生成的扩展。
    // ExtraExtensions字段在解析证书时不会被填写，参见Extensions。
    ExtraExtensions []pkix.Extension
    ExtKeyUsage        []ExtKeyUsage           // 密钥扩展用途的序列
    UnknownExtKeyUsage []asn1.ObjectIdentifier // 遇到的本包不能识别的密钥扩展用途
    BasicConstraintsValid bool // 如果下两个字段合法，将为真
    IsCA                  bool
    MaxPathLen            int
    SubjectKeyId   []byte
    AuthorityKeyId []byte
    // RFC 5280, 4.2.2.1（认证信息存取）
    OCSPServer            []string
    IssuingCertificateURL []string
    // 证书持有者的替用名称
    DNSNames       []string
    EmailAddresses []string
    IPAddresses    []net.IP
    // 名称的约束
    PermittedDNSDomainsCritical bool // 如为真则名称约束被标记为关键的
    PermittedDNSDomains         []string
    // CRL配销点
    CRLDistributionPoints []string
    PolicyIdentifiers []asn1.ObjectIdentifier
}

Certificate代表一个X.509证书。

func (*Certificate) CheckSignatureFrom

func (c *Certificate) CheckSignatureFrom(parent *Certificate) (err error)

CheckSignatureFrom检查c中的签名是否是来自parent的合法签名。

func (*Certificate) CheckCRLSignature

func (c *Certificate) CheckCRLSignature(crl *pkix.CertificateList) (err error)

CheckCRLSignature检查crl中的签名是否来自c。

func (*Certificate) CheckSignature

func (c *Certificate) CheckSignature(algo SignatureAlgorithm, signed, signature []byte) (err error)

CheckSignature检查signature是否是c的公钥生成的signed的合法签名。

func (*Certificate) CreateCRL

func (c *Certificate) CreateCRL(rand io.Reader, priv interface{}, revokedCerts []pkix.RevokedCertificate, now, expiry time.Time) (crlBytes []byte, err error)

CreateCRL返回一个DER编码的CRL（证书注销列表），使用c签名，并包含给出的已取消签名列表。

只支持RSA类型的密钥（priv参数必须是*rsa.PrivateKey类型）。

func (*Certificate) Equal

func (c *Certificate) Equal(other *Certificate) bool

func (*Certificate) Verify

func (c *Certificate) Verify(opts VerifyOptions) (chains [][]*Certificate, err error)

Verify通过创建一到多个从c到opts.Roots中的证书的链条来认证c，如有必要会使用opts.Intermediates中的证书。如果成功，它会返回一到多个证书链条，每一条都以c开始，以opts.Roots中的证书结束。

警告：它不会做任何取消检查。

func (*Certificate) VerifyHostname

func (c *Certificate) VerifyHostname(h string) error

如果c是名为h的主机的合法证书，VerifyHostname会返回真；否则它返回一个描述该不匹配情况的错误。

type CertPool

type CertPool struct {
    bySubjectKeyId map[string][]int
    byName         map[string][]int
    certs          []*Certificate
}

CertPool代表一个证书集合/证书池。

func NewCertPool

func NewCertPool() *CertPool

NewCertPool创建一个新的、空的CertPool。

func (*CertPool) AddCert

func (s *CertPool) AddCert(cert *Certificate)

AddCert向s中添加一个证书。

func (*CertPool) AppendCertsFromPEM

func (s *CertPool) AppendCertsFromPEM(pemCerts []byte) (ok bool)

AppendCertsFromPEM试图解析一系列PEM编码的证书。它将找到的任何证书都加入s中，如果所有证书都成功被解析，会返回真。

在许多Linux系统中，/etc/ssl/cert.pem会包含适合本函数的大量系统级根证书。

func (*CertPool) Subjects

func (s *CertPool) Subjects() (res [][]byte)

Subjects返回池中所有证书的DER编码的持有者的列表。

type CertificateRequest

type CertificateRequest struct {
    Raw                      []byte // 原始、完整的ASN.1 DER内容（CSR、签名算法、签名）
    RawTBSCertificateRequest []byte // ASN.1 DER 内容的证书请求信息
    RawSubjectPublicKeyInfo  []byte // 原始DER编码的SubjectPublicKeyInfo
    RawSubject               []byte // 原始DER编码的Subject
    Version            int
    Signature          []byte
    SignatureAlgorithm SignatureAlgorithm
    PublicKeyAlgorithm PublicKeyAlgorithm
    PublicKey          interface{}
    Subject pkix.Name
    // Attributes提供关于证书持有者的额外信息，参见RFC 2986 section 4.1。
    Attributes []pkix.AttributeTypeAndValueSET
    // Extensions保管原始的X.509扩展。当解析CSR时，本字段用于摘录本包未解析的不关键扩展。
    Extensions []pkix.Extension
    // ExtraExtensions包含应被直接拷贝到任何序列化的CSR中的扩展。
    // 本字段保管的值会覆盖任何其它字段生成的扩展，但会被Attributes字段指定的扩展覆盖。
    // ExtraExtensions字段在解析CSR时不会增加，参见Extensions。
    ExtraExtensions []pkix.Extension
    // 证书持有者的替用名称。
    DNSNames       []string
    EmailAddresses []string
    IPAddresses    []net.IP
}

CertificateRequest代表一个PKCS #10证书签名请求。

func MarshalECPrivateKey

func MarshalECPrivateKey(key *ecdsa.PrivateKey) ([]byte, error)

MarshalECPrivateKey将ecdsa私钥序列化为ASN.1 DER编码。

func MarshalPKCS1PrivateKey

func MarshalPKCS1PrivateKey(key *rsa.PrivateKey) []byte

MarshalPKCS1PrivateKey将rsa私钥序列化为ASN.1 PKCS#1 DER编码。

func MarshalPKIXPublicKey

func MarshalPKIXPublicKey(pub interface{}) ([]byte, error)

MarshalPKIXPublicKey将公钥序列化为PKIX格式DER编码。

func ParseECPrivateKey

func ParseECPrivateKey(der []byte) (key *ecdsa.PrivateKey, err error)

ParseECPrivateKey解析ASN.1 DER编码的ecdsa私钥。

func ParsePKCS1PrivateKey

func ParsePKCS1PrivateKey(der []byte) (key *rsa.PrivateKey, err error)

ParsePKCS1PrivateKey解析ASN.1 PKCS#1 DER编码的rsa私钥。

func ParsePKCS8PrivateKey

func ParsePKCS8PrivateKey(der []byte) (key interface{}, err error)

ParsePKCS8PrivateKey解析一个未加密的PKCS#8私钥，参见http://www.rsa.com/rsalabs/node.asp?id=2130和RFC5208。

func ParsePKIXPublicKey

func ParsePKIXPublicKey(derBytes []byte) (pub interface{}, err error)

ParsePKIXPublicKey解析一个DER编码的公钥。这些公钥一般在以"BEGIN PUBLIC KEY"出现的PEM块中。

func EncryptPEMBlock

func EncryptPEMBlock(rand io.Reader, blockType string, data, password []byte, alg PEMCipher) (*pem.Block, error)

EncryptPEMBlock使用指定的密码、加密算法加密data，返回一个具有指定块类型，保管加密后数据的PEM块。

func IsEncryptedPEMBlock

func IsEncryptedPEMBlock(b *pem.Block) bool

IsEncryptedPEMBlock返回PEM块b是否是用密码加密了的。

func DecryptPEMBlock

func DecryptPEMBlock(b *pem.Block, password []byte) ([]byte, error)

DecryptPEMBlock接受一个加密后的PEM块和加密该块的密码password，返回解密后的DER编码字节切片。它会检查DEK信息头域，以确定用于解密的算法。如果b中没有DEK信息头域，会返回错误。如果函数发现密码不正确，会返回IncorrectPasswordError。

func ParseCRL

func ParseCRL(crlBytes []byte) (certList *pkix.CertificateList, err error)

ParseCRL从crlBytes中解析CRL（证书注销列表）。因为经常有PEM编码的CRL出现在应该是DER编码的地方，因此本函数可以透明的处理PEM编码，只要没有前导的垃圾数据。

func ParseDERCRL

func ParseDERCRL(derBytes []byte) (certList *pkix.CertificateList, err error)

ParseDERCRL从derBytes中解析DER编码的CRL。

func ParseCertificate

func ParseCertificate(asn1Data []byte) (*Certificate, error)

ParseCertificate从ASN.1 DER数据解析单个证书。

func ParseCertificateRequest

func ParseCertificateRequest(asn1Data []byte) (*CertificateRequest, error)

ParseCertificateRequest解析一个ASN.1 DER数据获取单个证书请求。

func ParseCertificates

func ParseCertificates(asn1Data []byte) ([]*Certificate, error)

ParseCertificates从ASN.1 DER编码的asn1Data中解析一到多个证书。这些证书必须是串联的，且中间没有填充。

func CreateCertificate

func CreateCertificate(rand io.Reader, template, parent *Certificate, pub interface{}, priv interface{}) (cert []byte, err error)

CreateCertificate基于模板创建一个新的证书。会用到模板的如下字段：

SerialNumber、Subject、NotBefore、NotAfter、KeyUsage、ExtKeyUsage、UnknownExtKeyUsage、BasicConstraintsValid、IsCA、MaxPathLen、SubjectKeyId、DNSNames、PermittedDNSDomainsCritical、PermittedDNSDomains、SignatureAlgorithm。

该证书会使用parent签名。如果parent和template相同，则证书是自签名的。Pub参数是被签名者的公钥，而priv是签名者的私钥。

返回的切片是DER编码的证书。

只支持RSA和ECDSA类型的密钥。（pub可以是rsa.PublicKey或ecdsa.PublicKey，priv可以是rsa.PrivateKey或ecdsa.PrivateKey）

func CreateCertificateRequest

func CreateCertificateRequest(rand io.Reader, template *CertificateRequest, priv interface{}) (csr []byte, err error)

CreateCertificateRequest基于模板创建一个新的证书请求。会用到模板的如下字段：

Subject、Attributes、Extension、SignatureAlgorithm、DNSNames、EmailAddresses、IPAddresses。

priv是签名者的私钥。返回的切片是DER编码的证书请求。

只支持RSA（rsa.PrivateKey）和ECDSA（ecdsa.PrivateKey）类型的密钥。

pkix

pkix包提供了共享的、低层次的结构体，用于ASN.1解析和X.509证书、CRL、OCSP的序列化。

type Extension

type Extension struct {
    Id       asn1.ObjectIdentifier
    Critical bool `asn1:"optional"`
    Value    []byte
}

Extension代表一个同名的ASN.1结构体，参见RFC 5280, section 4.2。

type AlgorithmIdentifier

type AlgorithmIdentifier struct {
    Algorithm  asn1.ObjectIdentifier
    Parameters asn1.RawValue `asn1:"optional"`
}

AlgorithmIdentifier代表一个同名的ASN.1结构体，参见RFC 5280, section 4.1.1.2。

type RevokedCertificate

type RevokedCertificate struct {
    SerialNumber   *big.Int
    RevocationTime time.Time
    Extensions     []Extension `asn1:"optional"`
}

RevokedCertificate代表一个同名的ASN.1结构体，参见RFC 5280, section 5.1。

type TBSCertificateList

type TBSCertificateList struct {
    Raw                 asn1.RawContent
    Version             int `asn1:"optional,default:2"`
    Signature           AlgorithmIdentifier
    Issuer              RDNSequence
    ThisUpdate          time.Time
    NextUpdate          time.Time
    RevokedCertificates []RevokedCertificate `asn1:"optional"`
    Extensions          []Extension          `asn1:"tag:0,optional,explicit"`
}

TBSCertificateList代表一个同名的ASN.1结构体，参见RFC 5280, section 5.1。

type AttributeTypeAndValue

type AttributeTypeAndValue struct {
    Type  asn1.ObjectIdentifier
    Value interface{}
}

AttributeTypeAndValue代表一个同名的ASN.1结构体，参见http://tools.ietf.org/html/rfc5280#section-4.1.2.4。

type AttributeTypeAndValueSET

type AttributeTypeAndValueSET struct {
    Type  asn1.ObjectIdentifier
    Value [][]AttributeTypeAndValue `asn1:"set"`
}

AttributeTypeAndValueSET代表AttributeTypeAndValue序列表示的ASN.1序列的集合，参见RFC 2986 (PKCS #10)。

type CertificateList

type CertificateList struct {
    TBSCertList        TBSCertificateList
    SignatureAlgorithm AlgorithmIdentifier
    SignatureValue     asn1.BitString
}

CertificateList代表一个同名的ASN.1结构体，参见RFC 5280, section 5.1。用于认证签名。

func (*CertificateList) HasExpired

func (certList *CertificateList) HasExpired(now time.Time) bool

HasExpired报告证书列表是否已过期。

type RelativeDistinguishedNameSET

type RelativeDistinguishedNameSET []AttributeTypeAndValue

type RDNSequence

type RDNSequence []RelativeDistinguishedNameSET

type Name

type Name struct {
    Country, Organization, OrganizationalUnit []string
    Locality, Province                        []string
    StreetAddress, PostalCode                 []string
    SerialNumber, CommonName                  string
    Names []AttributeTypeAndValue
}

Name代表一个X.509识别名。只包含识别名的公共属性，额外的属性被忽略。

func (*Name) FillFromRDNSequence

func (n *Name) FillFromRDNSequence(rdns *RDNSequence)

func (Name) ToRDNSequence

func (n Name) ToRDNSequence() (ret RDNSequence)