'\" t
.\"     Title: update-crypto-policies
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 08/24/2019
.\"    Manual: \ \&
.\"    Source: update-crypto-policies
.\"  Language: English
.\"
.TH "UPDATE\-CRYPTO\-POLI" "8" "08/24/2019" "update\-crypto\-policies" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
update-crypto-policies \- manage the policies available to the various cryptographic back\-ends\&.
.SH "SYNOPSIS"
.sp
\fBupdate\-crypto\-policies\fR [\fICOMMAND\fR]
.SH "DESCRIPTION"
.sp
\fBupdate\-crypto\-policies(8)\fR is used to set the policy applicable for the various cryptographic back\-ends, such as SSL/TLS libraries\&. That will be the default policy used by these back\-ends unless the application user configures them otherwise\&.
.sp
The available policies are described in the \fBcrypto\-policies(7)\fR manual page\&.
.sp
The desired system policy is selected in /etc/crypto\-policies/config and this tool will generate the individual policy requirements for all back\-ends that support such configuration\&. After this tool is called the administrator is assured that any application that utilizes the supported back\-ends will follow a policy that adheres to the configured profile\&.
.sp
Note that the above assurance does apply to the extent that applications are configured to follow the default policy (the details vary on the back\-end, see below for more information)\&.
.sp
The generated back\-end policies will be placed in /etc/crypto\-policies/back\-ends\&. Currently the supported back\-ends are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
GnuTLS library
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
OpenSSL library
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
NSS library
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
OpenJDK
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Libkrb5
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
BIND
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
OpenSSH
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Libreswan
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
libssh
.RE
.sp
Applications and languages which rely on any of these back\-ends will follow the system policies as well\&. Examples are apache httpd, nginx, php, and others\&.
.sp
In general after changing the system crypto policies with the update\-crypto\-policies \-\-set command it is recommended to restart the system for the effect to fully take place as the policy configuration files are loaded on application start\-up\&. Otherwise applications started before the command was run need to be restarted to load the updated configuration\&.
.SH "COMMANDS"
.sp
The following commands are available in update\-crypto\-policies tool\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-show: Shows the currently applied crypto policy
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-is\-applied: Returns success if the currently configured policy is already applied\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-set: Sets the current policy and overwrites the config file\&.
.RE
.SH "OPTIONS"
.sp
The following options are available in update\-crypto\-policies tool\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-no\-check: By default this tool does a sanity check on whether the configured policy is accepted by the supported tools\&. This option disables those checks\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-\-no\-reload: By default this tool causes some running applications to reload the configured policy\&. This option skips the reloading\&.
.RE
.SH "APPLICATION SUPPORT"
.sp
Applications in the operating system that provide a default configuration file that includes a cryptographic policy string will be modified gradually to support these policies\&.
.sp
When an application provides a configuration file, the changes needed to utilize the system\-wide policy are the following\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Applications using GnuTLS: If an application allows the configuration of cipher priotities via a string, the special priority string "@SYSTEM" should replace any other priority string\&. Applications which use the default library settings automatically adhere to the policy\&. Applications following the policy inherit the settings for cipher suite preference, TLS and DTLS protocol versions, allowed elliptic curves, and limits for cryptographic keys\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Applications using OpenSSL: If an application allows the configuration of ciphersuite string, the special cipher string "PROFILE=SYSTEM" should replace any other cipher string\&. Applications which use the default library settings automatically adhere to the policy\&. Applications following the policy inherit the settings for cipher suite preference\&. By default the OpenSSL library reads a configuration file when it is initialized\&. If the applicaton does not override loading of the configuration file, the policy also sets the minimum TLS protocol version and default cipher suite preference via this file\&. If the application is long\-running such as the httpd server it has to be restarted to reload the configuration file after policy is changed\&. Otherwise the changed policy cannot take effect\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Applications using NSS: Applications using NSS will load the crypto policies by default\&. They inherit the settings for cipher suite preference, TLS and DTLS protocol versions, allowed elliptic curves, and limits for cryptographic keys\&. Note that unlike OpenSSL and GnuTLS, the NSS policy is enforced by default; to prevent applications from adhering to the policy the NSS_IGNORE_SYSTEM_POLICY environment variable must be set to 1 prior to executing that application\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Applications using Java: No special treatment is required\&. Applications using Java will load the crypto policies by default\&. These applications will then inherit the settings for allowed cipher suites, allowed TLS and DTLS protocol versions, allowed elliptic curves, and limits for cryptographic keys\&. To prevent openjdk applications from adhering to the policy the
<java\&.home>/jre/lib/security/java\&.security
file should be edited to contain
security\&.useSystemPropertiesFile=false\&. Alternatively one can create a file containing the overridden values for
\fIjdk\&.tls\&.disabledAlgorithms\fR,
\fIjdk\&.certpath\&.disabledAlgorithms\fR
and pass the location of that file to Java on the command line using the
\-Djava\&.security\&.properties=<path to file>\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Applications using libkrb5: No special treatment is required\&. Applications will follow the crypto policies by default\&. These applications inherit the settings for the permitted encryption types for tickets as well as the cryptographic key limits for the PKINIT protocol\&. A system\-wide opt\-out is available by deleting the /etc/krb5\&.conf\&.d/crypto\-policies link\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
BIND: This application inherits the set of blacklisted algorithms\&. To opt\-out from the policy, remove the policy include directive in the named\&.conf file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
OpenSSH: Both server and client application inherits the cipher preferences, the key exchange algorithms as well as the GSSAPI key exchange algorithms\&. To opt\-out from the policy for client, override the global ssh_config with a user\-specific configuration in ~/\&.ssh/config\&. See ssh_config(5) for more information\&. To opt\-out from the policy for server, uncomment the line containing CRYPTO_POLICY= in /etc/sysconfig/sshd \&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Libreswan: Both servers and clients inherit the ESP and IKE preferences, if they are not overridden in the connection configuration file\&. Note that due to limitations of libreswan, crypto policies is restricted to supporting IKEv2\&. To opt\-out from the policy, comment the line including
/etc/crypto\-policies/back\-ends/libreswan\&.config
from
/etc/ipsec\&.conf\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Applications using libssh: Both client and server applications using libssh will load the crypto policies by default\&. They inherit the ciphers, key exchange, message authentication, and signature algorithms preferences\&.
.RE
.SH "POLICY CONFIGURATION"
.sp
One of the supported profiles should be set in /etc/crypto\-policies/config and this script should be run afterwards\&.
.sp
In case of a parsing error no policies will be updated\&.
.SH "CUSTOM POLICIES"
.sp
The custom policies can take two forms\&. First form is a full custom policy file which is supported by the update\-crypto\-policies tool in the same way as the policies shipped along the tool in the package\&.
.sp
The second form can be called a subpolicy or policy modifier\&. This form modifies aspects of any base policy file by removing or adding algorithms or protocols\&. The subpolicies can be appended on the update\-crypto\-policies \-\-set command line to the base policy separated by the : character\&. There can be multiple subpolicies appended\&.
.sp
Let\(cqs suppose we have subpolicy NO\-SHA1 that drops support for SHA1 hash and subpolicy GOST that enables support for the various algorithms specified in Russian GOST standards\&. You can set the DEFAULT policy with disabled SHA1 support and enabled GOST support by running the following command:
.sp
update\-crypto\-policies \-\-set DEFAULT:NO\-SHA1:GOST
.sp
This command generates and applies configuration that will be modification of the DEFAULT policy with changes specified in the NO\-SHA1 and GOST subpolicies\&.
.SH "FILES"
.PP
/etc/crypto\-policies/config
.RS 4
The file contains the current system policy\&. It should contain a string of one of the profiles listed in the
\fBcrypto\-policies(7)\fR
page (e\&.g\&., DEFAULT)\&.
.RE
.PP
/etc/crypto\-policies/back\-ends
.RS 4
Contains the generated policies in separated files, and in a format readable by the supported back ends\&.
.RE
.PP
/etc/crypto\-policies/local\&.d
.RS 4
Contains additional files to be appended to the generated policy files\&. The files present must adhere to $app\-XXX\&.config file naming, where XXX is any arbitrary identifier\&. For example, to append a line to GnuTLS\*(Aq generated policy, create a gnutls\-extra\-line\&.config file in local\&.d\&. This will be appended to the generated gnutls\&.config during update\-crypto\-policies\&. These overrides, are only functional for the gnutls, bind, java (openjdk) and krb5 back\-ends\&.
.RE
.SH "SEE ALSO"
.sp
crypto\-policies(7), fips\-mode\-setup(8)
.SH "AUTHOR"
.sp
Written by Nikos Mavrogiannopoulos\&.