kryptos - v1.4.0

kryptos/x509/csr

X.509 Certificate Signing Request (CSR) generation.

Builder for creating PKCS#10 Certificate Signing Requests (CSRs). CSRs are used to request certificates from a Certificate Authority.

Example

import gleam/result
import kryptos/ec
import kryptos/hash
import kryptos/x509
import kryptos/x509/csr

let #(private_key, _) = ec.generate_key_pair(ec.P256)

let subject = x509.name([
  x509.cn("example.com"),
  x509.organization("Acme Inc"),
  x509.country("US"),
])

let assert Ok(builder) =
  csr.new()
  |> csr.with_subject(subject)
  |> csr.with_dns_name("example.com")
  |> result.try(csr.with_dns_name(_, "www.example.com"))

let assert Ok(my_csr) = csr.sign_with_ecdsa(builder, private_key, hash.Sha256)

let pem = csr.to_pem(my_csr)

Types

Builder

opaque </>

A builder for constructing CSRs.

pub opaque type Builder

Built

</>

Phantom type marker for CSRs created via the builder.

pub type Built

Csr

opaque </>

A Certificate Signing Request.

The phantom type parameter tracks how the CSR was created:

  • Csr(Built) - created via sign_with_ecdsa or sign_with_rsa
  • Csr(Parsed) - created via from_pem or from_der

Export functions (to_pem, to_der) work on any Csr(a). Accessor functions (subject, public_key, etc.) require Csr(Parsed).

pub opaque type Csr(status)

CsrError

</>

Error type for CSR parsing failures.

pub type CsrError {
  InvalidPem
  InvalidStructure
  UnsupportedSignatureAlgorithm(x509.Oid)
  UnsupportedKeyType(x509.Oid)
  SignatureVerificationFailed
  UnsupportedVersion(Int)
}

Constructors 

  • InvalidPem
  • InvalidStructure
  • UnsupportedSignatureAlgorithm(x509.Oid)
  • UnsupportedKeyType(x509.Oid)
  • SignatureVerificationFailed
  • UnsupportedVersion(Int)

Parsed

</>

Phantom type marker for CSRs parsed from PEM/DER.

pub type Parsed

Values

attributes

</> 
pub fn attributes(
  csr: Csr(Parsed),
) -> List(#(x509.Oid, BitArray))

Returns any non-extension attributes as raw (OID, value) pairs.

Most CSRs only have the extensionRequest attribute, so this is typically empty.

extensions

</> 
pub fn extensions(
  csr: Csr(Parsed),
) -> List(#(x509.Oid, Bool, BitArray))

Returns any extensions beyond SANs as raw (OID, critical, value) tuples.

This allows access to extensions that kryptos doesn’t have typed representations for. The Bool indicates whether the extension was marked as critical per RFC 5280.

from_der

</> 
pub fn from_der(der: BitArray) -> Result(Csr(Parsed), CsrError)

Parse a DER-encoded CSR and verify its signature.

from_der_unverified

</> 
pub fn from_der_unverified(
  der: BitArray,
) -> Result(Csr(Parsed), CsrError)

Parse a DER-encoded CSR without verifying the signature.

Useful for debugging malformed or partially valid CSRs. The parsed fields may not be trustworthy since the signature was not verified.

from_pem

</> 
pub fn from_pem(pem: String) -> Result(Csr(Parsed), CsrError)

Parse a PEM-encoded CSR and verify its signature.

Returns an error if the PEM is invalid, the structure is malformed, or the signature doesn’t verify against the embedded public key.

from_pem_unverified

</> 
pub fn from_pem_unverified(
  pem: String,
) -> Result(Csr(Parsed), CsrError)

Parse a PEM-encoded CSR without verifying the signature.

Useful for debugging malformed or partially valid CSRs. The parsed fields may not be trustworthy.

new

</> 
pub fn new() -> Builder

Creates a new CSR builder with an empty subject and no extensions.

Use the with_* functions to configure the builder, then call sign_with_ecdsa or sign_with_rsa to generate the signed CSR.

public_key

</> 
pub fn public_key(csr: Csr(Parsed)) -> x509.PublicKey

Returns the public key embedded in a parsed CSR.

sign_with_ecdsa

</> 
pub fn sign_with_ecdsa(
  builder: Builder,
  key: ec.PrivateKey,
  hash: hash.HashAlgorithm,
) -> Result(Csr(Built), Nil)

Signs the CSR with an ECDSA private key.

The public key is derived from the private key and included in the CSR. Recommended hash: Sha256 for P-256, Sha384 for P-384, Sha512 for P-521. Sha1 is supported for legacy compatibility but is cryptographically weak.

sign_with_eddsa

</> 
pub fn sign_with_eddsa(
  builder: Builder,
  key: eddsa.PrivateKey,
) -> Result(Csr(Built), Nil)

Signs the CSR with an EdDSA private key (Ed25519 or Ed448).

Note: Support for EdDSA is limited with browsers and certificate authorities.

sign_with_rsa

</> 
pub fn sign_with_rsa(
  builder: Builder,
  key: rsa.PrivateKey,
  hash: hash.HashAlgorithm,
) -> Result(Csr(Built), Nil)

Signs the CSR with an RSA private key using PKCS#1 v1.5 padding.

The public key is derived from the private key and included in the CSR. Recommended hash: Sha256 for 2048-bit keys, Sha384 or Sha512 for 3072-bit or larger keys. Sha1 is supported for legacy compatibility but is cryptographically weak.

signature_algorithm

</> 
pub fn signature_algorithm(
  csr: Csr(Parsed),
) -> x509.SignatureAlgorithm

Returns the signature algorithm used to sign the CSR.

subject

</> 
pub fn subject(csr: Csr(Parsed)) -> x509.Name

Returns the subject (distinguished name) of a parsed CSR.

subject_alt_names

</> 
pub fn subject_alt_names(
  csr: Csr(Parsed),
) -> List(x509.SubjectAltName)

Returns the Subject Alternative Names from the CSR.

to_der

</> 
pub fn to_der(csr: Csr(a)) -> BitArray

Exports the CSR as DER-encoded bytes.

to_pem

</> 
pub fn to_pem(csr: Csr(a)) -> String

Exports the CSR as a PEM-encoded string.

This is the format typically required when submitting a CSR to a Certificate Authority.

version

</> 
pub fn version(csr: Csr(Parsed)) -> Int

Returns the version of a parsed CSR.

PKCS#10 v1 CSRs always have version 0.

with_dns_name

</> 
pub fn with_dns_name(
  builder: Builder,
  name: String,
) -> Result(Builder, Nil)

Adds a DNS name to the Subject Alternative Names extension.

SANs allow a certificate to be valid for multiple hostnames. Modern browsers require the domain to appear in the SAN extension, not just the Common Name. The name must contain only ASCII characters.

with_email

</> 
pub fn with_email(
  builder: Builder,
  email: String,
) -> Result(Builder, Nil)

Adds an email address to the Subject Alternative Names extension.

Used for S/MIME certificates. The email must contain only ASCII characters.

with_ip

</> 
pub fn with_ip(
  builder: Builder,
  ip: String,
) -> Result(Builder, Nil)

Adds an IP address to the Subject Alternative Names extension.

Accepts IPv4 (e.g., “192.168.1.1”) or IPv6 (e.g., “2001:db8::1”) addresses.

with_subject

</> 
pub fn with_subject(
  builder: Builder,
  subject: x509.Name,
) -> Builder

Sets the distinguished name subject for the CSR.

✨ Search Document