16.2.1.4. CA Connector

privacyIDEA provides connector objects for different Certificate Authorities (CAs).

This module contains the connectors to Certificate Authorities. In this first implementation it is only a local certificate authority.

This module is tested in tests/test_lib_caconnector.py

class privacyidea.lib.caconnectors.localca.ATTR

This is the list Attributes of the Local CA.

CACERT = 'cacert'

CAKEY = 'cakey'

CERT_DIR = 'CertificateDir'

CRL = 'CRL'

CRL_OVERLAP_PERIOD = 'CRL_Overlap_Period'

CRL_VALIDITY_PERIOD = 'CRL_Validity_Period'

CSR_DIR = 'CSRDir'

OPENSSL_CNF = 'openssl.cnf'

TEMPLATE_FILE = 'templates'

WORKING_DIR = 'WorkingDir'

class privacyidea.lib.caconnectors.localca.CONFIG(name)

class privacyidea.lib.caconnectors.localca.LocalCAConnector(name, config=None)

This connector connects to a local CA represented by a CA certificate and key in the local file system. OpenSSL is used.

Required attributes are:

• cakey - the private key of the CA

• cacert - the certificate of the CA

Optional Attributes are:

• List of CDPs

• List of templates

• Key directory

• Default key size

• …

Parameters:

config – A dictionary with all necessary attributes.

Returns:

connector_type = 'local'

static create_ca(name)

Create parameters for a new CA connector. The configuration is requested at the command line in questions and answers. If the configuration is valid, the CA will be created on the file system and the configuration for the new LocalCAConnector is returned.

We are asking for the following:

• Directory (should exist or the current user should be able to create it and write into it)

• Keysize 2048/4096/8192

• Validity of CA certificate

• DN of CA Certificate

• Validity of enrolled certificates

• CRL:

  • default days

  • overlap period

Fixed values: * Hash: SHA256 * Name of Key, and CACert * Name of CRL * We create two templates for users and for servers.

Parameters:

name (str) – The name of the CA connector.

Returns:

The LocalCAConnector configuration

Return type:

dict

create_crl(publish=True, check_validity=False) → str

Create and Publish the CRL.

Parameters:

• publish – Whether the CRL should be published at its CDPs

• check_validity – Onle create a new CRL, if the old one is about to expire. Therefore, the overlap period and the remaining runtime of the CRL is checked. If the remaining runtime is smaller than the overlap period, we recreate the CRL.

Returns:

the CRL location or None, if no CRL was created

classmethod get_caconnector_description()

Return the description of this CA connectors. This contains the name as a key and the possible parameters.

Returns:

resolver description dict

Return type:

dict

get_templates()

Return the dict of available templates, which are read from the template YAML file.

Returns:

dict

revoke_cert(certificate: str, request_id=None, reason='unspecified') → str

Revoke the specified certificate. At this point only the database index.txt is updated.

Parameters:

• certificate (str) – The certificate to revoke in PEM format

• reason (basestring) – One of the available reasons the certificate gets revoked

Returns:

Returns the serial number of the revoked certificate. Otherwise, an error is raised.

set_config(config=None)

Set the configuration of the

Parameters:

config – A dict with specific config values

Returns:

sign_request(csr: str, options: dict = None) → tuple[int, str | None]

Signs a certificate request with the key of the CA.

options may contain the following entries:

• openssl.cnf: Path to the local OpenSSL CA configuration file

• WorkingDir: The directory where the configuration like openssl.cnf

  can be found.

• CSRDir: The directory, where to save the certificate signing

  requests. This is relative to the WorkingDir.

• CertificateDir: The directory where to save the certificates.

  This is relative to the WorkingDir.

• days: Number of days the certificate should be valid (default 365,

  can be overwritten by a given template setting)

• spkac: Whether the CSR is in SPKAC format

• extension: The extension section to use from the config file

• template: The template to use for signing the certificate

Parameters:

• csr (str) – Certificate signing request (PEM string or SPKAC)

• options (dict) – Additional options for signing the CSR (see above)

Returns:

A tuple containing a return value (0) and the certificate object in PEM encoded format

Return type:

tuple

This module contains the connectors to Certificate Authorities. This implementation is for the Microsoft CA via our middleware.

This module is tested in tests/test_lib_caconnector.py

class privacyidea.lib.caconnectors.msca.ATTR

This is the list Attributes of the Microsoft CA connector.

CA = 'ca'

HOSTNAME = 'hostname'

HTTP_PROXY = 'http_proxy'

PORT = 'port'

SSL_CA_CERT = 'ssl_ca_cert'

SSL_CLIENT_CERT = 'ssl_client_cert'

SSL_CLIENT_KEY = 'ssl_client_key'

SSL_CLIENT_KEY_PASSWORD = 'ssl_client_key_password'

USE_SSL = 'use_ssl'

class privacyidea.lib.caconnectors.msca.CONFIG(name)

class privacyidea.lib.caconnectors.msca.MSCAConnector(name, config=None)

This connector connects to our middleware for the Microsoft CA.

Required attributes are:

• hostname - the hostname of the middleware

• port - the port the middleware listens on

• http_proxy - if http proxy should be used

Parameters:

config – A dictionary with all necessary attributes.

Returns:

property connection

connector_type = 'microsoft'

static create_ca(name)

Create parameters for a new CA connector. The configuration is requested at the command line in questions and answers. If the configuration is valid, the CA will be created on the file system and the configuration for the new LocalCAConnector is returned.

We are asking for the following: * hostname of the middleware * port of the middleware * if a http_proxy is used

Parameters:

name (str) – The name of the CA connector.

Returns:

The MSCAConnector configuration

Return type:

dict

classmethod get_caconnector_description()

Return the description of this CA connectors. This contains the name as a key and the possible parameters.

Returns:

connector description

Return type:

dict

get_config(config)

This method helps to format the config values of the CA Connector.

Parameters:

config (dict) – The configuration as it is stored in the database

Returns:

get_cr_status(request_id)

If a certificate needs a CA manager approval the request is in a pending state. This method fetches the state of a requested certificate. This way we can know if the certificate was issued in the meantime.

Parameters:

request_id (int) – id of the request to check

Returns:

Status code of the request

get_issued_certificate(request_id)

If get_csr_status returned a disposition 3, we can fetch the issued certificate.

Parameters:

request_id – The id of the original certificate request

Returns:

The certificate as PEM string

get_specific_options()

Returns:

return the list of available CAs in the domain

get_templates()

Return the dict of available templates

Returns:

String

revoke_cert(certificate, request_id=None, reason=None)

Revoke the specified certificate. At this point only the database index.txt is updated.

Parameters:

• certificate (str) – The certificate to revoke (PEM encodes)

• request_id (int) – The id of the certificate in the certificate authority

• reason (basestring) – One of the available reasons the certificate gets revoked

Returns:

Returns the serial number of the revoked certificate. Otherwise, an error is raised.

set_config(config=None)

Set the configuration of the

Parameters:

config – A dict with specific config values

Returns:

sign_request(csr: str, options: dict = None) → tuple[int, str | None]

Send a signing request to the Microsoft CA

options may contain the following entries:

• template: The name of the certificate template to issue

Parameters:

• csr (PEM string or SPKAC) – Certificate signing request

• options (dict) – Additional options like the validity time or the template or spkac=1

Returns:

Returns a tuple of requestID and the certificate object if cert was provided instantly

Return type:

(int, X509 or None)

16.2.1.4.1. CA Connector functions

This the library for handling CA connector definitions which are stored in the database table “caconnector”.

The code is tested in tests/test_lib_caconnector.py.

privacyidea.lib.caconnector.delete_caconnector(connector_name)

delete a CA connector and all related config entries. If there was no CA connector, that could be deleted, a ResourceNotFoundError is raised.

Parameters:

connector_name (basestring) – The name of the CA connector that is to be deleted

Returns:

The Id of the resolver

Return type:

int

privacyidea.lib.caconnector.export_caconnector(name=None)

Export given or all caconnector configuration

privacyidea.lib.caconnector.get_all_caconnectors()

Shorthand to retrieve all caconnectors of the request-local config object

privacyidea.lib.caconnector.get_caconnector_class(connector_type)

Return the class for a given CA connector type.

Parameters:

connector_type (basestring) – The type of the connector

Returns:

CA Connector Class

privacyidea.lib.caconnector.get_caconnector_config(connector_name)

return the complete config of a given CA connector from the database

Parameters:

connector_name (basestring) – the name of the CA connector

Returns:

the config of the CA connector

Return type:

dict

privacyidea.lib.caconnector.get_caconnector_config_description(caconnector_type)

Get the description of the configuration of a CA connector

Parameters:

caconnector_type (basestring) – the type of the CA connector like “local”

Returns:

configuration description dict that looks like this:

{'local': {'attribute1': 'string',
           'attribute2': 'int'}}

privacyidea.lib.caconnector.get_caconnector_list(filter_caconnector_type=None, filter_caconnector_name=None, return_config=True)

Gets the list of configured CA Connectors from the database

Parameters:

• filter_caconnector_type (string) – Only CA connectors of the given type are returned

• return_config – Whether the configuration should be returned. If False only the list of the CAconncetor names is returned

Return type:

list of the connectors and their configuration

privacyidea.lib.caconnector.get_caconnector_object(connector_name)

create a CA Connector object from a connector_name

Parameters:

connector_name – the name of the CA connector

Returns:

instance of the CA Connector with the loaded config

privacyidea.lib.caconnector.get_caconnector_specific_options(catype, data)

Given the raw data of a CA connector configuration this function returns a dict of all available specific options to this instance of a CA connector.

Parameters:

• catype

• data

Returns:

privacyidea.lib.caconnector.get_caconnector_type(connector_name)

return the type of CA connector

Parameters:

connector_name – The name of the CA connector

Returns:

The type of the CA connector

Return type:

string

privacyidea.lib.caconnector.import_caconnector(data, name=None)

Import caconnector configuration

privacyidea.lib.caconnector.save_caconnector(params)

Create a new CA connector from the given parameters and save it to the database.

If the CA Connector already exists, it is updated. For updating some attributes of an existing CA connector you do not need to pass all attributes again, but only those, which should be changed.

When updating the CA connector the type must not be changed, since another type might require different attributes.

Parameters:

params (dict) – request parameters like “caconnector” (name) and “type” and the specific attributes of the ca connector.

Returns:

the database ID of the CA connector

Return type:

int