xref: /openbmc/phosphor-dbus-interfaces/yaml/xyz/openbmc_project/Certs/CSR/Create.interface.yaml (revision a1347418)

description: >
    Implement to create Certificate Signing Request(CSR).

methods:
    - name: GenerateCSR
      description: >
          This command is used to initiate a certificate signing request. This
          command only returns the D-Bus path name for the new CSR object. User
          need to listen on InterfacesAdded signal emitted by
          /xyz/openbmc_project/Certs to retrieve the CSR string after successful
          CSR creation.

          Note: Following Parameters are mandatory or optional based on the
                Redfish documentation.

                Caller is responsible for the input parameter validation.

                If the caller does not wish a field to be included in the
                CSR Request, initialize the Parameter with blank for strings
                and zero for integers.

      parameters:
          - name: AlternativeNames
            type: array[string]
            description: >
                Additional hostnames of the component that is being secured.
          - name: ChallengePassword
            type: string
            description: >
                The challenge password to be applied to the certificate for
                revocation requests.
          - name: City
            type: string
            description: >
                The city or locality of the organization making the request. For
                Example Austin This is a required parameter.
          - name: CommonName
            type: string
            description: >
                The fully qualified domain name of the component that is being
                secured. This is a required parameter.
          - name: ContactPerson
            type: string
            description: >
                The name of the user making the request.
          - name: Country
            type: string
            description: >
                The country of the organization making the request. This is a
                required parameter.
          - name: Email
            type: string
            description: >
                The email address of the contact within the organization making
                the request.
          - name: GivenName
            type: string
            description: >
                The given name of the user making the request.
          - name: Initials
            type: string
            description: >
                The initials of the user making the request.
          - name: KeyBitLength
            type: int64
            description: >
                The length of the key in bits, if needed based on the value of
                the KeyPairAlgorithm parameter.

                Refer https://www.openssl.org/docs/man1.0.2/man1/genpkey.html
          - name: KeyCurveId
            type: string
            description: >
                The curve ID to be used with the key, if needed based on the
                value of the KeyPairAlgorithm parameter.

                Refer https://www.openssl.org/docs/man1.0.2/man1/genpkey.html
          - name: KeyPairAlgorithm
            type: string
            description: >
                The type of key pair for use with signing algorithms.

                Valid built-in algorithm names for private key generation are
                RSA and EC.
          - name: KeyUsage
            type: array[string]
            description: >
                Key usage extensions define the purpose of the public key
                contained in a certificate.

                Valid Key usage extensions and its usage description.

                ClientAuthentication: The public key is used for TLS WWW client
                                      authentication.
                CodeSigning: The public key is used for the signing of
                executable code. CRLSigning: The public key is used for
                verifying signatures on
                            certificate revocation lists (CLRs).
                DataEncipherment: The public key is used for directly
                enciphering
                                  raw user data without the use of an
                intermediate
                                  symmetric cipher.
                DecipherOnly: The public key could be used for deciphering data
                              while performing key agreement.
                DigitalSignature: The public key is used for verifying digital
                                  signatures, other than signatures on
                certificates
                                  and CRLs.
                EmailProtection: The public key is used for email protection.
                EncipherOnly: The public key could be used for enciphering data
                              while performing key agreement.
                KeyCertSign: The public key is used for verifying signatures on
                             public key certificates.
                KeyEncipherment: The public key is used for enciphering private
                or
                                 secret keys.
                NonRepudiation: The public key is used to verify digital
                signatures,
                                other than signatures on certificates and CRLs,
                                and used to provide a non- repudiation service
                that
                                protects against the signing entity falsely
                denying
                                some action.
                OCSPSigning: The public key is used for signing OCSP responses.
                ServerAuthentication: The public key is used for TLS WWW server
                                      authentication.
                Timestamping: The public key is used for binding the hash of an
                              object to a time.
          - name: Organization
            type: string
            description: >
                The legal name of the organization. This should not be
                abbreviated and should include suffixes such as Inc, Corp, or
                LLC. For example, IBM Corp. This is a required parameter.
          - name: OrganizationalUnit
            type: string
            description: >
                The name of the unit or division of the organization making the
                request. This is a required parameter.
          - name: State
            type: string
            description: >
                The state or province where the organization is located. This
                should not be abbreviated. For example, Texas. This is a
                required parameter.
          - name: Surname
            type: string
            description: >
                The surname of the user making the request.
          - name: UnstructuredName
            type: string
            description: >
                The unstructured name of the subject.
      returns:
          - name: path
            type: string
            description: >
                The object path of the D-Bus object to be watch for retrieving
                the CSR string.
      errors:
          - xyz.openbmc_project.Common.Error.InternalFailure