# salt.modules.x509

Manage X509 certificates

Added in version 2015.8.0.

depends:

  M2Crypto

Deprecated since version 3006.0.

Warning

This module has been deprecated and will be removed in Salt 3009 (Potassium). Please migrate to the replacement modules. For breaking changes between both versions, you can refer to the x509_v2 execution module docs.

They will become the default `x509` modules in Salt 3008 (Argon). You can explicitly switch to the new modules before that release by setting `features: {x509_v2: true}` in your minion configuration.

salt.modules.x509.create_certificate(path=None, text=False, overwrite=True, ca_server=None, **kwargs)

  Create an X509 certificate.

  path:

    Path to write the certificate to.

  text:

    If `True`, return the PEM text without writing to a file. Default `False`.

  overwrite:

    If `True` (default), create_certificate will overwrite the entire PEM file. Set False to preserve existing private keys and dh params that may exist in the PEM file.

  kwargs:

    Any of the properties below can be included as additional keyword arguments.

  ca_server:

    Request a remotely signed certificate from ca_server. For this to work, a `signing_policy` must be specified, and that same policy must be configured on the ca_server. See `signing_policy` for details. Also, the salt master must permit peers to call the `sign_remote_certificate` function.

    Example:

    /etc/salt/master.d/peer.conf

        peer:
          .*:
            - x509.sign_remote_certificate

  subject properties:

    Any of the values below can be included to set subject properties Any other subject properties supported by OpenSSL should also work.

    C:

      2 letter Country code

    CN:

      Certificate common name, typically the FQDN.

    Email:

      Email address

    GN:

      Given Name

    L:

      Locality

    O:

      Organization

    OU:

      Organization Unit

    SN:

      SurName

    ST:

      State or Province

  signing_private_key:

    A path or string of the private key in PEM format that will be used to sign this certificate. If neither `signing_cert`, `public_key`, or `csr` are included, it will be assumed that this is a self-signed certificate, and the public key matching `signing_private_key` will be used to create the certificate.

  signing_private_key_passphrase:

    Passphrase used to decrypt the signing_private_key.

  signing_cert:

    A certificate matching the private key that will be used to sign this certificate. This is used to populate the issuer values in the resulting certificate. Do not include this value for self-signed certificates.

  public_key:

    The public key to be included in this certificate. This can be sourced from a public key, certificate, CSR or private key. If a private key is used, the matching public key from the private key will be generated before any processing is done. This means you can request a certificate from a remote CA using a private key file as your public_key and only the public key will be sent across the network to the CA. If neither `public_key` or `csr` are specified, it will be assumed that this is a self-signed certificate, and the public key derived from `signing_private_key` will be used. Specify either `public_key` or `csr`, not both. Because you can input a CSR as a public key or as a CSR, it is important to understand the difference. If you import a CSR as a public key, only the public key will be added to the certificate, subject or extension information in the CSR will be lost.

  public_key_passphrase:

    If the public key is supplied as a private key, this is the passphrase used to decrypt it.

  csr:

    A file or PEM string containing a certificate signing request. This will be used to supply the subject, extensions and public key of a certificate. Any subject or extensions specified explicitly will overwrite any in the CSR.

  basicConstraints:

    X509v3 Basic Constraints extension.

  extensions:

    The following arguments set X509v3 Extension values. If the value starts with `critical`, the extension will be marked as critical.

    Some special extensions are `subjectKeyIdentifier` and `authorityKeyIdentifier`.

    `subjectKeyIdentifier` can be an explicit value or it can be the special string `hash`. `hash` will set the subjectKeyIdentifier equal to the SHA1 hash of the modulus of the public key in this certificate. Note that this is not the exact same hashing method used by OpenSSL when using the hash value.

    `authorityKeyIdentifier` Use values acceptable to the openssl CLI tools. This will automatically populate `authorityKeyIdentifier` with the `subjectKeyIdentifier` of `signing_cert`. If this is a self-signed cert these values will be the same.

    basicConstraints:

      X509v3 Basic Constraints

    keyUsage:

      X509v3 Key Usage

    extendedKeyUsage:

      X509v3 Extended Key Usage

    subjectKeyIdentifier:

      X509v3 Subject Key Identifier

    issuerAltName:

      X509v3 Issuer Alternative Name

    subjectAltName:

      X509v3 Subject Alternative Name

    crlDistributionPoints:

      X509v3 CRL Distribution Points

    issuingDistributionPoint:

      X509v3 Issuing Distribution Point

    certificatePolicies:

      X509v3 Certificate Policies

    policyConstraints:

      X509v3 Policy Constraints

    inhibitAnyPolicy:

      X509v3 Inhibit Any Policy

    nameConstraints:

      X509v3 Name Constraints

    noCheck:

      X509v3 OCSP No Check

    nsComment:

      Netscape Comment

    nsCertType:

      Netscape Certificate Type

  days_valid:

    The number of days this certificate should be valid. This sets the `notAfter` property of the certificate. Defaults to 365.

  version:

    The version of the X509 certificate. Defaults to 3. This is automatically converted to the version value, so `version=3` sets the certificate version field to 0x2.

  serial_number:

    The serial number to assign to this certificate. If omitted a random serial number of size `serial_bits` is generated.

  serial_bits:

    The number of bits to use when randomly generating a serial number. Defaults to 64.

  algorithm:

    The hashing algorithm to be used for signing this certificate. Defaults to sha256.

  copypath:

    An additional path to copy the resulting certificate to. Can be used to maintain a copy of all certificates issued for revocation purposes.

  prepend_cn:

    If set to True, the CN and a dash will be prepended to the copypath's filename.

    Example:

      /etc/pki/issued_certs/www.example.com-DE:CA:FB:AD:00:00:00:00.crt

  signing_policy:

    A signing policy that should be used to create this certificate. Signing policies should be defined in the minion configuration, or in a minion pillar. It should be a YAML formatted list of arguments which will override any arguments passed to this function. If the `minions` key is included in the signing policy, only minions matching that pattern (see match.glob and match.compound) will be permitted to remotely request certificates from that policy. In order to `match.compound` to work salt master must peers permit peers to call it.

    Example:

    /etc/salt/master.d/peer.conf

        peer:
          .*:
            - match.compound

    Example:

        x509_signing_policies:
          www:
            - minions: 'www*'
            - signing_private_key: /etc/pki/ca.key
            - signing_cert: /etc/pki/ca.crt
            - C: US
            - ST: Utah
            - L: Salt Lake City
            - basicConstraints: "critical CA:false"
            - keyUsage: "critical cRLSign, keyCertSign"
            - subjectKeyIdentifier: hash
            - authorityKeyIdentifier: keyid,issuer:always
            - days_valid: 90
            - copypath: /etc/pki/issued_certs/

    The above signing policy can be invoked with `signing_policy=www`

  not_before:

    Initial validity date for the certificate. This date must be specified in the format '%Y-%m-%d %H:%M:%S'.

    Added in version 3001.

  not_after:

    Final validity date for the certificate. This date must be specified in the format '%Y-%m-%d %H:%M:%S'.

    Added in version 3001.

  CLI Example:

      salt '*' x509.create_certificate path=/etc/pki/myca.crt signing_private_key='/etc/pki/myca.key' csr='/etc/pki/myca.csr'}

salt.modules.x509.create_crl(path=None, text=False, signing_private_key=None, signing_private_key_passphrase=None, signing_cert=None, revoked=None, include_expired=False, days_valid=100, digest='')

  Create a CRL

  Depends:

    - PyOpenSSL Python module

  path:

    Path to write the CRL to.

  text:

    If `True`, return the PEM text without writing to a file. Default `False`.

  signing_private_key:

    A path or string of the private key in PEM format that will be used to sign the CRL. This is required.

  signing_private_key_passphrase:

    Passphrase to decrypt the private key.

  signing_cert:

    A certificate matching the private key that will be used to sign the CRL. This is required.

  revoked:

    A list of dicts containing all the certificates to revoke. Each dict represents one certificate. A dict must contain either the key `serial_number` with the value of the serial number to revoke, or `certificate` with either the PEM encoded text of the certificate, or a path to the certificate to revoke.

    The dict can optionally contain the `revocation_date` key. If this key is omitted the revocation date will be set to now. If should be a string in the format "%Y-%m-%d %H:%M:%S".

    The dict can also optionally contain the `not_after` key. This is redundant if the `certificate` key is included. If the `Certificate` key is not included, this can be used for the logic behind the `include_expired` parameter. If should be a string in the format "%Y-%m-%d %H:%M:%S".

    The dict can also optionally contain the `reason` key. This is the reason code for the revocation. Available choices are `unspecified`, `keyCompromise`, `CACompromise`, `affiliationChanged`, `superseded`, `cessationOfOperation` and `certificateHold`.

  include_expired:

    Include expired certificates in the CRL. Default is `False`.

  days_valid:

    The number of days that the CRL should be valid. This sets the Next Update field in the CRL.

  digest:

    The digest to use for signing the CRL. This has no effect on versions of pyOpenSSL less than 0.14

  CLI Example:

      salt '*' x509.create_crl path=/etc/pki/mykey.key \
              signing_private_key=/etc/pki/ca.key \
              signing_cert=/etc/pki/ca.crt \
              revoked="{'compromized-web-key': {'certificate': '/etc/pki/certs/www1.crt', 'revocation_date': '2015-03-01 00:00:00'}}"

salt.modules.x509.create_csr(path=None, text=False, **kwargs)

  Create a certificate signing request.

  path:

    Path to write the certificate to.

  text:

    If `True`, return the PEM text without writing to a file. Default `False`.

  algorithm:

    The hashing algorithm to be used for signing this request. Defaults to sha256.

  kwargs:

    The subject, extension and version arguments from `x509.create_certificate` can be used.

  CLI Example:

      salt '*' x509.create_csr path=/etc/pki/myca.csr public_key='/etc/pki/myca.key' CN='My Cert'

salt.modules.x509.create_private_key(path=None, text=False, bits=2048, passphrase=None, cipher='aes_128_cbc', verbose=True)

  Creates a private key in PEM format.

  path:

    The path to write the file to, either `path` or `text` are required.

  text:

    If `True`, return the PEM text without writing to a file. Default `False`.

  bits:

    Length of the private key in bits. Default 2048

  passphrase:

    Passphrase for encrypting the private key

  cipher:

    Cipher for encrypting the private key. Has no effect if passphrase is None.

  verbose:

    Provide visual feedback on stdout. Default True

    Added in version 2016.11.0.

  CLI Example:

      salt '*' x509.create_private_key path=/etc/pki/mykey.key

salt.modules.x509.expired(certificate)

  Returns a dict containing limited details of a certificate and whether the certificate has expired.

  Added in version 2016.11.0.

  certificate:

    The certificate to be read. Can be a path to a certificate file, or a string containing the PEM formatted text of the certificate.

  CLI Example:

      salt '*' x509.expired "/etc/pki/mycert.crt"

salt.modules.x509.get_pem_entries(glob_path)

  Returns a dict containing PEM entries in files matching a glob

  glob_path:

    A path to certificates to be read and returned.

  CLI Example:

      salt '*' x509.get_pem_entries "/etc/pki/*.crt"

salt.modules.x509.get_pem_entry(text, pem_type=None)

  Returns a properly formatted PEM string from the input text fixing any whitespace or line-break issues

  text:

    Text containing the X509 PEM entry to be returned or path to a file containing the text.

  pem_type:

    If specified, this function will only return a pem of a certain type, for example 'CERTIFICATE' or 'CERTIFICATE REQUEST'.

  CLI Example:

      salt '*' x509.get_pem_entry "-----BEGIN CERTIFICATE REQUEST-----MIICyzCC Ar8CAQI...-----END CERTIFICATE REQUEST"

salt.modules.x509.get_private_key_size(private_key, passphrase=None)

  Returns the bit length of a private key in PEM format.

  private_key:

    A path or PEM encoded string containing a private key.

  CLI Example:

      salt '*' x509.get_private_key_size /etc/pki/mycert.key

salt.modules.x509.get_public_key(key, passphrase=None, asObj=False)

  Returns a string containing the public key in PEM format.

  key:

    A path or PEM encoded string containing a CSR, Certificate or Private Key from which a public key can be retrieved.

  CLI Example:

      salt '*' x509.get_public_key /etc/pki/mycert.cer

salt.modules.x509.get_signing_policy(signing_policy_name)

  Returns the details of a names signing policy, including the text of the public key that will be used to sign it. Does not return the private key.

  CLI Example:

      salt '*' x509.get_signing_policy www

salt.modules.x509.read_certificate(certificate)

  Returns a dict containing details of a certificate. Input can be a PEM string or file path.

  certificate:

    The certificate to be read. Can be a path to a certificate file, or a string containing the PEM formatted text of the certificate.

  CLI Example:

      salt '*' x509.read_certificate /etc/pki/mycert.crt

salt.modules.x509.read_certificates(glob_path)

  Returns a dict containing details of all certificates matching a glob

  glob_path:

    A path to certificates to be read and returned.

  CLI Example:

      salt '*' x509.read_certificates "/etc/pki/*.crt"

salt.modules.x509.read_crl(crl)

  Returns a dict containing details of a certificate revocation list. Input can be a PEM string or file path.

  Depends:

    - OpenSSL command line tool

  crl:

    A path or PEM encoded string containing the CRL to read.

  CLI Example:

      salt '*' x509.read_crl /etc/pki/mycrl.crl

salt.modules.x509.read_csr(csr)

  Returns a dict containing details of a certificate request.

  Depends:

    - OpenSSL command line tool

  csr:

    A path or PEM encoded string containing the CSR to read.

  CLI Example:

      salt '*' x509.read_csr /etc/pki/mycert.csr

salt.modules.x509.sign_remote_certificate(argdic, **kwargs)

  Request a certificate to be remotely signed according to a signing policy.

  argdic:

    A dict containing all the arguments to be passed into the create_certificate function. This will become kwargs when passed to create_certificate.

  kwargs:

    kwargs delivered from publish.publish

  CLI Example:

      salt '*' x509.sign_remote_certificate argdic="{'public_key': '/etc/pki/www.key', 'signing_policy': 'www'}" __pub_id='www1'

salt.modules.x509.verify_crl(crl, cert)

  Validate a CRL against a certificate. Parses openssl command line output, this is a workaround for M2Crypto's inability to get them from CSR objects.

  crl:

    The CRL to verify

  cert:

    The certificate to verify the CRL against

  CLI Example:

      salt '*' x509.verify_crl crl=/etc/pki/myca.crl cert=/etc/pki/myca.crt

salt.modules.x509.verify_private_key(private_key, public_key, passphrase=None)

  Verify that 'private_key' matches 'public_key'

  private_key:

    The private key to verify, can be a string or path to a private key in PEM format.

  public_key:

    The public key to verify, can be a string or path to a PEM formatted certificate, CSR, or another private key.

  passphrase:

    Passphrase to decrypt the private key.

  CLI Example:

      salt '*' x509.verify_private_key private_key=/etc/pki/myca.key \
              public_key=/etc/pki/myca.crt

salt.modules.x509.verify_signature(certificate, signing_pub_key=None, signing_pub_key_passphrase=None)

  Verify that `certificate` has been signed by `signing_pub_key`

  certificate:

    The certificate to verify. Can be a path or string containing a PEM formatted certificate.

  signing_pub_key:

    The public key to verify, can be a string or path to a PEM formatted certificate, CSR, or private key.

  signing_pub_key_passphrase:

    Passphrase to the signing_pub_key if it is an encrypted private key.

  CLI Example:

      salt '*' x509.verify_signature /etc/pki/mycert.pem \
              signing_pub_key=/etc/pki/myca.crt

salt.modules.x509.will_expire(certificate, days)

  Returns a dict containing details of a certificate and whether the certificate will expire in the specified number of days. Input can be a PEM string or file path.

  Added in version 2016.11.0.

  certificate:

    The certificate to be read. Can be a path to a certificate file, or a string containing the PEM formatted text of the certificate.

  CLI Example:

      salt '*' x509.will_expire "/etc/pki/mycert.crt" days=30

salt.modules.x509.write_pem(text, path, overwrite=True, pem_type=None)

  Writes out a PEM string fixing any formatting or whitespace issues before writing.

  text:

    PEM string input to be written out.

  path:

    Path of the file to write the PEM out to.

  overwrite:

    If `True` (default), write_pem will overwrite the entire PEM file. Set False to preserve existing private keys and dh params that may exist in the PEM file.

  pem_type:

    The PEM type to be saved, for example `CERTIFICATE` or `PUBLIC KEY`. Adding this will allow the function to take input that may contain multiple PEM types.

  CLI Example:

      salt '*' x509.write_pem "-----BEGIN CERTIFICATE-----MIIGMzCCBBugA..." path=/etc/pki/mycert.crt