smx509

package
v0.15.6 Latest Latest
Warning

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

 Go to latest Published: Dec 21, 2022 License: MIT Imports: 44 Imported by: 0

Documentation

Overview

Package smx509 parses X.509-encoded keys and certificates include SM2/SM3 support.

It allows parsing and generating certificates, certificate signing requests, certificate revocation lists, and encoded public and private keys. It provides a certificate verifier, complete with a chain builder.

The package targets the X.509 technical profile defined by the IETF (RFC 2459/3280/5280), and as further restricted by the CA/Browser Forum Baseline Requirements. There is minimal support for features outside of these profiles, as the primary goal of the package is to provide compatibility with the publicly trusted TLS certificate ecosystem and its policies and constraints.

On Windows, certificate verification is handled by system APIs, but the package aims to apply consistent validation rules across operating systems.

On macOS, we did NOT support to use system root CA yet due to too many SDK internal package's dependencies.

Index

Constants

View Source 
const (
	NotAuthorizedToSign           = x509.NotAuthorizedToSign
	Expired                       = x509.Expired
	CANotAuthorizedForThisName    = x509.CANotAuthorizedForThisName
	TooManyIntermediates          = x509.TooManyIntermediates
	IncompatibleUsage             = x509.IncompatibleUsage
	NameMismatch                  = x509.NameMismatch
	NameConstraintsWithoutSANs    = x509.NameConstraintsWithoutSANs
	UnconstrainedName             = x509.UnconstrainedName
	TooManyConstraints            = x509.TooManyConstraints
	CANotAuthorizedForExtKeyUsage = x509.CANotAuthorizedForExtKeyUsage
)
View Source 
const (
	UnknownSignatureAlgorithm = x509.UnknownSignatureAlgorithm

	MD2WithRSA       = x509.MD2WithRSA
	MD5WithRSA       = x509.MD5WithRSA // Only supported for signing, not verification.
	SHA1WithRSA      = x509.SHA1WithRSA
	SHA256WithRSA    = x509.SHA256WithRSA
	SHA384WithRSA    = x509.SHA384WithRSA
	SHA512WithRSA    = x509.SHA512WithRSA
	DSAWithSHA1      = x509.DSAWithSHA1   // Unsupported.
	DSAWithSHA256    = x509.DSAWithSHA256 // Unsupported.
	ECDSAWithSHA1    = x509.ECDSAWithSHA1
	ECDSAWithSHA256  = x509.ECDSAWithSHA256
	ECDSAWithSHA384  = x509.ECDSAWithSHA384
	ECDSAWithSHA512  = x509.ECDSAWithSHA512
	SHA256WithRSAPSS = x509.SHA256WithRSAPSS
	SHA384WithRSAPSS = x509.SHA384WithRSAPSS
	SHA512WithRSAPSS = x509.SHA512WithRSAPSS
	PureEd25519      = x509.PureEd25519

	SM2WithSM3 SignatureAlgorithm = 99
)
View Source 
const (
	UnknownPublicKeyAlgorithm = x509.UnknownPublicKeyAlgorithm

	RSA     = x509.RSA
	DSA     = x509.DSA // Only supported for parsing.
	ECDSA   = x509.ECDSA
	Ed25519 = x509.Ed25519
)
View Source 
const (
	KeyUsageDigitalSignature  = x509.KeyUsageDigitalSignature
	KeyUsageContentCommitment = x509.KeyUsageContentCommitment
	KeyUsageKeyEncipherment   = x509.KeyUsageKeyEncipherment
	KeyUsageDataEncipherment  = x509.KeyUsageDataEncipherment
	KeyUsageKeyAgreement      = x509.KeyUsageKeyAgreement
	KeyUsageCertSign          = x509.KeyUsageCertSign
	KeyUsageCRLSign           = x509.KeyUsageCRLSign
	KeyUsageEncipherOnly      = x509.KeyUsageEncipherOnly
	KeyUsageDecipherOnly      = x509.KeyUsageDecipherOnly
)
View Source 
const (
	ExtKeyUsageAny                            = x509.ExtKeyUsageAny
	ExtKeyUsageServerAuth                     = x509.ExtKeyUsageServerAuth
	ExtKeyUsageClientAuth                     = x509.ExtKeyUsageClientAuth
	ExtKeyUsageCodeSigning                    = x509.ExtKeyUsageCodeSigning
	ExtKeyUsageEmailProtection                = x509.ExtKeyUsageEmailProtection
	ExtKeyUsageIPSECEndSystem                 = x509.ExtKeyUsageIPSECEndSystem
	ExtKeyUsageIPSECTunnel                    = x509.ExtKeyUsageIPSECTunnel
	ExtKeyUsageIPSECUser                      = x509.ExtKeyUsageIPSECUser
	ExtKeyUsageTimeStamping                   = x509.ExtKeyUsageTimeStamping
	ExtKeyUsageOCSPSigning                    = x509.ExtKeyUsageOCSPSigning
	ExtKeyUsageMicrosoftServerGatedCrypto     = x509.ExtKeyUsageMicrosoftServerGatedCrypto
	ExtKeyUsageNetscapeServerGatedCrypto      = x509.ExtKeyUsageNetscapeServerGatedCrypto
	ExtKeyUsageMicrosoftCommercialCodeSigning = x509.ExtKeyUsageMicrosoftCommercialCodeSigning
	ExtKeyUsageMicrosoftKernelCodeSigning     = x509.ExtKeyUsageMicrosoftKernelCodeSigning
)

Variables

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

IncorrectPasswordError is returned when an incorrect password is detected.

Functions

func CreateCertificate 

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

CreateCertificate creates a new X.509 v3 certificate based on a template. The following members of template are currently used:

  • AuthorityKeyId
  • BasicConstraintsValid
  • CRLDistributionPoints
  • DNSNames
  • EmailAddresses
  • ExcludedDNSDomains
  • ExcludedEmailAddresses
  • ExcludedIPRanges
  • ExcludedURIDomains
  • ExtKeyUsage
  • ExtraExtensions
  • IPAddresses
  • IsCA
  • IssuingCertificateURL
  • KeyUsage
  • MaxPathLen
  • MaxPathLenZero
  • NotAfter
  • NotBefore
  • OCSPServer
  • PermittedDNSDomains
  • PermittedDNSDomainsCritical
  • PermittedEmailAddresses
  • PermittedIPRanges
  • PermittedURIDomains
  • PolicyIdentifiers
  • SerialNumber
  • SignatureAlgorithm
  • Subject
  • SubjectKeyId
  • URIs
  • UnknownExtKeyUsage

The certificate is signed by parent. If parent is equal to template then the certificate is self-signed. The parameter pub is the public key of the certificate to be generated and priv is the private key of the signer.

The returned slice is the certificate in DER encoding.

The currently supported key types are *rsa.PublicKey, *ecdsa.PublicKey and ed25519.PublicKey. pub must be a supported key type, and priv must be a crypto.Signer with a supported public key.

The AuthorityKeyId will be taken from the SubjectKeyId of parent, if any, unless the resulting certificate is self-signed. Otherwise the value from template will be used.

If SubjectKeyId from template is empty and the template is a CA, SubjectKeyId will be generated from the hash of the public key.

func CreateCertificateRequest 

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

CreateCertificateRequest creates a new certificate request based on a template. The following members of template are used:

  • SignatureAlgorithm
  • Subject
  • DNSNames
  • EmailAddresses
  • IPAddresses
  • URIs
  • ExtraExtensions
  • Attributes (deprecated)

priv is the private key to sign the CSR with, and the corresponding public key will be included in the CSR. It must implement crypto.Signer and its Public() method must return a *rsa.PublicKey or a *ecdsa.PublicKey or a ed25519.PublicKey. (A *rsa.PrivateKey, *ecdsa.PrivateKey or ed25519.PrivateKey satisfies this.)

The returned slice is the certificate request in DER encoding.

func CreateRevocationList 

func CreateRevocationList(rand io.Reader, template *x509.RevocationList, issuer *Certificate, priv crypto.Signer) ([]byte, error)

CreateRevocationList creates a new X.509 v2 Certificate Revocation List, according to RFC 5280, based on template.

The CRL is signed by priv which should be the private key associated with the public key in the issuer certificate.

The issuer may not be nil, and the crlSign bit must be set in KeyUsage in order to use it as a CRL issuer.

The issuer distinguished name CRL field and authority key identifier extension are populated using the issuer certificate. issuer must have SubjectKeyId set.

func DecryptPEMBlock deprecated 

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

DecryptPEMBlock takes a PEM block encrypted according to RFC 1423 and the password used to encrypt it and returns a slice of decrypted DER encoded bytes. It inspects the DEK-Info header to determine the algorithm used for decryption. If no DEK-Info header is present, an error is returned. If an incorrect password is detected an IncorrectPasswordError is returned. Because of deficiencies in the format, it's not always possible to detect an incorrect password. In these cases no error will be returned but the decrypted DER bytes will be random noise.

Deprecated: Legacy PEM encryption as specified in RFC 1423 is insecure by design. Since it does not authenticate the ciphertext, it is vulnerable to padding oracle attacks that can let an attacker recover the plaintext.

func EncryptPEMBlock deprecated 

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

EncryptPEMBlock returns a PEM block of the specified type holding the given DER encoded data encrypted with the specified algorithm and password according to RFC 1423.

Deprecated: Legacy PEM encryption as specified in RFC 1423 is insecure by design. Since it does not authenticate the ciphertext, it is vulnerable to padding oracle attacks that can let an attacker recover the plaintext.

func IsEncryptedPEMBlock deprecated 

func IsEncryptedPEMBlock(b *pem.Block) bool

IsEncryptedPEMBlock returns whether the PEM block is password encrypted according to RFC 1423.

Deprecated: Legacy PEM encryption as specified in RFC 1423 is insecure by design. Since it does not authenticate the ciphertext, it is vulnerable to padding oracle attacks that can let an attacker recover the plaintext.

func MarshalECPrivateKey 

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

MarshalECPrivateKey converts an EC private key to SEC 1, ASN.1 DER form.

This kind of key is commonly encoded in PEM blocks of type "EC PRIVATE KEY". For a more flexible key format which is not EC specific, use MarshalPKCS8PrivateKey.

func MarshalPKCS1PrivateKey 

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

MarshalPKCS1PrivateKey converts an RSA private key to PKCS #1, ASN.1 DER form.

This kind of key is commonly encoded in PEM blocks of type "RSA PRIVATE KEY". For a more flexible key format which is not RSA specific, use MarshalPKCS8PrivateKey.

func MarshalPKCS1PublicKey 

func MarshalPKCS1PublicKey(key *rsa.PublicKey) []byte

MarshalPKCS1PublicKey converts an RSA public key to PKCS #1, ASN.1 DER form.

This kind of key is commonly encoded in PEM blocks of type "RSA PUBLIC KEY".

func MarshalPKCS8PrivateKey 

func MarshalPKCS8PrivateKey(key interface{}) ([]byte, error)

MarshalPKCS8PrivateKey converts a private key to PKCS #8, ASN.1 DER form.

The following key types are currently supported: *rsa.PrivateKey, *ecdsa.PrivateKey, a *sm2.PrivateKey, a *ecdh.PrivateKey a *sm9.SignMasterPrivateKey, a *sm9.SignPrivateKey, a *sm9.EncryptMasterPrivateKey, a *sm9.EncryptPrivateKey and ed25519.PrivateKey. Unsupported key types result in an error.

This kind of key is commonly encoded in PEM blocks of type "PRIVATE KEY".

func MarshalPKIXPublicKey 

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

MarshalPKIXPublicKey converts a public key to PKIX, ASN.1 DER form. The encoded public key is a SubjectPublicKeyInfo structure (see RFC 5280, Section 4.1).

The following key types are currently supported: *rsa.PublicKey, *ecdsa.PublicKey and ed25519.PublicKey. Unsupported key types result in an error.

This kind of key is commonly encoded in PEM blocks of type "PUBLIC KEY".

func MarshalSM2PrivateKey 

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

MarshalSM2PrivateKey convient method to marshal sm2 private key directly

func ParseCRL 

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

ParseCRL parses a CRL from the given bytes. It's often the case that PEM encoded CRLs will appear where they should be DER encoded, so this function will transparently handle PEM encoding as long as there isn't any leading garbage.

func ParseDERCRL 

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

ParseDERCRL parses a DER encoded CRL from the given bytes.

func ParseECPrivateKey 

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

ParseECPrivateKey parses an EC private key in SEC 1, ASN.1 DER form.

This kind of key is commonly encoded in PEM blocks of type "EC PRIVATE KEY".

func ParseName 

func ParseName(raw cryptobyte.String) (*pkix.RDNSequence, error)

ParseName parses a DER encoded Name as defined in RFC 5280.

func ParsePKCS1PrivateKey 

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

ParsePKCS1PrivateKey parses an RSA private key in PKCS #1, ASN.1 DER form.

This kind of key is commonly encoded in PEM blocks of type "RSA PRIVATE KEY".

func ParsePKCS1PublicKey 

func ParsePKCS1PublicKey(der []byte) (*rsa.PublicKey, error)

ParsePKCS1PublicKey parses an RSA public key in PKCS #1, ASN.1 DER form.

This kind of key is commonly encoded in PEM blocks of type "RSA PUBLIC KEY".

func ParsePKCS8PrivateKey 

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

ParsePKCS8PrivateKey parses an unencrypted private key in PKCS #8, ASN.1 DER form.

It returns a *rsa.PrivateKey, a *ecdsa.PrivateKey, a *sm2.PrivateKey, a *sm9.SignMasterPrivateKey, a *sm9.SignPrivateKey, a *sm9.EncryptMasterPrivateKey, a *sm9.EncryptPrivateKey or a ed25519.PrivateKey. More types might be supported in the future.

This kind of key is commonly encoded in PEM blocks of type "PRIVATE KEY".

func ParsePKIXPublicKey 

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

ParsePKIXPublicKey parses a public key in PKIX, ASN.1 DER form. The encoded public key is a SubjectPublicKeyInfo structure (see RFC 5280, Section 4.1).

It returns a *rsa.PublicKey, *dsa.PublicKey, *ecdsa.PublicKey, or ed25519.PublicKey. More types might be supported in the future.

This kind of key is commonly encoded in PEM blocks of type "PUBLIC KEY".

func ParseSM2PrivateKey 

func ParseSM2PrivateKey(der []byte) (*sm2.PrivateKey, error)

ParseSM2PrivateKey parses an SM2 private key

Types

type CertPool 

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

CertPool is a set of certificates.

func NewCertPool 

func NewCertPool() *CertPool

NewCertPool returns a new, empty CertPool.

func SystemCertPool 

func SystemCertPool() (*CertPool, error)

SystemCertPool returns a copy of the system cert pool.

On Unix systems other than macOS the environment variables SSL_CERT_FILE and SSL_CERT_DIR can be used to override the system default locations for the SSL certificate file and SSL certificate files directory, respectively. The latter can be a colon-separated list.

Any mutations to the returned pool are not written to disk and do not affect any other pool returned by SystemCertPool.

New changes in the system cert pool might not be reflected in subsequent calls.

func (*CertPool) AddCert 

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

AddCert adds a certificate to a pool.

func (*CertPool) AppendCertsFromPEM 

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

AppendCertsFromPEM attempts to parse a series of PEM encoded certificates. It appends any certificates found to s and reports whether any certificates were successfully parsed.

On many Linux systems, /etc/ssl/cert.pem will contain the system wide set of root CAs in a format suitable for this function.

func (*CertPool) Clone 

func (s *CertPool) Clone() *CertPool

Clone returns a copy of s.

func (*CertPool) Equal 

func (s *CertPool) Equal(other *CertPool) bool

Equal reports whether s and other are equal.

func (*CertPool) Subjects deprecated 

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

Subjects returns a list of the DER-encoded subjects of all of the certificates in the pool.

Deprecated: if s was returned by SystemCertPool, Subjects will not include the system roots.

type Certificate 

type Certificate x509.Certificate

A Certificate represents an X.509 certificate.

func ParseCertificate 

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

ParseCertificate parses a single certificate from the given ASN.1 DER data.

func ParseCertificatePEM 

func ParseCertificatePEM(data []byte) (*Certificate, error)

func ParseCertificates 

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

ParseCertificates parses one or more certificates from the given ASN.1 DER data. The certificates must be concatenated with no intermediate padding.

func (*Certificate) CheckCRLSignature 

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

CheckCRLSignature checks that the signature in crl is from c.

func (*Certificate) CheckSignature 

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

CheckSignature verifies that signature is a valid signature over signed from c's public key.

func (*Certificate) CheckSignatureFrom 

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

CheckSignatureFrom verifies that the signature on c is a valid signature from parent. SHA1WithRSA and ECDSAWithSHA1 signatures are not supported.

func (*Certificate) CreateCRL 

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

CreateCRL returns a DER encoded CRL, signed by this Certificate, that contains the given list of revoked certificates.

Note: this method does not generate an RFC 5280 conformant X.509 v2 CRL. To generate a standards compliant CRL, use CreateRevocationList instead.

func (*Certificate) Equal 

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

func (*Certificate) ToX509 

func (c *Certificate) ToX509() *x509.Certificate

func (*Certificate) Verify 

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

Verify attempts to verify c by building one or more chains from c to a certificate in opts.Roots, using certificates in opts.Intermediates if needed. If successful, it returns one or more chains where the first element of the chain is c and the last element is from opts.Roots.

If opts.Roots is nil, the platform verifier might be used, and verification details might differ from what is described below. If system roots are unavailable the returned error will be of type SystemRootsError.

Name constraints in the intermediates will be applied to all names claimed in the chain, not just opts.DNSName. Thus it is invalid for a leaf to claim example.com if an intermediate doesn't permit it, even if example.com is not the name being validated. Note that DirectoryName constraints are not supported.

Name constraint validation follows the rules from RFC 5280, with the addition that DNS name constraints may use the leading period format defined for emails and URIs. When a constraint has a leading period it indicates that at least one additional label must be prepended to the constrained name to be considered valid.

Extended Key Usage values are enforced nested down a chain, so an intermediate or root that enumerates EKUs prevents a leaf from asserting an EKU not in that list. (While this is not specified, it is common practice in order to limit the types of certificates a CA can issue.)

Certificates other than c in the returned chains should not be modified.

WARNING: this function doesn't do any revocation checking.

func (*Certificate) VerifyHostname 

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

VerifyHostname returns nil if c is a valid certificate for the named host. Otherwise it returns an error describing the mismatch.

IP addresses can be optionally enclosed in square brackets and are checked against the IPAddresses field. Other names are checked case insensitively against the DNSNames field. If the names are valid hostnames, the certificate fields can have a wildcard as the left-most label.

Note that the legacy Common Name field is ignored.

type CertificateInvalidError 

type CertificateInvalidError = x509.CertificateInvalidError

type CertificateRequest 

type CertificateRequest x509.CertificateRequest

CertificateRequest represents a PKCS #10, certificate signature request.

func ParseCertificateRequest 

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

ParseCertificateRequest parses a single certificate request from the given ASN.1 DER data.

func ParseCertificateRequestPEM 

func ParseCertificateRequestPEM(data []byte) (*CertificateRequest, error)

ParseCertificateRequestPEM parses a single certificate request from the given PEM data.

func (*CertificateRequest) CheckSignature 

func (c *CertificateRequest) CheckSignature() error

CheckSignature reports whether the signature on c is valid.

func (*CertificateRequest) ToX509 

func (c *CertificateRequest) ToX509() *x509.CertificateRequest

type ExtKeyUsage 

type ExtKeyUsage = x509.ExtKeyUsage

ExtKeyUsage represents an extended set of actions that are valid for a given key. Each of the ExtKeyUsage* constants define a unique action.

type KeyUsage 

type KeyUsage = x509.KeyUsage

KeyUsage represents the set of actions that are valid for a given key. It's a bitmap of the KeyUsage* constants.

type PEMCipher 

type PEMCipher int
const (
	PEMCipherDES PEMCipher
	PEMCipher3DES
	PEMCipherAES128
	PEMCipherAES192
	PEMCipherAES256
	PEMCipherSM4
)

Possible values for the EncryptPEMBlock encryption algorithm.

type PublicKeyAlgorithm 

type PublicKeyAlgorithm = x509.PublicKeyAlgorithm

type SignatureAlgorithm 

type SignatureAlgorithm = x509.SignatureAlgorithm

type UnknownAuthorityError 

type UnknownAuthorityError struct {
	Cert *Certificate
	// contains filtered or unexported fields
}

UnknownAuthorityError results when the certificate issuer is unknown

func (UnknownAuthorityError) Error 

func (e UnknownAuthorityError) Error() string

type VerifyOptions 

type VerifyOptions struct {
	// DNSName, if set, is checked against the leaf certificate with
	// Certificate.VerifyHostname or the platform verifier.
	DNSName string

	// Intermediates is an optional pool of certificates that are not trust
	// anchors, but can be used to form a chain from the leaf certificate to a
	// root certificate.
	Intermediates *CertPool
	// Roots is the set of trusted root certificates the leaf certificate needs
	// to chain up to. If nil, the system roots or the platform verifier are used.
	Roots *CertPool

	// CurrentTime is used to check the validity of all certificates in the
	// chain. If zero, the current time is used.
	CurrentTime time.Time

	// KeyUsages specifies which Extended Key Usage values are acceptable. A
	// chain is accepted if it allows any of the listed values. An empty list
	// means ExtKeyUsageServerAuth. To accept any key usage, include ExtKeyUsageAny.
	KeyUsages []ExtKeyUsage

	// MaxConstraintComparisions is the maximum number of comparisons to
	// perform when checking a given certificate's name constraints. If
	// zero, a sensible default is used. This limit prevents pathological
	// certificates from consuming excessive amounts of CPU time when
	// validating. It does not apply to the platform verifier.
	MaxConstraintComparisions int
}

VerifyOptions contains parameters for Certificate.Verify.

Source Files

View all Source files

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.