Skip to content

CLAUDE.md

Latest commit

 

History

History
78 lines (51 loc) · 3.07 KB

CLAUDE.md

File metadata and controls

78 lines (51 loc) · 3.07 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Crypt::OpenSSL::X509 is a Perl/C extension providing Perl bindings to OpenSSL's X.509 certificate API. It supports parsing certificates, extracting properties, computing fingerprints, and inspecting extensions — across OpenSSL versions 1.0.x through 4.x.

Build and Test Commands

# Generate Makefile (requires OpenSSL dev files; uses Crypt::OpenSSL::Guess to locate them)
perl Makefile.PL

# Compile C/XS code
make

# Run full test suite
make test

# Run a single test file
perl -Iblib/lib -Iblib/arch t/x509.t

# Install
make install

For author/CI testing with additional quality checks:

AUTHOR_TESTING=1 make test

Architecture

The module uses a hybrid Perl/XS architecture:

  • X509.pm — Public API surface, constants via Exporter, some pure-Perl helpers, and all POD documentation.
  • X509.xs — Core implementation in C using XSLoader. 1600+ lines defining five Perl packages:
    • Crypt::OpenSSL::X509 — Main certificate object (most methods)
    • Crypt::OpenSSL::X509::Extension — Certificate extensions
    • Crypt::OpenSSL::X509::ObjectID — OID handling
    • Crypt::OpenSSL::X509::Name — Distinguished names
    • Crypt::OpenSSL::X509::Name_Entry — Individual name entries

Makefile.PL is generated by Dist::Zilla from dist.ini. Do not edit Makefile.PL directly; modify dist.ini and regenerate, or edit maint/Makefile.PL.include for custom build logic.

OpenSSL Compatibility

The codebase maintains compatibility across OpenSSL 1.0.x–4.x through conditional compilation. Key patterns in X509.xs:

  • Compatibility shims for OpenSSL 1.0 (#if OPENSSL_VERSION_NUMBER < 0x10100000L)
  • OpenSSL 4.x introduced opaque ASN1_STRING types; accessor functions must be used instead of direct struct access (#if OPENSSL_VERSION_NUMBER >= 0x40000000L)
  • Default API compat mode is set to 1.1.0: -DOPENSSL_API_COMPAT=0x10100000L

When adding OpenSSL API calls, check which version introduced/deprecated them and add appropriate #if guards.

Key Implementation Details

  • Memory management: Data passes between C and Perl via OpenSSL BIO (Basic I/O) objects.
  • SubjectAltName parsing: Complex SAN structures are parsed in Perl using Convert::ASN1, not in C.
  • UTF-8 names: X509_NAME entries require special handling for multibyte characters.
  • Test certificates: Live in certs/ (PEM format); used across all test files.

Dependencies

Runtime: Convert::ASN1 (≥0.33), version (≥0.77)
Build: Crypt::OpenSSL::Guess, ExtUtils::MakeMaker
Test: Test::Pod

CI Platforms

GitHub Actions workflows cover: macOS (OpenSSL 1.1), Windows (ActivePerl), Cygwin, and MSYS2/MinGW. All run perl Makefile.PL && make && make test.

Documentation

  • is fully documented with POD in X509.pm. Run perldoc X509.pm
  • README.md is generated from POD using dzil build alternativly pod2markdown X509.pm > README.md. Do not edit README.md directly; edit POD in X509.pm and regenerate.