Skip to content

Verified Group Names

Toby Crawley edited this page Aug 10, 2023 · 16 revisions

In light of the recent announcement of a method to inject libraries into internal builds by shadowing internal names (aka 'Dependency Confusion'), we have decided to take steps to make Clojars more secure. Clojars now requires that all new libraries have a verified group name, and that group name needs to be reverse-domain-based. The final phase of these scheduled changes came into effect on 2021-04-18.

The changes are designed to protect against Clojars being used in the following attack vectors:

  • shadowing a company-internal library name, causing the version published on Clojars to be used instead in some situations
  • shadowing a library name that is also published to Maven Central or another public repository (Clojars already has checks in place to prevent shadowing anything on Maven Central, but they are brittle and could be removed once verification is in place)
  • "typo-squatting" - a library that is named very similarly to one published elsewhere; designed to capture cases where a developer makes a typo in the dependency specification

FAQ

What is a reverse-domain-based group name?

A reverse-domain-based group name is one that when reversed resolves to a DNS-resolvable domain, or a domain and a well known identifier within that domain. For example, com.github.clojars maps to https://github.com/clojars/, and org.clojars maps to https://clojars.org. This namespacing mechanism has a long history in Java for package names and libraries released to Maven Central. Clojars has historically been less stringent, and using verifiable group names brings us closer to the standards followed by much of the broader JVM community.

Do I have to have my own domain name to publish to Clojars?

No, you have quite a few automatically verified options if you don't have a domain name, don't want to use your own, or don't want to go through the manual verification process:

  • org.clojars.<clojars-username>: this group exists for each Clojars user, and is automatically verified. These groups have existed since the early days of Clojars, and have typically been used as sandboxes/for non-canonical forks. We recommend using net.clojars. for "official" releases instead.
  • net.clojars.<clojars-username>: this group exists for each Clojars user, and is automatically verified
  • com.github.<github-username> / io.github.<github-username>: both of these groups will be verified automatically when you login via GitHub after 2021-03-07. See below if you want to verify (com|io).github.<github-organization-name>.
  • com.gitlab.<gitlab-username> / io.gitlab.<gitlab-username>: both of these groups will be verified automatically when you login via GitLab after 2021-03-21. See below if you want to verify (com|io).gitlab.<gitlab-organization-name>.

How do I verify a group name?

If the group name matches a github/gitlab organisation name (com.github.<org>/com.gitlab.<org>/io.github.<org>/io.gitlab.<org>) you will need to prove your clojars user has sufficient priveleges in your githost's organisation. To do this need to create an empty public repository in your github/gitlab organisation with the following name pattern clojars-<your-clojars-username> and use the self-service verification page on Clojars to verify the group based on this information. Please file a support request on our clojars-administration repo if you have any issues with this process.

If the group name is some other reverse-domain-based name, please create a TXT DNS record under that domain containing clojars <your clojars username> to prove ownership, then use the self-service verification page on Clojars to verify the group based on this information. Please file a support request on our clojars-administration repo if you have any issues with this process.

If the group name isn't reverse-domain-based, it won't be verified.

If this is a new group (no libraries have yet been released to it), you will need to verify it before deploying the library after 2021-04-18.

Can I verify a sub-domain-based group of an already verified group?

Yes. If you want to use a group that is based on a sub-domain, you just need to verify the base domain. You can then just use the self-service verification page on Clojars to verify the group. Please file a support request on our clojars-administration repo if you have any issues with this process. The sub-domain doesn't have to actually exist in DNS. The new group will initially have one member, and that will be the account that verified the base domain.

For example, if you have already verified org.tcrawley, you can request org.tcrawley.awesome-sauce, and it will be verified without any additional proof. As another example, if you already verified com.github.tobias, you can use the same process above to verify com.github.tobias.awesome-sauce.

How does this impact existing libraries published to Clojars?

This won't have an impact on releasing new versions of existing libraries; the group does not need to be verified for new versions. These changes only impact new libraries.

Do I have to rename my existing libraries that I publish to Clojars?

No; existing libraries can continue to release new versions under their existing names and be referred to by their existing names.

In fact. we recommend that you do not release new versions of existing libraries under a new group name, since that can lead to two versions of your library on a project's classpath if one (or both) of them are brought in transitively. This happens because the dependency resolution logic uses the group + artifact name to find and remove duplicate dependencies, and has no way to detect that foo/bar and com.foo/bar are really the same library. See this discussion for a deeper explanation.

Does this impact how Clojure namespaces have to be named within libraries?

Not at all - there is no relationship between the name of a library and the namespaces it provides (but zero correspondence between them might be confusing).

Can I verify an existing group name?

Yes, as long as the group name is reverse-domain-based and you are a member of the group. Otherwise, no.

What does this mean for single-named libraries?

Libraries with a "single name" (like hiccup, cheshire, clj-http, etc) are implemented under the hood as a library where the group and artifact name are the same (hiccup/hiccup, cheshire/cheshire, etc). Existing libraries named in that fashion will continue to be releasable, but no new ones will be allowed to be created (that's not 100% accurate - you could verify a domain-based-group, then use the group name as the artifact name as well, but that seems unlikely).

I never publish libraries to Clojars, only use them. How does this impact me?

This should have no impact on you other than the improved security.

How can I help?

Great question! You can help by:

  • bringing any community documentation that needs to be updated to our attention, or updating it yourself
  • sharing this information throughout the community

When were the verified group name changes implemented?

The schedule for releasing this change was designed to allow enough time for us to get the Clojars changes in place and to communicate the changes throughout the community:

  • 2021-02-28:
    • net.clojars.<clojars-username>/org.clojars.<clojars-username> groups are already verified for all existing and future users (see below for details)
    • the Clojars admins can start processing any manual verification requests (see below for details)
    • creating new non-verified groups and creating new libraries in non-verified groups is still allowed
  • 2021-03-07:
    • com.github.<github-username> and io.github.<github-username> groups will be verified automatically when when you log in via GitHub
  • 2021-03-21:
    • login via GitLab will be released
    • com.gitlab.<gitlab-username> and io.gitlab.<gitlab-username> groups verified automatically when you login via GitLab
  • 2021-04-18:
    • creating new non-verified groups and creating new libraries in non-verified groups will be disabled
  • 2023-01-09:

The plan to implement these changes was tracked in this project.

Discussion/feedback

If you have questions or concerns that aren't answered here, feel free to comment on this discussion.