Cryptographic Software Inventory

Cryptographic Software Inventory

This is a DRAFT in progress for the purposes of review/input into the InCommon CEWG. It will eventually be maintained officially as documentation of the Shibboleth IdP’s cryptpgraphic usage and considerations for future adoption of new algorithms and/or changes to the cryptographic landscape.

This is a use case oriented review of the Shibboleth IdP software and its plugins. Each use case is discussed in terms of a set of common considerations regarding the use of cryptography of various kinds and the implications on forced or desired changes to the algorithms used.

Standards and specifications used or implemented by the software are also noted along with any relevant caveats or context.

Terminology

Term / Abbreviation

Definition

Term / Abbreviation

Definition

AES-GCM

Advanced Encryption Standard in Galois-Counter Mode, a standard encryption algorithm that includes a built-in MAC

IV

Initialization vector, an input to most symmetric encryption algorithms

JCA

Java Cryptography Architecture

MAC

Message Authentication Code, used to leverage a shared key to implement integrity protection over data

Specifications

The below use cases are in addition to the use of, or the implementations of, these open specifications and standards that contain or specify cryptographic behavior:

  • Used

    • TLS (various versions)

    • X.509 / PKIX

    • PKCS #12 and RFC 7468 (PEM, etc.) for parsing cryptographic material

    • OpenPGP

    • Kerberos V5 / GSS-API

    • XML Signature / Encryption 1.1

    • JOSE

  • Implemented (but see below):

    • SAML 1.0 / 1.1 / 2.0

    • OpenID Connect / OAuth

    • OATH

    • WebAuthn / FIDO

Qualifications / Caveats

SAML

The SAML implementation is implemented fully by the project and does not use any third-party SAML libraries (we in fact produce a library commonly used, and misused, by others).

There are a variety of extension specifications published after SAML 2.0 was finalized that add enhanced or more precisely specified behavior regarding cryptographic negotiation, and this software supports all of them. It also supports an additional, proprietary extension specification that is now deprecated covering the use of PKIX (see ShibMetaExt V1.0).

The IdP supports a significant subset of the specifcations, but does not include the following portions:

  • NameID Management

  • Authentication / Authorization Decision Queries

  • Any Holder of Key Profiles

OpenID / OAuth

The implementation relies on primitives from the Nimbus libraries from Connect2id but with most of the “functional” layers implemented on top of those primitives from scratch.

OATH

The TOTP plugin naturally supports only TOTP and HOTP is not supported.

The implementation of TOTP relies on a Google library.

The plugin does not support tracking of skew on a per-token basis, but this limitation causes the implementation to function more securely (but less usably).

Kerberos V5 / GSS-API

We do not directly implement these protocols but do leverage Java’s API for the exchanges defined by the “SPNEGO” mechanism originally used by Microsoft, which is a form of GSS-API implemented over HTTP using Kerberos as a mechanism, and we also leverage the same API server-side to implement a more secure form of Kerberos validation. In both cases, the supported algorithms and all aspects of that evolution are dictated by Java.

WebAuthn

TBD

Use Cases

Non-standard, non-obvious, or unusual use cases are described in more depth below.

In the default configuration, IdP “sessions” maintaining cross-request state with the client are stored in the client in HTML Storage. The data must be integrity-protected, and by convention is kept confidental to avoid exposure of PII to malware that may infect a client. A component called a DataSealer uses symmetric encryption plus a message authentication code to “seal” the data. How does the use-case relate to the software’s intended purpose? Sessions are generally required for “expected” operation of the IdP, though they are technically optional. Session data may be stored server-side, at a cost in general system reliability (because clustered deployment requires a storage mechanism external to the IdP, introducing a wide range of failure modes). Does the use case involve two or more independent software implementers being able to produce and consume ciphertext for the other or is it self-contained and lacking a requirement for interoperability? The data is never intended to be consumed by any third party software or process and the specific format and mechanics used are undocumented and left as a detail of the implementation. Are there standards defining/constraining which algorithms are usable for the use case? No. 1 Is the output ephemeral or durable and for what expected lifetime? The data is durable for the life of a session, which can vary quite a bit based on policy, though usually it is less than a day. In principle it could have an extended lifetime, but the implementation includes provisions for regularly updating the data so that it is continually “re-encrypted” under a current key. Does the ciphertext provide sufficient information about the algorithm(s) used to allow for it to be consumed arbitrarily later? Not presently, but since the format is internal to the software, it could in principle evolve to include this if it were needed. What are the algorithms supported for this use case in current versions of the platform? Currently, only AES-GCM with variable key size (128, 192, 256) depending on the configured key. Does a process exist for rotating/changing the key(s) involved in the use case? If this is a standardized process, please reference it, and if not, please describe it. If there is an existing recommended policy regarding rotation frequency, please note that. A command line tool and Java class are provided to maintain a set of files that track a default key and a variable size history of older keys, but it is a custom implementation. Is is assumed the files can be copied or accessed from a shared fle system by all servers in a cluster. A pluggable interface is used to allow alternative implementations. It is suggested that the key be changed daily or so depending on load, but in principle this is not strictly necessary as a random IV is used during each operation to prevent known ciphertext attacks. Does a process exist for revoking/expiring the key(s) involved in the use case? If this is a standardized process, please reference it, and if not, please describe it. Revoking or expiring a key can be accomplished by simply removing it from the source of keys used by the implementation at the cost of losing the ability to recover sessions encrypted by that particular key. This is considered by most a trivial disruption in comparison to the risk. What degree of cryptographic agility exists in the particular use case? Because the consumption of the data is purely internal to the implementation, it is possible to update the software unilaterally to alter or extend the set of supported algorithms. Changes to the encryption format would likely be required to account for the possibility of alternate algorithms and/or specifying them in the configuration, but this would be possible without coordination with third parties or major disruption to the software development lifecycle. However, changes to the format or algorithm set would create implications during rolling upgrades (if a node on one version was unable to create or consume data for or from another version) and this would have to be documented for specific releases. In practice, sessions would probably be invalidated in such cases as this would not be a major functional problem. In principle any authenticated encryption algorithm supported by the JCA could be used without major disruption or difficulty. Using unauthenticated encryption algorithms would require a reimplementation using a layered design to include a MAC, and would introduce additional risk from implementation mistakes. At present, AES-GCM appears to be the only authenticated encryption algorithm required to be implemented by the JCA. What is the impact of a compromise on the software’s purpose or a deployer’s data or infrastructure in functional (rather than assumed risk) terms? Very significant/catastrophic in the case of a compromise to the integrity property. Compromise of the confidentiality property would not be considered a terribly significant problem/risk. As this use case implies session state is primarily stored client-side, so a compromise of integrity would result in an attacker having the ability to forge session state, allowing the IdP to be subverted to issue authentication tokens for any user to any service in most configurations. A key compromise would be very easy to recover from (simply changing the key and removing the compromised one suffices) but a break in the AES-GCM algorithm or a vulnerability in the implementation would require a software update to the IdP (and an alternative algorithm or hybrid approach would need to be used, see also the previous answer). Are there assumptions about how a deployer implements or uses the feature(s) that impact the answers above? Some of the discussion is based on the default implementation of the key “strategy” supplied with the software that handles accessing keys. In principle, an alternative implementation built by a third party could impact some of the answers.
The default configuration of the IdP and the OIDC plugins use the same DataSealer component described in the Client-Side Session Storage use case to encrypt and integrity protect a few different kinds of opaque, time-limited data provided to third parties such that it is statelessly recoverable in a secure fashion. The functional aspects share enough in common to be grouped together as a single use case and include: Transient SAML Name Identifier values OAuth authorization codes as defined by the “code” response type Custom claims embedded in JWT-formatted OAuth tokens of various sorts Opaque OAuth tokens of various sorts To differing degrees, these use cases share a common set of requirements: The data must be recoverable, confidential, and integrity protected (tamper-proof) The data must contain a verifiable expiration The data must be usable across different nodes of a cluster without shared state other than a shared key How does the use-case relate to the software’s intended purpose? All of the uses amount to a means of sharing data with a third party that may contain information about a subject (possibly simply an identity, but sometimes additional data) that is meant to be used in a subsequent “API call” of sorts such that the API client’s use must be verified as legitimate and time-limited. Sometimes such tokens are “bearer” tokens but may also contain the identity of the token wielder authenticated via other means or contain other sealed information limiting/scoping their use. For example, SAML transient identifiers would contain the identity of an SP authorized to return them in a query. OAuth access/refresh tokens would contain the OAuth client identity, and might optionally support more advanced usage requirements. In each case, the data is considered opaque to the third party to whom it is given, must be tamper-proof, and is presumed in some cases to need confidentiality for privacy reasons. Does the use case involve two or more independent software implementers being able to produce and consume ciphertext for the other or is it self-contained and lacking a requirement for interoperability? While the data in each case is given to a third party, it never intended to be parsed or understood by that party, rather simply returned in the context of some other documented interaction. The specific format and mechanics used to create and protect the data are undocumented and left as a detail of the implementation. Are there standards defining/constraining which algorithms are usable for the use case? No. 1 Is the output ephemeral or durable and for what expected lifetime? The data is durable for a lifetime that varies by use case but is usually configurable and measured in hours (or less). In principle it could have an extended lifetime, and the specific key used at a particular time to create the data would need to remain accessible throughout that lifetime. Does the ciphertext provide sufficient information about the algorithm(s) used to allow for it to be consumed arbitrarily later? Not presently, but since the format is internal to the software, it could in principle evolve to include this if it were needed. What are the algorithms supported for this use case in current versions of the platform? Currently, only AES-GCM with variable key size (128, 192, 256) depending on the configured key. Does a process exist for rotating/changing the key(s) involved in the use case? If this is a standardized process, please reference it, and if not, please describe it. If there is an existing recommended policy regarding rotation frequency, please note that. A command line tool and Java class are provided to maintain a set of files that track a default key and a variable size history of older keys, but it is a custom implementation. Is is assumed the files can be copied or accessed from a shared fle system by all servers in a cluster. A pluggable interface is used to allow alternative implementations. It is suggested that the key be changed daily or so depending on load, but in principle this is not strictly necessary as a random IV is used during each operation to prevent known ciphertext attacks. Does a process exist for revoking/expiring the key(s) involved in the use case? If this is a standardized process, please reference it, and if not, please describe it. Revoking or expiring a key can be accomplished by simply removing it from the source of keys used by the implementation at the cost of losing the ability to support the tokens or other data encrypted by that particular key. Use of such tokens or data would be deemed invalid as if the client attempted to forge or tamper with it, though the specific warning generated would only reference the fact that an absent key had been used (there is no current provision for noting that a specific key had been formally revoked to produce a different log message). What degree of cryptographic agility exists in the particular use case? Because the consumption of the data is purely internal to the implementation, it is possible to update the software unilaterally to alter or extend the set of supported algorithms. Changes to the encryption format would likely be required to account for the possibility of alternate algorithms and/or specifying them in the configuration, but this would be possible without coordination with third parties or major disruption to the software development lifecycle. However, changes to the format or algorithm set would create implications during rolling upgrades (if a node on one version was unable to create or consume data for or from another version) and this would have to be documented for specific releases. In practice, tokens/etc. would probably be invalidated in such cases, though this could result in disruptions to varying, though limited, degrees. In principle any authenticated encryption algorithm supported by the JCA could be used without major disruption or difficulty. Using unauthenticated encryption algorithms would require a reimplementation using a layered design to include a MAC, and would introduce additional risk from implementation mistakes. At present, AES-GCM appears to be the only authenticated encryption algorithm required to be implemented by the JCA. What is the impact of a compromise on the software’s purpose or a deployer’s data or infrastructure in functional (rather than assumed risk) terms? Very significant/catastrophic in the case of a compromise to the integrity property. Compromise of the confidentiality property would result in a privacy compromise of subjective severity depending on the data involved and local policies or regulations. A compromise of integrity would result in serious breaches varying by use case, such as: the ability to forge OpenID logins and data about a subject to a particular relying party the ability to force access or refresh tokens allowing access to resources relying on the IdP as an OAuth authorization service the ability to query for data that might not otherwise be intended to be accessible to the caller A key compromise would be easy to recover from (simply changing the key and removing the compromised one suffices) but a break in the AES-GCM algorithm or a vulnerability in the implementation would require a software update to the IdP (and an alternative algorithm or hybrid approach would need to be used, see also the previous answer). Are there assumptions about how a deployer implements or uses the feature(s) that impact the answers above? Some of the discussion is based on the default implementation of the key “strategy” supplied with the software that handles accessing keys. In principle, an alternative implementation built by a third party could impact some of the answers.
Most of the direct authentication methods supported by the IdP are “black boxed”, relying on existing authentication implementations that we invoke rather than implementing them directly. The more “indirect” mechanisms supported do not rely directly on cryptographic primitives other than foundational ones such as TLS. GSS-API, WebAuthn, and OATH are noted in the Caveats section with respect to cryptographic implications. One exception is the support for directly validating passwords against a local file, usually containing salted and hashed passwords. How does the use-case relate to the software’s intended purpose? The IdP authenticates subjects as a core process in the course of implementing the web authentication protocols that it supports. The support for direct verification of hashed passwords supplied by a client is largely a mechanism for “quick” deployment of an IdP for testing or demonstrations and is not used heavily in practice, but it is a fully supported option. Does the use case involve two or more independent software implementers being able to produce and consume ciphertext for the other or is it self-contained and lacking a requirement for interoperability? It is essentially self-contained given a compliant password file, but in order that the supported password files may be managed via Apache’s htpasswd utility, it is designed to consume that particular file format and to support a number of salted hash mechanisms supported by that utility, so it must interoperate for that to work. Are there standards defining/constraining which algorithms are usable for the use case? No. 1 Is the output ephemeral or durable and for what expected lifetime? The feature relies on files that are expected to be stored for arbitrary lengths of time, but does not produce output itself. Does the ciphertext provide sufficient information about the algorithm(s) used to allow for it to be consumed arbitrarily later? The Apache format relies on a number of prefixes signifying the digest mechanism used to transform passwords for storage and comparison. What are the algorithms supported for this use case in current versions of the platform? Salted MD-5 and unsalted SHA-1 are directly supported, and a crypt(3) compatible option is supported that internally recognizes SHA-512, SHA-256, MD-5, and DES. Some of these are known to be insecure and are not suggested for use, but are supported by the underlying formats and libraries. Does a process exist for rotating/changing the key(s) involved in the use case? If this is a standardized process, please reference it, and if not, please describe it. If there is an existing recommended policy regarding rotation frequency, please note that. There are no keys involved. Changing passwords involves updating the underlying file, which is possible to update in real time. Does a process exist for revoking/expiring the key(s) involved in the use case? If this is a standardized process, please reference it, and if not, please describe it. There are no keys involved. Revoking a password would require removing it from the underlying file. What degree of cryptographic agility exists in the particular use case? Within the range of supported algorithms, passwords can be re-hashed by updating the underlying file, but addition or removal of digest options would require code updates (and possibly the implementation of a new tool to produce compatible files if the htpasswd utility does not include them). What is the impact of a compromise on the software’s purpose or a deployer’s data or infrastructure in functional (rather than assumed risk) terms? An external compromise is unlikely because the non-digested input must be supplied in the course of using this feature, but the file must be readable and is loaded into memory, so various attacks that compromise the integrity of the JVM could lead to compromise of the hashed passwords. Compromised hashes are vulnerable if weak or unsalted formats are used, but would otherwise require brute force attack to crack salted hashes (allowing of course that many passwords are weak and easily guessed). A compromise of the actual validation step is not practically likely, but would leave an IdP using the feature vulnerable to impersonation attacks by malicious clients. Are there assumptions about how a deployer implements or uses the feature(s) that impact the answers above? It is assumed that this feature is not likely to be used in production at scale, but if used, the password file must of course be well protected.
TBD, but essentially a discussion of the fact that we implemented our own PGP-based verification enforcer for Maven and have done relative duo diligence on all the keys we accept for the Java builds.
We endeavor to provide a meaningful and reliable process by which our community may verify our software. This process is designed to offer confidence that our software as delivered represents a build that has satisfied our inward-facing supply chain protections (see above). This extends to the installation of plugins. We provide that confidence in the form of a PGP-compatible signature over all our hosted artifacts and installation bundles, signed with a key that will be found in an enumerated bundle on our download site at https://shibboleth.net/downloads/PGP_KEYS. Updates to that file cannot be made without physical access to our server or to a locally held Git repository. Both server and Git repository are limited to access via SSH keys we also maintain in a similar way. That is, it is not possible for a compromise to a third-party service (such as Codeberg) to compromise that file. Our actual IdP installation process does not download or verify any artifacts itself (this is assumed to have been done by the deployer) but our plugin installer does default to requiring a signature from a known key, and if the signing key is not recognized as trusted via a locally maintained or specified list of trusted keys, a manual approval of the key must occur, after which it is stored and trusted. This extends to the command line tool that will download updated IdP installation packages (but it will not install them) and it extends to the download of versions of Jetty by our Jetty plugin. Note that apart from these PGP signatures, we may at our discretion produce additional checksums (primarily because this is a Maven expectation) but we do not consider them to be a relevant mechanism for trusting our artifacts, nor do we support inferences of trust on the basis of any third-party-signed certificates deployed with our web site(s), as we do not consider any commercial CAs or their issuance processes to be worthy of any substantial degree of organizational trust. It follows that we consider the use of our Java artifacts via Maven in its typical/default modes of operation to be fundamentally insecure. (See also the previous section regarding our inward-facing processes.) How does the use-case relate to the software’s intended purpose? Our software operates in a highly trusted fashion (most of the time) and must therefore be treated as requiring an elevated degree of trust during installation, extension, and update. We seek to facilitate this in a cost-effective and trustworthy way. Does the use case involve two or more independent software implementers being able to produce and consume ciphertext for the other or is it self-contained and lacking a requirement for interoperability? The protections we apply to the installation of plugins and downloading new versions of the IdP or Jetty are in principle self-contained and could be viewed as an opaque mechanism, but in practice the trustworthiness of those processes is enhanced through the use of a standard/open mechanism. And in turn, the initial verification of our software, and the ability to implement a more trustworthy process of incorporating our Java artifacts into other software requires an interoperable approach. So in practice, this is a use case that requites interoperation with independent implementations (of PGP in this case). Are there standards defining/constraining which algorithms are usable for the use case? Yes, RFC9580 and related RFCs define the relevant formats and processes. Is the output ephemeral or durable and for what expected lifetime? The signed artifacts are expected to have an indefinite lifetime; in practice our willingness to re-sign artifacts if necessary for cryptographic reasons would be limited to artifacts from actively supported versions and we would likely move or in some way delineate any older artifacts if given a reason. Does the ciphertext provide sufficient information about the algorithm(s) used to allow for it to be consumed arbitrarily later? Yes, the particular algorithms used are part of the data format. What are the algorithms supported for this use case in current versions of the platform? TBD - certainly primarily SHA-256/etc. and RSA Does a process exist for rotating/changing the key(s) involved in the use case? If this is a standardized process, please reference it, and if not, please describe it. If there is an existing recommended policy regarding rotation frequency, please note that. The signing keys used by the project and its committers are in general controlled by the individuals (with one exception noted below) and we do not impose pre-determined lifetimes or expectations around rotation of those keys. Artifacts are signed by the key that is “current” for a given committer at the time they are produced, and new keys can be added easily as long as they are advertised in the designated file. Introducing new keys, however, imposes a cost on the community to discover and accept a new key and so is not done lightly or on a particular schedule. An exception is the key used to sign snapshots, which was generated online and is stored on a server that is accessible to the project team, and does not represent any individual’s assurance of the state of the artifacts. That key is primarily a convenience for our own build processes to be tested and to facilitate the installation of unreleased software. That key is likely to be subject to more frequent change. Notably, it is not advertised in the main PGP_KEY file, but in a separate file alongside it. Does a process exist for revoking/expiring the key(s) involved in the use case? If this is a standardized process, please reference it, and if not, please describe it. We do not have a formal process at this time but in the event of a compromise, we would remove the key from the hosted PGP_KEYS file, announce the issue, and endeavor to identify any supported artifacts signed with that key, rebuild them, and re-sign them under a different key. That process is likely to take some time, and the specific steps taken would depend on the facts known related to the compromise. What degree of cryptographic agility exists in the particular use case? Agility would depend largely on the degree of adoption of alternative signing and digest algorithms by Bouncy Castle (the PGP implementation we use in Java) and by any other PGP implementations expected to be of relevance. The OpenPGP software is likely the primary “additional” implementation of direct concern. Given an available algorithm to use, the cost of migration for new artifacts is likely minimal but for older artifacts would be subject to similar constraints as in the case of a compromise (i.e., it would depend on the scope of the risk). Our agility is enhanced with respect to our consumption of our own artifacts (i.e., plugin installation) as we are able to rely on a single implementation. What is the impact of a compromise on the software’s purpose or a deployer’s data or infrastructure in functional (rather than assumed risk) terms? Potentially catastrophic given the possibility of a malicious artifact masquerading as legitimate and potentially being installed on many trusted systems operating at a high degree of exposure. However, it should be noted that it is unknown to what degree existing deployers properly verify our artifacts, and it is even more questionable to what extent any third parties consuming artifacts via Maven do so since Maven does not provide an effective means to do so by default. One cannot compromise what is already broken. Are there assumptions about how a deployer implements or uses the feature(s) that impact the answers above? We assume that installation of the IdP itself occur only via installation packages that have undergone a signature verification against a trusted key and that our plugin installers, etc. are not subverted (implying also that the initial leap of faith to trust a key is done only after verifying the candidate key independently). In turn of course, the PGP implementation used to initially verify the IdP installer itself would have to be worthy of trust. As well documented, there is a practical limit to how many layers one can traverse here.

Footnotes

  1. Qualified by the fact that some specifications (such as FIPS in the US) will dictate specific requirements for the implementation of all cryptography in a piece of software.