From 392d6480f5a06931223305e1263cf71275d70a13 Mon Sep 17 00:00:00 2001 From: Sitaram Chamarty Date: Wed, 27 Mar 2024 18:08:59 +0530 Subject: [PATCH] assorted doc fixes: - how to compensate for patterns other than UNSAFE_PATT - rearranged some of the ssh cert stuff - warning about scripting if using http mode --- docs/git-config.mkd | 2 +- docs/gitolite-and-ssh-certs.mkd | 52 ++++++++++++++++++++++++++++++----------- docs/http.mkd | 5 ++++ docs/rc.mkd | 29 +++++++++++++++++++++++ docs/triggers.mkd | 40 +++++++++++++++++++++++++++++++ docs/wild.mkd | 5 ++++ 6 files changed, 118 insertions(+), 15 deletions(-) diff --git a/docs/git-config.mkd b/docs/git-config.mkd index 98cbc61..2a4705e 100644 --- a/docs/git-config.mkd +++ b/docs/git-config.mkd @@ -102,7 +102,7 @@ As you can see, the general idea is to place the most generic ones (`repo @all`, or repo regex like `repo foo.*`) first, and place more specific ones later to override the generic settings. -# compensating for UNSAFE\_PATT +# compensating for UNSAFE\_PATT (and other patterns) An important feature in gitolite is that you can share the admin load with more people, **without** having to give all of them shell access on the diff --git a/docs/gitolite-and-ssh-certs.mkd b/docs/gitolite-and-ssh-certs.mkd index 6304e46..e778a61 100644 --- a/docs/gitolite-and-ssh-certs.mkd +++ b/docs/gitolite-and-ssh-certs.mkd @@ -1,14 +1,7 @@ # gitolite and ssh certificates -(Background: there have been a few emails over the years about this on the -mailing list, and I tried to understand how ssh certs work and so on back -then, culminating in [this -email](https://groups.google.com/g/gitolite/c/XouuE3s3DMs/m/6_HbGJKzAgAJ). -That was still too open-ended, because there's more than one way to do it and -none of them is canonical in any sense. And even though there were other -emails from folks who tried it themselves, none of those seemed to hit all the -important points either. So I finally found some time to work on this; hope -it helps.) +Please see the Appendix at the bottom for background and earlier discussions +of this topic on the mailing list. ## objectives @@ -41,11 +34,10 @@ username. Any other method seems to violate one of our objectives. !!! note "Specifically..." - ...notice that if you already use ssh certs, you only have to: - (1) add the "Match User git" section to sshd config - (3) add the two supporting files (see last bullet in the "detailed steps" section), and - (3) ask the CA to add two principals to the certificates they issue, if - the user is a gitolite user (see below) + ...notice that if you already use ssh certs, you only have to: + (1) add the "Match User git" section to sshd config + (2) add the two supporting files (see last bullet in the "detailed steps" section), and + (3) ask the CA to add two principals to the certificates they issue, if the user is a gitolite user (see below) ## host certs and user certs @@ -187,3 +179,35 @@ This takes a "default" ssh setup and does just enough to get this working. called "porcelain" is not a good idea, I'm in good company. does exactly the same thing :) + +## Appendix -- background and discussion + +There have been a few emails over the years about this on the mailing list, +and I tried to understand how ssh certs work and so on back then, culminating +in [this email](https://groups.google.com/g/gitolite/c/XouuE3s3DMs/m/6_HbGJKzAgAJ). +That was still too open-ended, because there's more than one way to do it and +none of them is canonical in any sense. And even though there were other +emails from folks who tried it themselves, none of those seemed to hit all the +important points either. + +One of the mechanisms discussed in that earlier email was "without root +access". Sadly, the only way to do this is to dedicate the entire ssh-cert +mechanism for the exclusive use of gitolite. This is not very useful, since +at least some of the reasons that make ssh certs better than ssh pubkeys, do +not apply to gitolite (the admin repo is a single source of auditable truth +for who can access what, and removing a user is trivially achieved by deleting +his key from `keydir/`). Thus, if you're using certs only for gitolite I'm +not even sure it is worth doing. + +This means the best mechanism will integrate cleanly with any existing use of +ssh certs in the organisation, which is what this method focuses on. + +We're also not considering revocation. Any org using ssh certs should think +about this from a larger perspective, not just gitolite, along with the +decision on how the pubkeys are actually going to be signed. The popular +strategy seems to be to use a web-based system tied into some corporate +"userid" to authenticate the user and issue him a cert, either with a +previously stored pubkey or a freshly pasted/uploaded one, and make the cert +very short-lived (typically 5-15 minutes, though sometimes I have heard of +certs valid for 8-9 hours). + diff --git a/docs/http.mkd b/docs/http.mkd index e667e84..b92f9fd 100644 --- a/docs/http.mkd +++ b/docs/http.mkd @@ -74,6 +74,11 @@ and is available [here](contrib/ssh-and-http). # usage +!!! danger "Warning:" + Http mode does not seem capable of setting an exit code when things fail, + unlike ssh mode. Therefore, using an http-hosted gitolite in scripts may + need more care and thought. + ## client side Git URLs look like `https://user:password@server/git/reponame.git`. diff --git a/docs/rc.mkd b/docs/rc.mkd index f5ae4f3..622e145 100644 --- a/docs/rc.mkd +++ b/docs/rc.mkd @@ -226,3 +226,32 @@ order it has them. - document 'before' option (default: goes to the end) - document arguments supplied via ENABLE list --> + +# appendix C: overriding safety-net patterns + +Apart from [`UNSAFE_PATT`][unsafepatt], there are other patterns that +gitolite uses to prevent various attacks. They're all defined in `Rc.pm` in +the source, but you can override any of them in `~/.gitolite.rc` if needed. + +[unsafepatt]: git-config.html#compensating-for-unsafe_patt-and-other-patterns + +!!! danger "DANGER!" + + Overriding any of these regexes may impact the security of the + installation severly if you are not careful. You have been warned! + +The patterns are: + + $REMOTE_COMMAND_PATT = qr(^[-0-9a-zA-Z._\@/+ :,\%=]*$); + $REF_OR_FILENAME_PATT = qr(^[0-9a-zA-Z][-0-9a-zA-Z._\@/+ :,]*$); + $REPONAME_PATT = qr(^\@?[0-9a-zA-Z][-0-9a-zA-Z._\@/+]*$); + $REPOPATT_PATT = qr(^\@?[[0-9a-zA-Z][-0-9a-zA-Z._\@/+\\^$|()[\]*?{},]*$); + $USERNAME_PATT = qr(^\@?[0-9a-zA-Z][-0-9a-zA-Z._\@+]*$); + +To override any of them, just add a new definition for the pattern at the +**very end** of your rc file, just before the `1;` line. E.g., to allow +usernames to have a leading underscore, you might add: + + $USERNAME_PATT = qr(^\@?[_0-9a-zA-Z][-0-9a-zA-Z._\@+]*$); + +Needless to say you should be very comfortable with regexes to attempt this :) diff --git a/docs/triggers.mkd b/docs/triggers.mkd index 4a564aa..290df6d 100644 --- a/docs/triggers.mkd +++ b/docs/triggers.mkd @@ -213,6 +213,46 @@ actually looks like. For example: gitolite query-rc POST_CREATE + + + # tips and examples 1. If you have code that latches onto more than one trigger, collecting data diff --git a/docs/wild.mkd b/docs/wild.mkd index da71d24..bd0b87d 100644 --- a/docs/wild.mkd +++ b/docs/wild.mkd @@ -260,3 +260,8 @@ But, as I said in [this mail](https://groups.google.com/d/msg/gitolite/nFbnQuO0z to actually understand how this larger group become the "owner". ``` + -- 2.11.4.GIT