Files

34 KiB

csr

import "github.com/effective-security/xpki/csr"

Package csr provides utilities for creating, parsing, and validating Certificate Signing Requests (CSRs) as defined by RFC 2986.

This package supports:

  • CSR generation with various key types (RSA, ECDSA)
  • CSR parsing and validation
  • Request and key-request types shared with the authority package
  • Extension handling for certificate requests
  • Key request generation for automated certificate enrollment

The package integrates with the cryptoprov package to support hardware-backed private keys and various cryptographic providers.

Index

Constants

const (
    // CurveP256 specifies curve P-256 for ECDSA
    CurveP256 = 256

    // CurveP384 specifies curve P-384 for ECDSA
    CurveP384 = 384

    // CurveP521 specifies curve P-521 for ECDSA
    CurveP521 = 521
)

const (
    // UserNoticeQualifierType defines id-qt-unotice
    UserNoticeQualifierType = "id-qt-unotice"
    // CpsQualifierType defines id-qt-cps
    CpsQualifierType = "id-qt-cps"

    // OneYear duration
    OneYear = Duration(8760 * time.Hour)
)

func ApplySAN

func ApplySAN(template *x509.Certificate, names []string) error

ApplySAN replaces the subject alternative names of template with names parsed by ParseSAN: DNSNames, EmailAddresses, IPAddresses and URIs are replaced (a type with no names becomes nil), and every raw SAN extension is removed from ExtraExtensions, keeping the order of the others. A nil names leaves template unchanged, so the names of a parsed CSR survive; a non-nil empty slice clears them. A nil template is an error. On error template is unchanged.

func DecodeCDP

func DecodeCDP(val []byte) ([]string, error)

DecodeCDP returns list of CDP

func DefaultSigAlgo

func DefaultSigAlgo(priv crypto.Signer) x509.SignatureAlgorithm

DefaultSigAlgo returns the X.509 signature algorithm for priv: the one a SignatureAlgorithmer advertises, else one chosen by key type and size. RSA keys of 2048 and 3072 bits use SHA-256 and keys of 4096 bits or more SHA-512 (NIST SP 800-57 rates 3072-bit RSA at 128 bits, matching SHA-256, and GCP KMS signs 3072-bit keys only with SHA-256, XPKI-114); ECDSA P-256, P-384 and P-521 use SHA-256, SHA-384 and SHA-512. SHA-1 is never returned; other key types give x509.UnknownSignatureAlgorithm.

func EncodeCDP

func EncodeCDP(cdp []string) (*pkix.Extension, error)

EncodeCDP returns CRLDP

func EncodeCDPFull

func EncodeCDPFull(cdp []string, issuer asn1.RawValue) (*pkix.Extension, error)

EncodeCDPFull returns CRLDP

func FindAttr

func FindAttr(attrs []pkix.AttributeTypeAndValue, id asn1.ObjectIdentifier) *pkix.AttributeTypeAndValue

FindAttr returns attribute

func Parse

func Parse(csrBytes []byte) (*x509.Certificate, error)

Parse takes an incoming certificate request and builds a certificate template from it.

func ParseObjectIdentifier

func ParseObjectIdentifier(oidString string) (oid asn1.ObjectIdentifier, err error)

ParseObjectIdentifier parses a dotted-decimal OID string. The whole string must be digits separated by single dots; anything else is an error.

func ParsePEM

func ParsePEM(csrPEM []byte) (*x509.Certificate, error)

ParsePEM takes an incoming certificate request and builds a certificate template from it.

func PopulateName

func PopulateName(raSubject *X509Subject, csrSubject pkix.Name) pkix.Name

PopulateName has functionality similar to Name, except it fills the fields of the resulting pkix.Name with req's if the subject's corresponding fields are empty

func SetSAN

func SetSAN(template *x509.Certificate, names []string)

SetSAN is ApplySAN without an error: a name ParseSAN rejects is skipped with an error log and the valid names are applied. A nil names leaves template unchanged; a non-nil empty slice clears the names.

Deprecated: use ApplySAN, which reports the invalid names.

func SigAlgo

func SigAlgo(algo string, size int) x509.SignatureAlgorithm

SigAlgo returns the signature algorithm for a key of algo ("RSA" or "ECDSA", case-insensitive) and size, as DefaultSigAlgo chooses it from a key: RSA 2048 and 3072 bits SHA-256 (XPKI-114), 4096 bits and above SHA-512; ECDSA by curve size. Other algorithms give x509.UnknownSignatureAlgorithm.

type AllowedFields

AllowedFields provides booleans for fields in the CSR. If a AllowedFields is not present in a CertProfile, all of these fields may be copied from the CSR into the signed certificate. If a AllowedFields *is* present in a CertProfile, only those fields with a `true` value in the AllowedFields may be copied from the CSR to the signed certificate. Note that some of these fields, like Subject, can be provided or partially provided through the API. Since API clients are expected to be trusted, but CSRs are not, fields provided through the API are not subject to validation through this mechanism.

type AllowedFields struct {
    Subject        bool `json:"subject" yaml:"subject"`
    DNSNames       bool `json:"dns" yaml:"dns"`
    IPAddresses    bool `json:"ip" yaml:"ip"`
    EmailAddresses bool `json:"email" yaml:"email"`
    URIs           bool `json:"uri" yaml:"uri"`
}

type BasicConstraints

BasicConstraints CSR information RFC 5280, 4.2.1.9

type BasicConstraints struct {
    IsCA       bool `asn1:"optional"`
    MaxPathLen int  `asn1:"optional,default:-1"`
}

type CertificatePolicy

CertificatePolicy represents the ASN.1 PolicyInformation structure from https://tools.ietf.org/html/rfc3280.html#page-106. Valid values of Type are "id-qt-unotice" and "id-qt-cps"

type CertificatePolicy struct {
    ID         OID                          `json:"oid" yaml:"oid"`
    Qualifiers []CertificatePolicyQualifier `json:"qualifiers" yaml:"qualifiers"`
}

type CertificatePolicyQualifier

CertificatePolicyQualifier represents a single qualifier from an ASN.1 PolicyInformation structure.

type CertificatePolicyQualifier struct {
    Type  string `json:"type" yaml:"type"`
    Value string `json:"value" yaml:"value"`
}

type CertificateRequest

A CertificateRequest encapsulates the API interface to the certificate request functionality.

type CertificateRequest struct {
    // CommonName of the Subject
    CommonName string `json:"common_name" yaml:"common_name"`
    // Names of the Subject
    Names []X509Name `json:"names" yaml:"names"`
    // SerialNumber of the Subject
    SerialNumber string `json:"serial_number,omitempty" yaml:"serial_number,omitempty"`
    // SAN is Subject Alt Names
    SAN []string `json:"san" yaml:"san"`
    // KeyRequest for generated key
    KeyRequest *KeyRequest `json:"key,omitempty" yaml:"key,omitempty"`
    // Extensions for the cert
    Extensions []X509Extension `json:"extensions,omitempty" yaml:"extensions,omitempty"`
}

func (*CertificateRequest) AddSAN

func (r *CertificateRequest) AddSAN(s string)

AddSAN adds a SAN value to the request

func (*CertificateRequest) Name

func (r *CertificateRequest) Name() pkix.Name

Name returns the PKIX name for the request.

func (*CertificateRequest) Validate

func (r *CertificateRequest) Validate() error

Validate provides the default validation logic for certificate authority certificates. The only requirement here is that the certificate have a non-empty subject field.

type DistributionPoint

DistributionPoint defines CDP as per RFC 5280, 4.2.1.14

type DistributionPoint struct {
    DistributionPoint DistributionPointName `asn1:"optional,tag:0"`
    Reason            asn1.BitString        `asn1:"optional,tag:1"`
    CRLIssuer         asn1.RawValue         `asn1:"optional,tag:2"`
}

type DistributionPointName

DistributionPointName is a part of DistributionPoint

type DistributionPointName struct {
    FullName     []asn1.RawValue  `asn1:"optional,tag:0"`
    RelativeName pkix.RDNSequence `asn1:"optional,tag:1"`
}

type Duration

Duration represents a period of time, its the same as time.Duration but supports better marshalling from json

type Duration time.Duration

func (Duration) MarshalJSON

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON encodes our custom Duration value as a quoted version of its underlying value's String() output this means you get a duration with a trailing units indicator, e.g. "10m0s"

func (Duration) String

func (d Duration) String() string

String returns a string formatted version of the duration in a valueUnits format, e.g. 5m0s for 5 minutes

func (Duration) TimeDuration

func (d Duration) TimeDuration() time.Duration

TimeDuration returns this duration in a time.Duration type

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON handles decoding our custom json serialization for Durations json values that are numbers are treated as seconds json values that are strings, can use the standard time.Duration units indicators e.g. this can decode val:100 as well as val:"10m"

func (*Duration) UnmarshalYAML

func (d *Duration) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML handles decoding our custom json serialization for Durations

type GeneralName

GeneralName represents a General Names sequence as defined in RFC 5820 section 4.2.1.6.

GeneralNames ::= SEQUENCE SIZE (1..MAX) OF GeneralName

GeneralName ::= CHOICE {
     otherName                       [0]     OtherName,
     rfc822Name                      [1]     IA5String,
     dNSName                         [2]     IA5String,
     x400Address                     [3]     ORAddress,
     directoryName                   [4]     Name,
     ediPartyName                    [5]     EDIPartyName,
     uniformResourceIdentifier       [6]     IA5String,
     iPAddress                       [7]     OCTET STRING,
     registeredID                    [8]     OBJECT IDENTIFIER }

OtherName ::= SEQUENCE {
     type-id    OBJECT IDENTIFIER,
     value      [0] EXPLICIT ANY DEFINED BY type-id }

EDIPartyName ::= SEQUENCE {
     nameAssigner            [0]     DirectoryString OPTIONAL,
     partyName               [1]     DirectoryString }
type GeneralName struct {
    Raw           asn1.RawValue
    DNSName       string
    DirectoryName pkix.RDNSequence
    EmailAddres   string
    IPAddres      net.IP
    URI           *url.URL
}

func DecodeCDPFull

func DecodeCDPFull(val []byte) ([]string, []GeneralName, error)

DecodeCDPFull returns list of CDP

func (*GeneralName) Parse

func (e *GeneralName) Parse(raw asn1.RawValue) error

Parse parses an DER-encoded ASN.1 data structure and stores the result in the object.

type KeyPurpose

KeyPurpose declares the purpose for keys

type KeyPurpose int

const (
    // Undefined purpose of key
    Undefined KeyPurpose = 0
    // SigningKey specifies the purpose of key to be used in signing/verification operations
    SigningKey KeyPurpose = 1
    // EncryptionKey specifies the purpose of key to be used in encryption/decryption operations
    EncryptionKey KeyPurpose = 2
)

type KeyRequest

KeyRequest contains the algorithm and key size for a new private key.

type KeyRequest struct {
    L   string     `json:"label" yaml:"label"`
    A   string     `json:"algo"  yaml:"algo"`
    S   int        `json:"size"  yaml:"size"`
    P   KeyPurpose `json:"purpose"  yaml:"purpose"`
    // contains filtered or unexported fields
}

func NewKeyRequest

func NewKeyRequest(prov cryptoprov.Provider, label, algo string, keySize int, purpose KeyPurpose) *KeyRequest

NewKeyRequest returns KeyRequest from given parameters

func (*KeyRequest) Algo

func (kr *KeyRequest) Algo() string

Algo returns the requested key algorithm represented as a string.

func (*KeyRequest) Generate

func (kr *KeyRequest) Generate() (crypto.PrivateKey, error)

Generate generates a key as specified in the request. Currently, only ECDSA and RSA are supported.

func (*KeyRequest) Label

func (kr *KeyRequest) Label() string

Label returns the requested key label.

func (*KeyRequest) Purpose

func (kr *KeyRequest) Purpose() int

Purpose returns the purpose of the key .

func (*KeyRequest) SigAlgo

func (kr *KeyRequest) SigAlgo() x509.SignatureAlgorithm

SigAlgo returns an appropriate X.509 signature algorithm given the key request's type and size.

func (*KeyRequest) Size

func (kr *KeyRequest) Size() int

Size returns the requested key size.

type KeyRequestGen

KeyRequestGen contains the algorithm and key size for a new private key.

type KeyRequestGen interface {
    Algo() string
    Label() string
    Size() int
    Generate() (crypto.PrivateKey, error)
    SigAlgo() x509.SignatureAlgorithm
    Purpose() int
}

type OID

OID is the asn1's ObjectIdentifier, provide a custom JSON marshal / unmarshal.

type OID asn1.ObjectIdentifier

func (OID) Equal

func (oid OID) Equal(other OID) bool

Equal reports whether oi and other represent the same identifier.

func (OID) MarshalJSON

func (oid OID) MarshalJSON() ([]byte, error)

MarshalJSON marshals an oid into a JSON string.

func (OID) String

func (oid OID) String() string

func (*OID) UnmarshalJSON

func (oid *OID) UnmarshalJSON(data []byte) (err error)

UnmarshalJSON unmarshals a JSON string into an OID.

func (*OID) UnmarshalYAML

func (oid *OID) UnmarshalYAML(unmarshal func(any) error) error

UnmarshalYAML unmarshals a YAML string into an OID.

type Provider

Provider extends cryptoprov.Crypto functionality to support CSP processing and certificate signing

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

func NewProvider

func NewProvider(provider cryptoprov.Provider) *Provider

NewProvider returns an instance of CSR provider

func (*Provider) CreateRequestAndExportKey

func (c *Provider) CreateRequestAndExportKey(req *CertificateRequest) (csrPEM, key []byte, keyID string, pub crypto.PublicKey, err error)

CreateRequestAndExportKey takes a certificate request and generates a key and CSR from it.

func (*Provider) GenerateKeyAndRequest

func (c *Provider) GenerateKeyAndRequest(req *CertificateRequest) (csrPEM []byte, priv crypto.PrivateKey, keyID string, err error)

GenerateKeyAndRequest takes a certificate request and generates a key and CSR from it.

func (*Provider) NewKeyRequest

func (c *Provider) NewKeyRequest(label, algo string, keySize int, purpose KeyPurpose) *KeyRequest

NewKeyRequest returns KeyRequest from given parameters

func (*Provider) NewSigningCertificateRequest

func (c *Provider) NewSigningCertificateRequest(keyLabel, algo string, keySize int, CN string, names []X509Name, san []string) *CertificateRequest

NewSigningCertificateRequest creates new request for signing certificate

func (*Provider) SignRequest

func (c *Provider) SignRequest(priv crypto.PrivateKey, req *CertificateRequest) (csrPEM []byte, err error)

SignRequest signs a certificate request with priv. req.SAN is parsed by ParseSAN, so an invalid name fails the request instead of being skipped and duplicates are dropped (XPKI-059); the signature algorithm is DefaultSigAlgo(priv).

type SAN

SAN holds subject alternative names classified by type, as ParseSAN returns them. Each list keeps the input order without duplicates; a type with no names is nil.

type SAN struct {
    DNSNames       []string
    EmailAddresses []string
    IPAddresses    []net.IP
    URIs           []*url.URL
}

func ParseSAN

func ParseSAN(names []string) (*SAN, error)

ParseSAN classifies, validates and deduplicates subject alternative names (XPKI-059). Each name is trimmed of surrounding whitespace and must not be empty. It is then, in this order: a URI when it contains "://" (it must parse, have a scheme and be ASCII); an IP address when net.ParseIP accepts it (an IPv4 address is kept in its 4-byte form); an email address when mail.ParseAddress accepts it (the address part is kept, and it must be ASCII); otherwise a DNS name. A DNS name with non-ASCII runes is converted to A-labels first (IDNA mapping, which also lowercases it); an ASCII name keeps its case. The ASCII form must be at most 253 characters of labels separated by dots, each label 1 to 63 letters, digits, hyphens or underscores that neither starts nor ends with a hyphen; a wildcard is allowed only as the whole first label of a name with at least two labels; a trailing dot is invalid. A single label such as "localhost" is valid.

Duplicates are dropped and the first occurrence is kept: DNS names and email addresses compare case-insensitively, IP addresses by value (so "::ffff:10.0.0.1" duplicates "10.0.0.1"), URIs by their serialized form.

Every invalid name is reported; the returned error joins them as `invalid SAN "name": reason`.

func (*SAN) Validate

func (s *SAN) Validate() error

Validate checks the names of s with the rules of ParseSAN and drops duplicates in place, so names that are already classified, such as the names of a parsed CSR, get the same validation as names given as strings (XPKI-059). On error s is unchanged. The returned error joins every invalid name as `invalid SAN "name": reason`.

type SignRequest

SignRequest stores a signature request, which contains the SAN, the PEM-encoded CSR, optional subject information, and the signature profile.

Extensions provided in the request are copied into the certificate, as long as they are in the allowed list for the issuer's policy (an empty list allows all). Extensions requested in the CSR are copied only when explicitly allowed; key usages, SAN, basic constraints, key identifiers and OCSP no-check are always taken from the profile and permitted CSR fields instead.

type SignRequest struct {
    SAN          []string        `json:"san" yaml:"san"`
    Request      string          `json:"certificate_request" yaml:"certificate_request"`
    Subject      *X509Subject    `json:"subject,omitempty" yaml:"subject,omitempty"`
    Profile      string          `json:"profile" yaml:"profile"`
    SerialNumber *big.Int        `json:"serial_number,omitempty" yaml:"serial_number,omitempty"`
    Extensions   []X509Extension `json:"extensions,omitempty" yaml:"extensions,omitempty"`

    // If provided, NotBefore will be used without modification (except
    // for canonicalization) as the value of the notBefore field of the
    // certificate. In particular no backdating adjustment will be made
    // when NotBefore is provided. The signer rejects a NotBefore earlier
    // than now minus the profile backdate.
    NotBefore time.Time `json:"-" yaml:"-"`
    // If provided, NotAfter will be used without modification (except
    // for canonicalization and clipping to the issuer's NotAfter) as the
    // value of the notAfter field of the certificate. The signer rejects a
    // NotAfter that is not after NotBefore or exceeds the profile expiry.
    NotAfter time.Time `json:"-" yaml:"-"`
}

func (*SignRequest) ExtensionsIDs

func (r *SignRequest) ExtensionsIDs() []string

ExtensionsIDs returns list of extension IDs in the request

func (*SignRequest) SubjectCommonName

func (r *SignRequest) SubjectCommonName() string

SubjectCommonName returns CN in the request

type SignatureAlgorithmer

SignatureAlgorithmer is implemented by a crypto.Signer whose key accepts a single X.509 signature algorithm, such as a KMS key whose algorithm fixes the hash and padding. DefaultSigAlgo returns that algorithm when it is not x509.UnknownSignatureAlgorithm.

type SignatureAlgorithmer interface {
    SignatureAlgorithm() x509.SignatureAlgorithm
}

type Signer

Signer interface to sign CSR

type Signer interface {
    SignCertificate(req SignRequest) (cert []byte, err error)
}

type X509Extension

X509Extension represents a raw extension to be included in the certificate. The "value" field must be hex encoded.

type X509Extension struct {
    ID       OID    `json:"id" yaml:"id"`
    Critical bool   `json:"critical" yaml:"critical"`
    Value    string `json:"value" yaml:"value"`
}

func (X509Extension) GetValue

func (ext X509Extension) GetValue() ([]byte, error)

GetValue returns raw value. if prefix is hex or base64, then it's decoded, otherwise hex decoding is tried first then base64

type X509Name

X509Name contains the SubjectInfo fields.

type X509Name struct {
    Country            string `json:"c" yaml:"c"`
    Province           string `json:"st" yaml:"st"`
    Locality           string `json:"l" yaml:"l"`
    Organization       string `json:"o" yaml:"o"`
    OrganizationalUnit string `json:"ou" yaml:"ou"`
    EmailAddress       string `json:"email" yaml:"email"` // 1.2.840.113549.1.9.1
    SerialNumber       string `json:"serial_number" yaml:"serial_number"`
}

type X509Subject

X509Subject contains the information that should be used to override the subject information when signing a certificate.

type X509Subject struct {
    CommonName   string     `json:"common_name" yaml:"common_name"`
    Names        []X509Name `json:"names" yaml:"names"`
    SerialNumber string     `json:"serial_number" yaml:"serial_number"`
}

func (*X509Subject) Name

func (s *X509Subject) Name() pkix.Name

Name returns the PKIX name for the subject.

Generated by gomarkdoc