kryptos/x509

X.509 certificate and CSR types and utilities.

This module provides foundational types and helpers for working with X.509 public key infrastructure. It includes:

Distinguished Names: Type-safe construction of subject/issuer names
Extensions: Subject Alternative Names, Basic Constraints, Key Usage, etc.
Public Keys: Unified representation for RSA, ECDSA, EdDSA, and XDH keys
Signature Algorithms: Common signing algorithms for certificates and CSRs
Certificate Fields: Validity periods, authority key identifiers

Use this module with:

x509/csr for creating and parsing Certificate Signing Requests
x509/certificate for parsing and working with X.509 certificates

Distinguished Names

Distinguished names (DNs) identify subjects and issuers in X.509 structures. They consist of attribute-value pairs like Common Name (CN), Organization (O), and Country (C). Helper functions provide type-safe construction with correct ASN.1 string encodings:

import kryptos/x509

let subject = x509.name([
  x509.cn("example.com"),
  x509.organization("Acme Inc"),
  x509.organizational_unit("Engineering"),
  x509.locality("San Francisco"),
  x509.state("California"),
  x509.country("US"),
])

Extensions

Subject Alternative Names (SANs) specify additional identities:

import kryptos/x509.{DnsName, Email, IpAddress, Uri}

let extensions = x509.Extensions([
  DnsName("www.example.com"),
  DnsName("api.example.com"),
  Email("admin@example.com"),
  Uri("https://example.com/cps"),
])

Types

AttributeValue

opaque </>

An attribute value in a distinguished name.

This type is opaque to ensure values are properly validated for their encoding requirements (e.g., PrintableString for country codes, IA5String for email addresses).

pub opaque type AttributeValue

AuthorityKeyIdentifier

</>

Authority Key Identifier extension. Identifies the public key used to verify the certificate’s signature.

pub type AuthorityKeyIdentifier {
  AuthorityKeyIdentifier(
    key_identifier: option.Option(BitArray),
    authority_cert_issuer: option.Option(List(SubjectAltName)),
    authority_cert_serial_number: option.Option(BitArray),
  )
}

Constructors

AuthorityKeyIdentifier(
  key_identifier: option.Option(BitArray),
  authority_cert_issuer: option.Option(List(SubjectAltName)),
  authority_cert_serial_number: option.Option(BitArray),
)

BasicConstraints

</>

Basic Constraints extension - indicates if cert is a CA.

pub type BasicConstraints {
  BasicConstraints(
    ca: Bool,
    path_len_constraint: option.Option(Int),
  )
}

Constructors

BasicConstraints(
  ca: Bool,
  path_len_constraint: option.Option(Int),
)

ExtendedKeyUsage

</>

Extended Key Usage purposes.

pub type ExtendedKeyUsage {
  ServerAuth
  ClientAuth
  CodeSigning
  EmailProtection
  OcspSigning
}

Constructors

```
ServerAuth
```
TLS server authentication.
```
ClientAuth
```
TLS client authentication.
```
CodeSigning
```
Signing downloadable executable code.
```
EmailProtection
```
Email protection (S/MIME signing and encryption).
```
OcspSigning
```
Signing OCSP responses.

Extensions

</>

X.509 certificate extensions.

pub type Extensions {
  Extensions(subject_alt_names: List(SubjectAltName))
}

Constructors

Extensions(subject_alt_names: List(SubjectAltName))

KeyUsage

</>

Key Usage flags for certificates.

pub type KeyUsage {
  DigitalSignature
  NonRepudiation
  KeyEncipherment
  DataEncipherment
  KeyAgreement
  KeyCertSign
  CrlSign
  EncipherOnly
  DecipherOnly
}

Constructors

```
DigitalSignature
```
Verify digital signatures (other than certificates and CRLs).
```
NonRepudiation
```
Verify signatures for non-repudiation services (also called contentCommitment).
```
KeyEncipherment
```
Encipher private or secret keys (e.g., RSA key transport).
```
DataEncipherment
```
Directly encrypt raw user data (without key agreement).
```
KeyAgreement
```
Key agreement protocols (e.g., Diffie-Hellman).
```
KeyCertSign
```
Verify signatures on public key certificates (CA certificates).
```
CrlSign
```
Verify signatures on certificate revocation lists.
```
EncipherOnly
```
With KeyAgreement, may only encipher data during key agreement.
```
DecipherOnly
```
With KeyAgreement, may only decipher data during key agreement.

Name

</>

An X.509 distinguished name, consisting of a sequence of RDNs.

pub type Name {
  Name(rdns: List(Rdn))
}

Constructors

```
Name(rdns: List(Rdn))
```

Oid

</>

An ASN.1 Object Identifier represented as a list of integer components.

pub type Oid {
  Oid(components: List(Int))
}

Constructors

```
Oid(components: List(Int))
```

PublicKey

</>

A public key extracted from an X.509 structure (CSR or certificate).

pub type PublicKey {
  EcPublicKey(ec.PublicKey)
  RsaPublicKey(rsa.PublicKey)
  EdPublicKey(eddsa.PublicKey)
  XdhPublicKey(xdh.PublicKey)
}

Constructors

```
EcPublicKey(ec.PublicKey)
```
An elliptic-curve public key (e.g., P-256, P-384).
```
RsaPublicKey(rsa.PublicKey)
```
An RSA public key.
```
EdPublicKey(eddsa.PublicKey)
```
An EdDSA public key (Ed25519 or Ed448).
```
XdhPublicKey(xdh.PublicKey)
```
An XDH public key (e.g., Curve25519 or Curve448).

Rdn

</>

A Relative Distinguished Name (RDN), containing one or more attribute-value pairs.

pub type Rdn {
  Rdn(attributes: List(#(Oid, AttributeValue)))
}

Constructors

Rdn(attributes: List(#(Oid, AttributeValue)))

SignatureAlgorithm

</>

Signature algorithm used in X.509 structures.

pub type SignatureAlgorithm {
  RsaSha1
  RsaSha256
  RsaSha384
  RsaSha512
  EcdsaSha1
  EcdsaSha256
  EcdsaSha384
  EcdsaSha512
  Ed25519
  Ed448
}

Constructors

```
RsaSha1
```
RSA with SHA-1, suitable for legacy systems.
```
RsaSha256
```
RSA with SHA-256
```
RsaSha384
```
RSA with SHA-384
```
RsaSha512
```
RSA with SHA-512
```
EcdsaSha1
```
ECDSA with SHA-1, for legacy elliptic curve systems.
```
EcdsaSha256
```
ECDSA with SHA-256
```
EcdsaSha384
```
ECDSA with SHA-384
```
EcdsaSha512
```
ECDSA with SHA-512
```
Ed25519
```
Edwards-Curve Digital Signature Algorithm using Ed25519
```
Ed448
```
Edwards-Curve Digital Signature Algorithm using Ed448

SubjectAltName

</>

A Subject Alternative Name entry for X.509 extensions.

pub type SubjectAltName {
  DnsName(String)
  IpAddress(BitArray)
  Email(String)
  Uri(String)
  DirectoryName(Name)
  RegisteredId(Oid)
  OtherName(oid: Oid, value: BitArray)
  Unknown(tag: Int, value: BitArray)
}

Constructors

```
DnsName(String)
```
A DNS hostname (e.g., “example.com”).
```
IpAddress(BitArray)
```
An IP address (4 bytes for IPv4, 16 bytes for IPv6).
```
Email(String)
```
An email address (e.g., “user@example.com”).
```
Uri(String)
```
A Uniform Resource Identifier (e.g., “https://example.com/path”).
```
DirectoryName(Name)
```
A distinguished name, used when a certificate identifies a directory entity.
```
RegisteredId(Oid)
```
A registered OID identifying a name form (e.g., for hardware modules).
```
OtherName(oid: Oid, value: BitArray)
```
An application-specific name form with an OID type and raw value.
```
Unknown(tag: Int, value: BitArray)
```
An unknown GeneralName type with its raw tag byte and value. Returned when parsing encounters an unrecognized SAN type.

Validity

</>

Certificate validity period from not before to not after (inclusive).

pub type Validity {
  Validity(
    not_before: timestamp.Timestamp,
    not_after: timestamp.Timestamp,
  )
}

Constructors

Validity(
  not_before: timestamp.Timestamp,
  not_after: timestamp.Timestamp,
)

Values

attribute_value_to_string

</>

pub fn attribute_value_to_string(value: AttributeValue) -> String

Extracts the string value from an AttributeValue.

Returns the underlying string regardless of encoding type (UTF8String, PrintableString, or IA5String).

cn

</>

pub fn cn(value: String) -> #(Oid, AttributeValue)

Creates a Common Name (CN) attribute.

The Common Name typically contains the primary identifier for the subject, such as a domain name for server certificates or a person’s name for client certificates.

Parameters

value: The common name value (e.g., “example.com”)

Returns

A Common Name attribute tuple.

country

</>

pub fn country(value: String) -> #(Oid, AttributeValue)

Creates a Country (C) attribute.

Uses PrintableString encoding as required by X.520.

Important: The value must be a two-letter uppercase ISO 3166-1 alpha-2 country code (e.g., “US”, “GB”, “DE”). Non-ASCII or incorrectly formatted values will produce non-compliant DER that may be rejected by CAs and clients.

Parameters

value: The two-letter country code (e.g., “US”, “GB”, “DE”)

Returns

A Country attribute tuple.

email_address

</>

pub fn email_address(value: String) -> #(Oid, AttributeValue)

Creates an Email Address attribute.

Note: emailAddress in the DN is deprecated; prefer using Subject Alternative Names via csr.with_email instead.

Important: The value must contain only ASCII characters. Non-ASCII values will produce non-compliant DER that may be rejected by CAs and clients.

Parameters

value: The email address (e.g., “admin@example.com”)

Returns

An Email Address attribute tuple.

locality

</>

pub fn locality(value: String) -> #(Oid, AttributeValue)

Creates a Locality (L) attribute.

Parameters

value: The city or locality name (e.g., “San Francisco”)

Returns

A Locality attribute tuple.

name

</>

pub fn name(attributes: List(#(Oid, AttributeValue))) -> Name

Builds a distinguished name from a list of attribute-value pairs.

Creates a Name with each attribute in its own Relative Distinguished Name (RDN). This produces the standard X.509 format where attributes are displayed as “CN = x, O = y”.

Parameters

attributes: A list of OID and value tuples (use helper functions like cn, organization, country, etc.)

Returns

A Name suitable for use as a CSR subject.

name_to_string

</>

pub fn name_to_string(name: Name) -> String

Converts a distinguished name to a human-readable string.

Formats the name in OpenSSL style: “CN=example.com, O=Acme Inc, C=US”

Known OIDs are displayed with their standard abbreviations (CN, O, OU, C, ST, L). Unknown OIDs are displayed in dotted-decimal notation (e.g., “1.2.3.4=value”).

organization

</>

pub fn organization(value: String) -> #(Oid, AttributeValue)

Creates an Organization (O) attribute.

Identifies the organization or company name associated with the certificate.

Parameters

value: The organization name (e.g., “Acme Inc”)

Returns

An Organization attribute tuple.

organizational_unit

</>

pub fn organizational_unit(
  value: String,
) -> #(Oid, AttributeValue)

Creates an Organizational Unit (OU) attribute.

Identifies a subdivision within an organization, such as a department or team name.

Parameters

value: The organizational unit name (e.g., “Engineering”)

Returns

An Organizational Unit attribute tuple.

state

</>

pub fn state(value: String) -> #(Oid, AttributeValue)

Creates a State or Province (ST) attribute.

Parameters

value: The state or province name (e.g., “California”)

Returns

A State/Province attribute tuple.