# X509Certificate

<a id="x509certificate"></a>

# X509Certificate

```cpp
#include <icy/crypto/x509certificate.h>

class X509Certificate
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:33](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L33)

RAII wrapper for an OpenSSL X509 certificate with PEM loading and inspection.

## Public Methods

| Return | Name | Description |
|--------|------|-------------|
|  | [`X509Certificate`](#x509certificate-1) `explicit` | Constructs an [X509Certificate](#x509certificate) by parsing a PEM-encoded certificate from memory. |
|  | [`X509Certificate`](#x509certificate-2) `explicit` | Constructs an [X509Certificate](#x509certificate) by reading a PEM-encoded certificate from a file. |
|  | [`X509Certificate`](#x509certificate-3) `explicit` | Constructs an [X509Certificate](#x509certificate) taking ownership of an existing OpenSSL X509 object. |
|  | [`X509Certificate`](#x509certificate-4)  | Constructs an [X509Certificate](#x509certificate) from an existing OpenSSL X509 object, optionally sharing ownership via reference count increment. |
|  | [`X509Certificate`](#x509certificate-5)  | Copy-constructs an [X509Certificate](#x509certificate) by duplicating the underlying X509 object. |
|  | [`X509Certificate`](#x509certificate-6) `noexcept` | Move-constructs an [X509Certificate](#x509certificate), transferring ownership from `cert`. |
| [`X509Certificate`](#x509certificate) & | [`operator=`](#operator-241)  | Copy-assigns a certificate, duplicating the underlying X509 object. |
| [`X509Certificate`](#x509certificate) & | [`operator=`](#operator-242) `noexcept` | Move-assigns a certificate, transferring ownership from `cert`. |
| `void` | [`swap`](#swap-12)  | Swaps this certificate with `cert`. |
|  | [`~X509Certificate`](#x509certificate-7)  | Destroys the [X509Certificate](#x509certificate) and releases the underlying OpenSSL X509 object. |
| `const std::string &` | [`issuerName`](#issuername) `const` | Returns the full distinguished name of the certificate issuer. |
| `std::string` | [`issuerName`](#issuername-1) `const` | Extracts a single field from the certificate issuer's distinguished name. |
| `const std::string &` | [`subjectName`](#subjectname) `const` | Returns the full distinguished name of the certificate subject. |
| `std::string` | [`subjectName`](#subjectname-1) `const` | Extracts a single field from the certificate subject's distinguished name. |
| `std::string` | [`commonName`](#commonname) `const` | Returns the common name (CN) from the certificate subject. |
| `void` | [`extractNames`](#extractnames) `const` | Extracts the common name and the set of Subject Alternative Name (SAN) DNS entries from the certificate. |
| [`DateTime`](https://auscaster.com/icey/docs/api-reference/icy-DateTime.md#datetime) | [`validFrom`](#validfrom) `const` | Returns the date and time from which the certificate is valid. |
| [`DateTime`](https://auscaster.com/icey/docs/api-reference/icy-DateTime.md#datetime) | [`expiresOn`](#expireson) `const` | Returns the date and time at which the certificate expires. |
| `void` | [`save`](#save-1) `const` | Writes the certificate in PEM format to an output stream. |
| `void` | [`save`](#save-2) `const` | Writes the certificate in PEM format to a file. |
| `bool` | [`issuedBy`](#issuedby) `const` | Verifies whether this certificate was signed by the given issuer. |
| `const X509 *` | [`certificate`](#certificate-1) `const` | Returns a const pointer to the underlying OpenSSL X509 object. |
| `X509 *` | [`certificate`](#certificate-2)  | Returns a mutable pointer to the underlying OpenSSL X509 object. |

---

<a id="x509certificate-1"></a>

### X509Certificate

`explicit`

```cpp
explicit X509Certificate(const char * data, size_t length)
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:55](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L55)

Constructs an [X509Certificate](#x509certificate) by parsing a PEM-encoded certificate from memory.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `const char *` | Pointer to a buffer containing the PEM-encoded certificate. |
| `length` | `size_t` | Number of bytes in `data`. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the BIO cannot be created or PEM parsing fails. |

---

<a id="x509certificate-2"></a>

### X509Certificate

`explicit`

```cpp
explicit X509Certificate(const std::string & path)
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:61](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L61)

Constructs an [X509Certificate](#x509certificate) by reading a PEM-encoded certificate from a file.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `const std::string &` | Filesystem path to the PEM certificate file. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the file cannot be opened or PEM parsing fails. |

---

<a id="x509certificate-3"></a>

### X509Certificate

`explicit`

```cpp
explicit X509Certificate(X509 * pCert)
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:68](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L68)

Constructs an [X509Certificate](#x509certificate) taking ownership of an existing OpenSSL X509 object.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pCert` | `X509 *` | Non-null pointer to an OpenSSL X509 certificate. This object takes ownership and will call X509_free on destruction. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if `pCert` is null. |

---

<a id="x509certificate-4"></a>

### X509Certificate

```cpp
X509Certificate(X509 * pCert, bool shared)
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:79](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L79)

Constructs an [X509Certificate](#x509certificate) from an existing OpenSSL X509 object, optionally sharing ownership via reference count increment.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `pCert` | `X509 *` | Non-null pointer to an OpenSSL X509 certificate. Ownership is always taken (X509_free called on destruction). |
| `shared` | `bool` | If true, increments the certificate's reference count via X509_up_ref before taking ownership, so the original pointer remains valid after this object is destroyed. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if `pCert` is null. |

---

<a id="x509certificate-5"></a>

### X509Certificate

```cpp
X509Certificate(const X509Certificate & cert)
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:84](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L84)

Copy-constructs an [X509Certificate](#x509certificate) by duplicating the underlying X509 object.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `cert` | const [`X509Certificate`](#x509certificate) & | The certificate to copy. |

---

<a id="x509certificate-6"></a>

### X509Certificate

`noexcept`

```cpp
X509Certificate(X509Certificate && cert) noexcept
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:89](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L89)

Move-constructs an [X509Certificate](#x509certificate), transferring ownership from `cert`.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `cert` | [`X509Certificate`](#x509certificate) && | The certificate to move from; left in a valid but empty state. |

---

<a id="operator-241"></a>

### operator=

```cpp
X509Certificate & operator=(const X509Certificate & cert)
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:95](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L95)

Copy-assigns a certificate, duplicating the underlying X509 object.

#### Returns
Reference to this object.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `cert` | const [`X509Certificate`](#x509certificate) & | The certificate to copy. |

---

<a id="operator-242"></a>

### operator=

`noexcept`

```cpp
X509Certificate & operator=(X509Certificate && cert) noexcept
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:101](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L101)

Move-assigns a certificate, transferring ownership from `cert`.

#### Returns
Reference to this object.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `cert` | [`X509Certificate`](#x509certificate) && | The certificate to move from; left in a valid but empty state. |

---

<a id="swap-12"></a>

### swap

```cpp
void swap(X509Certificate & cert)
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:106](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L106)

Swaps this certificate with `cert`.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `cert` | [`X509Certificate`](#x509certificate) & | The certificate to swap with. |

---

<a id="x509certificate-7"></a>

### ~X509Certificate

```cpp
~X509Certificate()
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:109](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L109)

Destroys the [X509Certificate](#x509certificate) and releases the underlying OpenSSL X509 object.

---

<a id="issuername"></a>

### issuerName

`const`

```cpp
const std::string & issuerName() const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:114](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L114)

Returns the full distinguished name of the certificate issuer.

#### Returns
One-line string representation produced by X509_NAME_oneline.

---

<a id="issuername-1"></a>

### issuerName

`const`

```cpp
std::string issuerName(NID nid) const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:120](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L120)

Extracts a single field from the certificate issuer's distinguished name.

#### Returns
Field value, or an empty string if the field is absent.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `nid` | [`NID`](#nid) | The field to extract (e.g. NID_COMMON_NAME). |

---

<a id="subjectname"></a>

### subjectName

`const`

```cpp
const std::string & subjectName() const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:125](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L125)

Returns the full distinguished name of the certificate subject.

#### Returns
One-line string representation produced by X509_NAME_oneline.

---

<a id="subjectname-1"></a>

### subjectName

`const`

```cpp
std::string subjectName(NID nid) const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:131](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L131)

Extracts a single field from the certificate subject's distinguished name.

#### Returns
Field value, or an empty string if the field is absent.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `nid` | [`NID`](#nid) | The field to extract (e.g. NID_ORGANIZATION_NAME). |

---

<a id="commonname"></a>

### commonName

`const`

```cpp
std::string commonName() const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:138](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L138)

Returns the common name (CN) from the certificate subject.

Convenience wrapper for subjectName(NID_COMMON_NAME).

#### Returns
Common name string, or empty if absent.

---

<a id="extractnames"></a>

### extractNames

`const`

```cpp
void extractNames(std::string & commonName, std::set< std::string > & domainNames) const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:148](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L148)

Extracts the common name and the set of Subject Alternative Name (SAN) DNS entries from the certificate.

If no SAN DNS entries are present and the common name is non-empty, the common name is added to `domainNames` as a fallback.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `commonName` | `std::string &` | Receives the certificate's common name. |
| `domainNames` | `std::set< std::string > &` | Receives all DNS SAN entries (cleared before population). |

---

<a id="validfrom"></a>

### validFrom

`const`

```cpp
DateTime validFrom() const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:156](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L156)

Returns the date and time from which the certificate is valid.

Parsed from the X509 notBefore field.

#### Returns
UTC [DateTime](https://auscaster.com/icey/docs/api-reference/icy-DateTime.md#datetime) representing the start of the validity period.

---

<a id="expireson"></a>

### expiresOn

`const`

```cpp
DateTime expiresOn() const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:163](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L163)

Returns the date and time at which the certificate expires.

Parsed from the X509 notAfter field.

#### Returns
UTC [DateTime](https://auscaster.com/icey/docs/api-reference/icy-DateTime.md#datetime) representing the end of the validity period.

---

<a id="save-1"></a>

### save

`const`

```cpp
void save(std::ostream & stream) const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:169](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L169)

Writes the certificate in PEM format to an output stream.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `stream` | `std::ostream &` | Destination stream to write to. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the BIO cannot be created or write fails. |

---

<a id="save-2"></a>

### save

`const`

```cpp
void save(const std::string & path) const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:175](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L175)

Writes the certificate in PEM format to a file.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `const std::string &` | Filesystem path of the output file (created or truncated). |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::runtime_error` | if the file cannot be opened or write fails. |

---

<a id="issuedby"></a>

### issuedBy

`const`

```cpp
bool issuedBy(const X509Certificate & issuerCertificate) const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:186](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L186)

Verifies whether this certificate was signed by the given issuer.

Extracts the public key from `issuerCertificate` and calls X509_verify. Use this to validate links in a certificate chain.

#### Returns
true if this certificate's signature verifies against the issuer's public key, false otherwise.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `issuerCertificate` | const [`X509Certificate`](#x509certificate) & | The certificate of the purported issuer. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::invalid_argument` | if the issuer certificate has no public key. |

---

<a id="certificate-1"></a>

### certificate

`const`

```cpp
const X509 * certificate() const
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:191](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L191)

Returns a const pointer to the underlying OpenSSL X509 object.

#### Returns
Pointer valid for the lifetime of this [X509Certificate](#x509certificate).

---

<a id="certificate-2"></a>

### certificate

```cpp
X509 * certificate()
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:196](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L196)

Returns a mutable pointer to the underlying OpenSSL X509 object.

#### Returns
Pointer valid for the lifetime of this [X509Certificate](#x509certificate).

## Protected Methods

| Return | Name | Description |
|--------|------|-------------|
| `void` | [`load`](#load-2)  | Parses a PEM-encoded certificate from a memory buffer and stores it. |
| `void` | [`load`](#load-3)  | Reads a PEM-encoded certificate from a file and stores it. |
| `void` | [`init`](#init-16)  | Populates _issuerName and _subjectName from the loaded certificate. |

---

<a id="load-2"></a>

### load

```cpp
void load(const char * data, size_t length)
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:205](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L205)

Parses a PEM-encoded certificate from a memory buffer and stores it.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `data` | `const char *` | Pointer to PEM data. |
| `length` | `size_t` | Number of bytes in `data`. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::logic_error` | if a certificate is already loaded. |
| `std::runtime_error` | if BIO creation or PEM parsing fails. |

---

<a id="load-3"></a>

### load

```cpp
void load(const std::string & path)
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:212](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L212)

Reads a PEM-encoded certificate from a file and stores it.

#### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `path` | `const std::string &` | Filesystem path to the PEM certificate file. |

#### Exceptions

| Exception | Description |
|-----------|-------------|
| `std::logic_error` | if a certificate is already loaded. |
| `std::runtime_error` | if the file cannot be opened or PEM parsing fails. |

---

<a id="init-16"></a>

### init

```cpp
void init()
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:217](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L217)

Populates _issuerName and _subjectName from the loaded certificate.

Called after each successful load or construction from an X509 pointer.

## Public Types

| Name | Description |
|------|-------------|
| [`NID`](#nid)  | Name identifier for extracting fields from a certificate's distinguished name. |

---

<a id="nid"></a>

### NID

```cpp
enum NID
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:40](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L40)

Name identifier for extracting fields from a certificate's distinguished name.

Values correspond to OpenSSL NID constants used with X509_NAME_get_text_by_NID.

| Value | Description |
|-------|-------------|
| `NID_COMMON_NAME` | Common name (CN field). |
| `NID_COUNTRY` | Country code (C field). |
| `NID_LOCALITY_NAME` | Locality / city (L field). |
| `NID_STATE_OR_PROVINCE` | [State](https://auscaster.com/icey/docs/api-reference/icy-State.md#state) or province (ST field). |
| `NID_ORGANIZATION_NAME` | Organization name (O field). |
| `NID_ORGANIZATION_UNIT_NAME` | Organizational unit (OU field). |
## Private Attributes

| Return | Name | Description |
|--------|------|-------------|
| `std::string` | [`_issuerName`](#_issuername)  |  |
| `std::string` | [`_subjectName`](#_subjectname)  |  |
| [`X509Ptr`](https://auscaster.com/icey/docs/api-reference/icy-crypto.md#x509ptr) | [`_certificate`](#_certificate)  |  |

---

<a id="_issuername"></a>

### _issuerName

```cpp
std::string _issuerName
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:225](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L225)

---

<a id="_subjectname"></a>

### _subjectName

```cpp
std::string _subjectName
```

[Defined in src/crypto/include/icy/crypto/x509certificate.h:226](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L226)

---

<a id="_certificate"></a>

### _certificate

```cpp
X509Ptr _certificate
```

Type: [`X509Ptr`](https://auscaster.com/icey/docs/api-reference/icy-crypto.md#x509ptr)

[Defined in src/crypto/include/icy/crypto/x509certificate.h:227](https://github.com/auscaster/icey/blob/main/src/crypto/include/icy/crypto/x509certificate.h#L227)