Scep.idl

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2010 Raritan Inc. All rights reserved.
 */
 
#include <Event.idl>
#include <ServerSSLCert.idl>
 
/**
 * Certificate Management via SCEP
 */
module cert {
 
    /** SCEP interface */
    interface Scep {
 
        constant int NO_ERROR                           = 0;
        constant int ERR_INVALID_PARAMS                 = 1;
 
        /** Data needed for initial enrollment */
        structure EnrollmentData {
            string challenge;                       ///< The SCEP challenge password. Write-only.
            ServerSSLCert.ReqInfo certInfo;   ///< Data of the Certificate Signing Request that will be created
        };
 
        /** Settings for all SCEP enrollments (initial and renewal) */
        structure ScepSettings {
            string caCertFingerprint;       ///< The fingerprint of the trusted CA certificate
            string url;                     ///< SCEP server url
            int renewDaysBeforeExpiry;      ///< Run renewal if the certificate will expire in <n> days
            int pendingWaitTimeSeconds;     ///< In pending state, seconds between polling messages
            int pendingRetries;             ///< In pending state, how many polling messages will be sent before exiting with failure
            boolean skipVerificationOfIssuedCertChain;  ///< Do not verify whether the issued end-entity certificate
                                                        ///< builds a chain of trust up to the SCEP Root CA cert
        };
 
        enumeration EnrollmentRunStatus {
            NOT_RUN,                        ///< Enrollment has not run yet
            STARTED,                        ///< Enrollment run started
            PENDING,                        ///< Enrollment run went to pending state
            SUCCESS,                        ///< Enrollment run succeeded
            FAILED                          ///< Enrollment run failed
        };
 
        structure EnrollmentRunInfo {
            EnrollmentRunStatus status;     ///< Status of the enrollment run. If NOT_RUN, the other values can be ignored.
            time startedAt;                 ///< Unix timestamp (UTC) of when the enrollment started
            time endedAt;                   ///< Unix timestamp (UTC) of when the enrollment ended or 0 if still running
            string failureReason;           ///< In case of status FAILED, a textual description of the error
        };
 
        /** The current status of SCEP */
        structure ScepStatus {
            boolean enabled;                            ///< Is SCEP enabled
            time lastSuccessfulEnrollment;              ///< Unix timestamp (UTC) of the last successful enrollment, or 0 if that has
                                                        ///< not happened with the current SCEP setup (will be reset to 0 with a call
                                                        ///< to \ref enableScep
            EnrollmentRunInfo lastEnrollmentRunInfo;    ///< Info about the last (possibly still ongoing) enrollment run
        };
 
        valueobject ScepStatusChangedEvent extends idl.Event {
            ScepStatus newStatus;
        };
 
        /**
         * Enable SCEP. This will reset a previous SCEP setup and start with the initial enrollment again.
         *
         * @param initialEnrollmentData
         * @param scepSettings
         *
         * @return NO_ERROR              enabled SCEP successfully
         * @return ERR_INVALID_PARAMS    one of the parameters was invalid
         */
        int enableScep(in EnrollmentData initialEnrollmentData, in ScepSettings scepSettings);
 
        /**
         * Disable SCEP and discard all settings of this SCEP setup, allowing
         * manual management of the TLS certificate again.
         * Re-enabling SCEP will start with the initial enrollment again.
         */
        void discardScep();
 
        /**
         * Get the data that is used for the initial enrollment. For Renewals,
         * this is not used anymore.
         *
         * @return initial enrollment data
         */
        EnrollmentData getInitialEnrollmentData();
 
        /**
         * Get the SCEP settings.
         *
         * @return SCEP settings
         */
        ScepSettings getSettings();
 
        /**
         * Get the SCEP status.
         *
         * @return SCEP status
         */
        ScepStatus getStatus();
 
        /**
         * Set SCEP settings of an existing SCEP setup. Note, that this will
         * kill a currently running SCEP enrollment and immediately retry.
         *
         * @return NO_ERROR              changed ScepSettings successfully
         * @return ERR_INVALID_PARAMS    one of the parameters was invalid
         */
        int setSettings(in ScepSettings scepSettings);
 
        /**
         * Get all supported key variants.
         *
         * @return Vector of KeyInfo structures representing all supported key variants
         */
        vector<ServerSSLCert.KeyInfo> getSupportedKeyInfos();
 
    };
 
}