diff options
Diffstat (limited to 'rt/docs/design_docs')
22 files changed, 0 insertions, 2950 deletions
diff --git a/rt/docs/design_docs/3.3-schema-redesign.txt b/rt/docs/design_docs/3.3-schema-redesign.txt deleted file mode 100644 index 518eccd4d..000000000 --- a/rt/docs/design_docs/3.3-schema-redesign.txt +++ /dev/null @@ -1,57 +0,0 @@ --- --------------------------------------- -- --- RT 3.3 Schema redesign v7: 2004-11-08 -- --- --------------------------------------- -- - -TABLE CustomFields ( - id INTEGER NOT NULL AUTO_INCREMENT, - Name varchar(200) NULL , - Type varchar(200) NULL , -- Changed: see MaxValues below - MaxValues integer, -- New: 1 = Single, 0 = Multiple - Pattern varchar(255) NULL , -- New: regex to validate against - Repeated int2 NOT NULL DEFAULT 0 , -- New: repeated table entry - LookupType varchar(255) NOT NULL, -- New: "RT::Queue-RT::Ticket" - Description varchar(255) NULL , - SortOrder integer NOT NULL DEFAULT 0 , -- only used on "pick CF" screen -) - --- This table replaces the "Queue" field in CustomFields -TABLE ObjectCustomFields ( - id INTEGER NOT NULL AUTO_INCREMENT, - CustomField int NOT NULL , -- CustomField ID - ObjectId integer NOT NULL, -- Final id of toplevel parent, or - -- the object itself if ParentType - -- is empty; 0 means global as usual - SortOrder integer NOT NULL DEFAULT 0 , -- this is used to sort the CFs -); - --- This table replaces TicketCustomFieldValues -TABLE ObjectCustomFieldValues ( - id INTEGER NOT NULL AUTO_INCREMENT, - CustomField int NOT NULL , - ObjectType varchar(255) NOT NULL, -- Final target of the Object - ObjectId int NOT NULL , -- New: replaces the "Ticket" field - SortOrder integer NOT NULL DEFAULT 0 , -- New: for Repeated fields - - Content varchar(255) NULL , - LargeContent LONGTEXT NULL, -- New: data longer than 255 bytes - ContentType varchar(80) NULL, -- New: MIME type of LargeContent - ContentEncoding varchar(80) NULL , -- New: for binary LargeContent - Disabled int2 NOT NULL DEFAULT 0 , -- New: whether this is deleted -) - -TABLE Transactions ( - id INTEGER NOT NULL AUTO_INCREMENT, - ObjectType varchar(255) NULL, -- Final target of the Object - ObjectId integer NOT NULL DEFAULT 0 , -- New: replaces the "Ticket" field - TimeTaken integer NOT NULL DEFAULT 0 , - Type varchar(20) NULL , - Field varchar(40) NULL , - OldValue varchar(255) NULL , - NewValue varchar(255) NULL , - ReferenceType varchar(255) NULL, -- NeW: Currently "RT::OCFV" only - OldReference integer NULL , -- New: Id of ReferenceType - NewReference integer NULL , -- New: Id of ReferenceType - Data varchar(255) NULL , -) - --- vim: filetype=mysql shiftwidth=4 expandtab diff --git a/rt/docs/design_docs/CARS b/rt/docs/design_docs/CARS deleted file mode 100755 index a4d2a78c5..000000000 --- a/rt/docs/design_docs/CARS +++ /dev/null @@ -1,66 +0,0 @@ -Conditional Automated Request Shuffler -Initial Design. <jesse@fsck.com> 9 Nov 99 - -#Try to find out what queue the incoming ticket is in -#Try to find out the default action for this invocation -#Read the ticket from STDIN -#Obtain the actor -#Obtain the serial # if we have one -#If the ticket has a ticket-id - #if this is a 'comment' - #add the current mime objects as a 'comment' - - #if this is 'correspondence' - #add the current mime object as 'correspondence' - - -#if this ticket does not yet have a ticket id - - #For now: - #Create a new ticket - - #In the distant future - - #load the regexp table matching this queue - #check the message agains the regexp table, ordered by precedence - #when we get a match - #get the ruleset for that regexp from the actions table - #evaluate the ruleset in order of precedence. - #if we get an 'exit' stop proccesing ALL rulesets -wpw #if we get a 'forward,' forward it to 'value'. - - #if we get a 'create,' create a request in 'value' - #elseif we get a 'map', add this as additional correspondence on ticket 'value' - - - #if we get an 'associate', associate the ticket number returned from the - 'create' or 'map' with the master ticket from 'value' - - #if we get a 'reply', - #load the reply template with id 'value' - #replace strings in the template - #send the template - - - - -CREATE TABLE Rules { -ID int AUTO_INCREMENT, -Desc varchar(120), -Regexp varchar(80), -Precedence int, -MatchField varchar(20), #Can be a headername or 'any' all header names - #end in : - - -CREATE TABLE Actions { -Rule int, -Action varchar(20), # Create, Forward, Squelch, Owner, Area, Associate -Value varchar(20), #queue or email address -Desc varchar(120) -} - -CREATE TABLE Autoreplies { -ID int AUTO_INCREMENT, -Content text -);
\ No newline at end of file diff --git a/rt/docs/design_docs/TransactionTypes.txt b/rt/docs/design_docs/TransactionTypes.txt deleted file mode 100755 index 6edc408de..000000000 --- a/rt/docs/design_docs/TransactionTypes.txt +++ /dev/null @@ -1,48 +0,0 @@ -This is some loose scrabbling made by TobiX, they might eventually be relevant -for 2.1. - -INTERFACES, in general - -should: - -- provide the user (client?) with a list of possible actions (methods). -- let the user execute those actions (methods). -- Return information to the user/client. - -There are two kind of actions/methods: - -- Information retrieval -- Transactions - -For the first, I think the best thing is to just provide a lot of -methods for it in the libraries, and let it be an Interface Design -Issue what to show and how to show it. - -For the second, I think we can win in the long run on having a -generalized methods for - -- listing transaction types. -- creating & committing transactions. - -..with the possibility of just deploying new custom-developed modules -when new transaction types are needed. - - -RT->Config->Get('TransactionTypes') ...and... -RT->Config->Get('TransactionTypes') - - global object which contains all TransactionTypes - - used by all UIs to create menues of possible (user) actions (one TransactionType is a user action) - -The UIs should call sth like -$Ticket->AddTransaction($TransactionName), which should be equivalent -with i.e. $Ticket->Correspond when $TransactionName is 'Correspond' -(AUTOLOAD should call the do-sub if exists -RT->Config->Get('TransactionTypes')->{$TransactionName}) - -The RT::Ticket::AddTransaction will create a new transaction of the -right TransactionClass (maybe via a sub -RT::TransactionTypes::NewTransaction). Then $Transaction->do is -called. - -TransactionType->do initializes a new object of the right TransactionClass, and - diff --git a/rt/docs/design_docs/acls b/rt/docs/design_docs/acls deleted file mode 100644 index bb093adcb..000000000 --- a/rt/docs/design_docs/acls +++ /dev/null @@ -1,50 +0,0 @@ - - -Does principal baz have right foo for object bar - -What rights does user baz have for object bar - -# {{{ Which principals have right foo for object bar - - -if ($args{'ObjectType'} eq 'Ticket') { - $or_check_ticket_roles = " OR ( Groups.Domain = 'TicketRole' AND Groups.Instance = '".$args{'ObjectId'}."') "; - # If we're looking at ticket rights, we also want to look at the associated queue rights. - # this is a little bit hacky, but basically, now that we've done the ticket roles magic, we load the queue object - # and ask all the rest of our questions about the queue. - my $tick = RT::Ticket->new($RT::SystemUser); - $tick->Load($args{'ObjectId'}); - $args{'ObjectType'} = 'Queue'; - $args{'ObjectId'} = $tick->QueueObj->Id(); - -} -if ($args{'ObjectType'} eq 'Queue') { - $or_check_roles = " OR ( ( (Groups.Domain = 'QueueRole' AND Groups.Instance = '".$args{'ObjectId'}."') $or_check_ticket_roles ) - AND Groups.Type = ACL.PrincipalType AND Groups.Id = Principals.ObjectId AND Principals.PrincipalType = 'Group') "; -} - -if (defined $args{'ObjectType'} ) { - $or_look_at_object_rights = " OR (ACL.ObjectType = '".$args{'ObjectType'}."' AND ACL.ObjectId = '".$args{'ObjectId'}."') "; - -} - -my $query = "SELECT Users.* from ACL, Groups, Users, Principals, Principals UserPrinc, CachedGroupMembers WHERE - Users.id = UserPrinc.ObjectId AND UserPrinc.PrincipalType = 'User' AND - Principals.Id = CachedGroupMembers.GroupId AND - CachedGroupMembers.MemberId = UserPrinc.ObjectId AND - UserPrinc.PrincipalType = 'User' AND - (ACL.RightName = 'SuperUser' OR ACL.RightName = '$right') AND - (ACL.ObjectType = 'System' $or_look_at_object_rights) AND - ( - (ACL.PrincipalId = Principals.Id AND - Principals.ObjectId = Groups.Id AND - ACL.PrincipalType = 'Group' AND - (Groups.Domain = 'SystemInternal' OR Groups.Domain = 'UserDefined' OR Groups.Domain = 'ACLEquivalence') - ) - $or_check_roles - )"; - -# }}} - -What objects does principal baz have right foo for -; diff --git a/rt/docs/design_docs/approval_notices b/rt/docs/design_docs/approval_notices deleted file mode 100644 index 5e7611924..000000000 --- a/rt/docs/design_docs/approval_notices +++ /dev/null @@ -1,8 +0,0 @@ -Notification on "your request approved by" -Notification on "your request approved by all approvers" -Notification on "your request denied by" -Reject ticket on rejection of any approval - -"Ticket N is pending your approval" - - diff --git a/rt/docs/design_docs/approval_template b/rt/docs/design_docs/approval_template deleted file mode 100644 index 3b9386806..000000000 --- a/rt/docs/design_docs/approval_template +++ /dev/null @@ -1,25 +0,0 @@ -===Create-Ticket: approval - { my $name = "HR"; - my $groups = RT::Groups->new($RT::SystemUser); - $groups->LimitToUserDefinedGroups(); - $groups->Limit(FIELD => 'Name', OPERATOR => '=', VALUE => "$name"); - $groups->WithMember($TransactionObj->CreatorObj->Id); - - my $groupid = $groups->First->Id; - - my $adminccs = RT::Users->new($RT::SystemUser); - $adminccs->WhoHaveRight(Right => 'AdminGroup', IncludeSystemRights => undef, IncludeSuperusers => 0, IncludeSubgroupMembers => 0, Object => $groups->First); - - my @admins; - while (my $admin = $adminccs->Next) { - push (@admins, $admin->Name); - } - } - Queue: ___Approvals - Type: approval - AdminCcs: {join (", ",@admins) } - Depended-On-By: TOP - Refers-To: TOP - Due: {time + 86400} - Content-Type: text/plain - Content: Your approval is requested for the ticket {$Tickets{'TOP'}->Id}: {$Tickets{'TOP'}->Subject} diff --git a/rt/docs/design_docs/cf_search b/rt/docs/design_docs/cf_search deleted file mode 100644 index 456a9febb..000000000 --- a/rt/docs/design_docs/cf_search +++ /dev/null @@ -1,72 +0,0 @@ -find all tickets where: - - - CF Foo - Has values (talk or read) AND - Has values (bar and baz) AND - doesn't have values (bing or bong) - - -LimitCustomFieldValues { - my %args = ( CustomField => undef, - ClauseId => 'CustomFields', - OPERATOR => undef, - ENTRYAGGREGATOR => undef, - VALUES => undef, - @_) ; - - unless ( $self->{'TicketAliases'}{$args{'ClauseId'}}{'CustomField'} ) { - $self->{'TicketAliases'}{$args{'ClauseId'}}{'CustomField'} = $self->NewAlias('CustomFields'); - $self->Join(TABLE1 =>$self->{'TicketAliases'}{$args{'ClauseId'}}{'CustomField' }, - FIELD1 => 'QueueId', - TABLE2 => 'main', FIELD2 => 'QueueId'); - - if ($args{'OPERATOR'} =~ /!=|IS/i) { - } - else { - } - -} - # {{{ if it's a keyword - elsif ( $TYPES{ $restriction->{'FIELD'} } eq 'CUSTOMFIELD' ) { - - my $null_columns_ok; - my $TicketCFs = $self->Join( TYPE => 'left', - ALIAS1 => 'main', - FIELD1 => 'id', - TABLE2 => 'TicketCustomFieldValues', - FIELD2 => 'Ticket' ); - - foreach my $value ( @{ $restriction->{'VALUES'} } ) { - $self->SUPER::Limit( ALIAS => $TicketCFs, - FIELD => 'Content', - OPERATOR => $restriction->{'OPERATOR'}, - VALUE => $value, - QUOTEVALUE => $restriction->{'QUOTEVALUE'}, - ENTRYAGGREGATOR => 'AND', ); - } - if ( ( $restriction->{'OPERATOR'} =~ /^IS$/i ) or ( $restriction->{'OPERATOR'} eq '!=' ) ) { - $null_columns_ok = 1; - } - - #If we're trying to find tickets where the keyword isn't somethng, also check ones where it _IS_ null - if ( $restriction->{'OPERATOR'} eq '!=' ) { - $self->SUPER::Limit( ALIAS => $TicketCFs, - FIELD => 'Content', - OPERATOR => 'IS', - VALUE => 'NULL', - QUOTEVALUE => 0, - ENTRYAGGREGATOR => 'OR', ); - } - - $self->SUPER::Limit( LEFTJOIN => $TicketCFs, - FIELD => 'CustomField', - VALUE => $restriction->{'CUSTOMFIELD'}, - ENTRYAGGREGATOR => 'OR' ); - - } - - # }}} - - } - diff --git a/rt/docs/design_docs/cli_spec b/rt/docs/design_docs/cli_spec deleted file mode 100644 index ae5f29f76..000000000 --- a/rt/docs/design_docs/cli_spec +++ /dev/null @@ -1,31 +0,0 @@ - -Things the cli must do - create ticket - comment - reply - update ticket metadata - search for tickets - update a bunch of tickets. - list tickets - login/logout - - -should support multiple rt servers - -create/edit/update should use EDITOR or take from a file or stdin - -should be able to update ticket sttributes from a commandline without invoking an editor or needing to use stdin. - -login/logout should store RT session cookies rather than constantly transmitting the username/password combo. - -rtserver and rt username should come from env variables. but should be able to be overridden by commandline options. - -rt password should be able to be specified on the commandline (say from a script) or, failing that be prompted for within the application (as rt's sbin/initdb script does) ...or maybe able to be read from a stash file on disk. - -must be able to dowaload attachments from cli. - - it might also be cool to be able to generate session-length urls for attavhments so you can use a browser. but that's not necessary. - - -I'm envisioning this as similar to the subversion cli, actually. - diff --git a/rt/docs/design_docs/cvs_integration b/rt/docs/design_docs/cvs_integration deleted file mode 100644 index 45a758fbe..000000000 --- a/rt/docs/design_docs/cvs_integration +++ /dev/null @@ -1,164 +0,0 @@ -jesse@FSCK.COM: ok. anyone here - interested in having RT as a bug tracker integrated with CVS? () - -marc: in principle, sure. () - -jesse@FSCK.COM: want to write up your - ideal of how such a beast would work? () - -alex_c: what sort of integration are you thinking of, Jesse? () - -jesse@FSCK.COM: well, that's what I want - to know, alex. lots of people want their bug trackers tied to their - version control. I want to know what people want it to _do_ ;) () - -alex_c: weird. :) () - -marc: similarly to what the debian bts does. - you put a magic string ("rt-closes#123") and it causes the bug in rt to - be closed (or appended with a different magic string) with the commit - message. also nice would be if rt would then generate links to a - webcvs server. () - -jhawk: Hrmm. cvs front-end that strips 'em out? - Perhaps with RT: lines instead of CVS: lines in the commit - interaction? () - -marc: the magic string goes in the commit - message, that is. no, use one of the magic post-commit scripts. () - - -jesse@FSCK.COM: well, there's also the - pre-commit script to lock out commits wihtout a ticket id () - -jhawk: Personally, I don't want to force special - magic strings to the bug-tracking system, some of which may be - confidential, to appear in the cvs logs. () - -marc: I could see wanting that on a release - branch. () - -jhawk: I also think it would be cool to supply - template stuff for you to edit. () - -jesse@FSCK.COM: I'm not sure cvs can be - made to do that. can it? (generate templates) () - -jhawk: It would be reasonable, in my model, to - turn some kinds of RT: lines into things that fell in the commit - message, but not all kinds. () - -marc: I don't quite see jhawk's objection. () - -ghudson: In my observation, locking out commits - without a ticket ID is usually an impediment to development, and leads - to developers having the one bug which all commits cite. () - -jhawk: If you had a CVS frontend, it could geneate - the template and feed it to 'cvs commit -m' () - -ghudson: CVS can generate templates and verify - that they have been filled in. () - -jhawk: What Greg says sounds cool; greg, what do - you mean? marc: one sec. () - -marc: I think assuming a frontend is a terrible - idea. () - -jesse@FSCK.COM: greg: agreed. but people - seem to want it. the idea would be only for a locked down release - branch. () - -jhawk: marc: So, I might want to close an open - ticket as part of a commit message without that showing up in the - coommit message. Or to insert a splufty long comment into a ticket - while I do the commit but not close or really change the state, and - that comment might want to ramble a lot but not include that ramble in - the commit message. () - -jesse@FSCK.COM: well, then arguably, you - might want to not use the commit message for that update, but instead - just go straight to the bts () - -marc: I think the idea is to force you to - mention the ticket closing in the commit message. () - -jesse@FSCK.COM: but yeah, state changing - and 'update messages' are separate concepts that should both be - supported. () - -jesse@FSCK.COM: part of the idea is to - drag the commit message into the BTS () - -jhawk: Err, I think it quite frequent that I want - to put separate info in both the commit message and the ticket system, - and entering them at the same time seems cool. () - -jesse@FSCK.COM: ok. noted. I'll see if - that's doable, when i get around to this. () - -marc: so I think you want a custom front-end, - but I don't think what you want is what jesse is talking about. () - -jesse@FSCK.COM: the thing that would be - really cool that scare the pants off me is tracking which branches bugs - exist in / are fixed in () - -jesse@FSCK.COM: what jhawk wants should - be doable, now that I understand his reqts. () - -marc: that would require the bts to understand - branches in some fundamental way. () - -jesse@FSCK.COM: yes. see above, about - the pants. () - -sly: uh oh, not more people losing their pants... .. - - -ghudson: RT needs to know the names of branches - and their structure (so that you can tell it "fixed in foo" and it - knows that the bug is still fixed in anything that branches off of foo, - but not necessarily in other new branches), but nothing more than that. - -jhawk: So, note that what I'm describing is how - I'd like the UI to be, from a generic architectural level, and not - really thinking terribly specific. Greg, can you explain the CVS - template thing? () - -jesse@FSCK.COM: and it needs to know - exactly "when" a branch happens. because "fixed in foo" won't fix - something that branched off foo yesterday () - -marc: jesse was talking about integrating rt - with cvs. building a new developent+repository+bts from scratch would - be a problem with larger scope :-) () - -jesse@FSCK.COM: marc: was that in - response to jhawk? () - -ghudson: CVS and templates: "rcsinfo" lets you - specify a template for log messages, and "commitinfo" lets you check - them. () - -ghudson: Er, sorry, my bad. - s/commitinfo/verifymsg/ () - -marc: with cvs, if you have the revision number - of the fix (which you should). you can use the branch version number to - get a date and see when the branch happened relative to the fix. () - -marc: jesse: yes. () - -jesse@FSCK.COM: Ok. would people - consider "integration with CVS" to be subpar or incomplete if it didn't - deal with tracking branches? () - -marc: incomplete relative to an ideal, but not - subpar, as it would still be useful. () - -allbery@CS.CMU.EDU: CVS's branch - support sucks so much that failure to work with it is hardly a bug () - - diff --git a/rt/docs/design_docs/delegation b/rt/docs/design_docs/delegation deleted file mode 100644 index 0e5705907..000000000 --- a/rt/docs/design_docs/delegation +++ /dev/null @@ -1,115 +0,0 @@ -Group ACLs - - the rights: - - - CreatePersonalGroup - CreateGroup - - AdminGroup - * Update group metadata and access control list - AdminGroupMembers - * Add ad delete members of this group - ModifyOwnMembership - * Join and quit this group - - - the primitives: - -In user.pm - -=item HasRight { Right => 'somerightname', ObjectType => 'Group', ObjectId => 'GroupId' - - Returns true if this user has the right 'somerightname' for -the group with id 'Id' - -=cut - - -=item RightsForObject { ObjectType => 'Group', ObjectId =>'GroupId' } - -in users.pm - -=item WhoHaveRight { Right =>'somerightname', ObjectType => 'Group', ObjectId => 'GroupId' } - - - Finds all users who have the right 'somerightname' for the group -in question. - - If a user has "AdminGroupMembers" globally and we ask about - group 23, that user should be found. - -=cut - -Users must be able to delegate individual rights - - * Is it that users can delegate any and all rights but it's - only rights they _have_ which actually grant rights. - -rights must not be redelegated - -users must be able to create groups to which rights can be delegated. - -Only users who have the "delegate rights" right can delegate rights. - - -When a user's right to do something is revoked, the delegation must -be revoked - - * For any delegated ACL check, the delegator's right must be - checked immediately after the delegatee's right. - If a user has had a right delegated by multiple parties, - this may mean that we need to actually loop through and check - a bunch of possible delegations. Or can we craft a "has delegated - right" ACL check. - - - - - - - -ACL 1 Group Q has the right to Frob ObjectI. -ACL 2 User A has the right "DelegateRights" - -Group Q has the member Group S -Group S has the member Group R -Group S has the member Group T -Group R has the member user A -Group T has the member user A - -User A delegates to Group P the right to Frob ObjectI - - New ACL rule: - - ACL 3: Group P has the right to Frob ObjectI - as delegated from ACL1 by User A - - -In the case where ACL1 is revoked: - - find all acls which are delegated from ACL1. - Delete them - -In the case where User A is removed from group R - - Get the list of all groups that A was in by way of group R before the removal - Get the list of all groups that A is in _after_ the removal. - - Find all the ACEs granted to each group that A is no longer in. - For each ACE in that list, find all the rights that A has delegated. - Whack them. - -In the case where Group S is removed from group Q - - - Get a list of all groups that S was in by way of Q before the removal - Call this list O. - - For each user X who's a member of S (directly or indirectly): - Get a list of all groups that X is in after removal. - For each group in O that X is no longer a member of: - Find all ACEs granted to O - For each ACE, look up all the delegations that X has made. - For each delegation - WHACK IT diff --git a/rt/docs/design_docs/evil_plans b/rt/docs/design_docs/evil_plans deleted file mode 100644 index 5b5cc58c1..000000000 --- a/rt/docs/design_docs/evil_plans +++ /dev/null @@ -1,162 +0,0 @@ -Current planned 2.2 feature list. subject to change. - - -Core - - - -Web UI - -Should New "Tools" top level menu -Should "This week in RT" at a glance. -Nice "RT Stats" overview. -Nice recent and favorite items - - -per-user configuration - -Must Saveable user preferences. - - The ideal implementation would be "saveable user metadata", - including things like "Alternate Email Addresses". To - do this right, not all user metadata would be directly - editable by the user who has "ModifySelf" it may be that - this is a "system" datastore that gets accessed by various - functions, some of which the user has access to modify and - some of which only the system does. - - API: Set field "FOO" to value "BAR" for user BAZ - What values does field "FOO" have for user BAZ? - Clear all values of "FOO" for user BAZ - What users have value "BAR" for field "FOO" - - Example usages: - - What users have the alternative email address matching - "boo@fsck.com" - What custom searches does user BAZ have defined? - What is baz's default queue? - - Actually, I feel a little sketchy about Alternative Email - Addresses in there. I'm not quite sure why yet. - - The same would really be useful for queues. Damn it. I think - I want a registry. - - - -Searching - -Must Ability to define search result format. -should Saveable user searches. -nice Sharable searches. - - -Scrips - -must Include more Conditions; at least those contributed so far - that make sense in my grand scheme of things - -should The name should change to something that people don't think is - spelled wrong. ("I will not invent words\n" x 1000) - -nice Scrips could apply to a list of queues, rather than just one queue or - all of them. - - -Custom fields - -Nice Date custom fields -Nice Some way to order and group custom fields. -Nice Default values -Nice Required values -Nice Make custom fields apply to an enumerated list of queues, - rather than just one. - - -Web infrastructure - - -Installation - -Should Better FSSTD conformance: - bins in /bin - admin tools in /sbin (does this include rtadmin?) - ephemeral data in /var - rename config file - force local RT search path? - -Mail gateway - -must Integrate gpg-authenticated command-by-mail mode - - - -Core - -should Use apache logging, if available -should Use syslog, if available. -should Mail user new password, as an Action, so it can be invoked either - as a scripaction or from the web ui. - - - -Web Services Framework - -Should Expose an API to create a ticket by HTTP posting an XML document. -Should Provide an RSS feed to display tickets matching certain criteria -Nice Allow ticket updates via the web ui -Nice Export full ticket metadata and history as XML - -Note: I currently favor the REST philosophy that GET and POST to specific, - defined URLs provides everything one needs to build comprehensive - web services without the massive added complexity of a SOAP or XML-RPC - framework. Sadly, the world doesn't agree with me - - -ACLs: - -Wish New ACL primitives for: - - List all users who have right "FOO" on object "BAR" - List all rights user "BAZ" has for object "BAR" - List all objects for which user "BAR" has right "FOO" - - - - - - - - - - - - - - - - - - -For the near future: - - Use case: - Jesse wants to get notified of all tickets in queue 'RT Bugs' - with a severity of 'critical' and also have a requestor whcih matches 'fsck.com'. - I'm not sure this is the best idea. - - - Site admins define a number of subscriptions and can sign up individual - users, groups or metagroups to get mail on that subscription. - - Basically, an admin would define "On Condition, notify as comment with - template _template_" - - There would be a new table called "subscriptions"(?) that would have - the structure: - - id - ScripId - PrincipalType ENUM: User, Group, Owner, Requestors, AdminCcs, Ccs - PrincipalId -- UserId or GroupId. For Owner, Requestors, AdminCcs, Ccs, it doesn't really make a lick of difference. diff --git a/rt/docs/design_docs/gnupg_details_on_output_formats b/rt/docs/design_docs/gnupg_details_on_output_formats deleted file mode 100644 index e2fc1756f..000000000 --- a/rt/docs/design_docs/gnupg_details_on_output_formats +++ /dev/null @@ -1,1253 +0,0 @@ - -*NOTE* This file is a copy of doc/DETAILS file that comes -with gnupg-1.9.94 distribution. - -Format of colon listings -======================== -First an example: - -$ gpg --fixed-list-mode --with-colons --list-keys \ - --with-fingerprint --with-fingerprint wk@gnupg.org - -pub:f:1024:17:6C7EE1B8621CC013:899817715:1055898235::m:::scESC: -fpr:::::::::ECAF7590EB3443B5C7CF3ACB6C7EE1B8621CC013: -uid:f::::::::Werner Koch <wk@g10code.com>: -uid:f::::::::Werner Koch <wk@gnupg.org>: -sub:f:1536:16:06AD222CADF6A6E1:919537416:1036177416:::::e: -fpr:::::::::CF8BCC4B18DE08FCD8A1615906AD222CADF6A6E1: -sub:r:1536:20:5CE086B5B5A18FF4:899817788:1025961788:::::esc: -fpr:::::::::AB059359A3B81F410FCFF97F5CE086B5B5A18FF4: - -The double --with-fingerprint prints the fingerprint for the subkeys -too, --fixed-list-mode is themodern listing way printing dates in -seconds since Epoch and does not merge the first userID with the pub -record. - - - 1. Field: Type of record - pub = public key - crt = X.509 certificate - crs = X.509 certificate and private key available - sub = subkey (secondary key) - sec = secret key - ssb = secret subkey (secondary key) - uid = user id (only field 10 is used). - uat = user attribute (same as user id except for field 10). - sig = signature - rev = revocation signature - fpr = fingerprint: (fingerprint is in field 10) - pkd = public key data (special field format, see below) - grp = reserved for gpgsm - rvk = revocation key - tru = trust database information - spk = signature subpacket - - 2. Field: A letter describing the calculated trust. This is a single - letter, but be prepared that additional information may follow - in some future versions. (not used for secret keys) - o = Unknown (this key is new to the system) - i = The key is invalid (e.g. due to a missing self-signature) - d = The key has been disabled - (deprecated - use the 'D' in field 12 instead) - r = The key has been revoked - e = The key has expired - - = Unknown trust (i.e. no value assigned) - q = Undefined trust - '-' and 'q' may safely be treated as the same - value for most purposes - n = Don't trust this key at all - m = There is marginal trust in this key - f = The key is fully trusted - u = The key is ultimately trusted. This often means - that the secret key is available, but any key may - be marked as ultimately trusted. - 3. Field: length of key in bits. - 4. Field: Algorithm: 1 = RSA - 16 = Elgamal (encrypt only) - 17 = DSA (sometimes called DH, sign only) - 20 = Elgamal (sign and encrypt - don't use them!) - (for other id's see include/cipher.h) - 5. Field: KeyID - 6. Field: Creation Date (in UTC). For UID and UAT records, this is the - self-signature date. Note that the dae is usally printed - in seconds since epoch, however, we are migrating to an ISO - 8601 format (e.g. "19660205T091500"). This is currently - only relevant for X.509, A simple way to detect the format - is be scannning for the 'T'. - 7. Field: Key or user ID/user attribute expiration date or empty if none. - 8. Field: Used for serial number in crt records (used to be the Local-ID). - For UID and UAT records, this is a hash of the user ID contents - used to represent that exact user ID. For trust signatures, - this is the trust depth seperated by the trust value by a - space. - 9. Field: Ownertrust (primary public keys only) - This is a single letter, but be prepared that additional - information may follow in some future versions. For trust - signatures with a regular expression, this is the regular - expression value, quoted as in field 10. -10. Field: User-ID. The value is quoted like a C string to avoid - control characters (the colon is quoted "\x3a"). - This is not used with --fixed-list-mode in gpg. - A UAT record puts the attribute subpacket count here, a - space, and then the total attribute subpacket size. - In gpgsm the issuer name comes here - An FPR record stores the fingerprint here. - The fingerprint of an revocation key is stored here. -11. Field: Signature class. This is a 2 digit hexnumber followed by - either the letter 'x' for an exportable signature or the - letter 'l' for a local-only signature. - The class byte of an revocation key is also given here, - 'x' and 'l' ist used the same way. -12. Field: Key capabilities: - e = encrypt - s = sign - c = certify - a = authentication - A key may have any combination of them in any order. In - addition to these letters, the primary key has uppercase - versions of the letters to denote the _usable_ - capabilities of the entire key, and a potential letter 'D' - to indicate a disabled key. -13. Field: Used in FPR records for S/MIME keys to store the fingerprint of - the issuer certificate. This is useful to build the - certificate path based on certificates stored in the local - keyDB; it is only filled if the issue certificate is - available. The advantage of using this value is that it is - guaranteed to have been been build by the same lookup - algorithm as gpgsm uses. - For "uid" recods this lists the preferences n the sameway the - -edit menu does. - For "sig" records, this is the fingerprint of the key that - issued the signature. Note that this is only filled in if - the signature verified correctly. Note also that for - various technical reasons, this fingerprint is only - available if --no-sig-cache is used. - -14. Field Flag field used in the --edit menu output: - -15. Field Used in sec/sbb to print the serial number of a token - (internal protect mode 1002) or a '#' if that key is a - simple stub (internal protect mode 1001) - -All dates are displayed in the format yyyy-mm-dd unless you use the -option --fixed-list-mode in which case they are displayed as seconds -since Epoch. More fields may be added later, so parsers should be -prepared for this. When parsing a number the parser should stop at the -first non-number character so that additional information can later be -added. - -If field 1 has the tag "pkd", a listing looks like this: -pkd:0:1024:B665B1435F4C2 .... FF26ABB: - ! ! !-- the value - ! !------ for information number of bits in the value - !--------- index (eg. DSA goes from 0 to 3: p,q,g,y) - - -The "tru" trust database records have the fields: - - 2: Reason for staleness of trust. If this field is empty, then the - trustdb is not stale. This field may have multiple flags in it: - - o: Trustdb is old - t: Trustdb was built with a different trust model than the one we - are using now. - - 3: Trust model: - 0: Classic trust model, as used in PGP 2.x. - 1: PGP trust model, as used in PGP 6 and later. This is the same - as the classic trust model, except for the addition of trust - signatures. - - GnuPG before version 1.4 used the classic trust model by default. - GnuPG 1.4 and later uses the PGP trust model by default. - - 4: Date trustdb was created in seconds since 1/1/1970. - 5: Date trustdb will expire in seconds since 1/1/1970. - -The "spk" signature subpacket records have the fields: - - 2: Subpacket number as per RFC-2440 and later. - 3: Flags in hex. Currently the only two bits assigned are 1, to - indicate that the subpacket came from the hashed part of the - signature, and 2, to indicate the subpacket was marked critical. - 4: Length of the subpacket. Note that this is the length of the - subpacket, and not the length of field 5 below. Due to the need - for %-encoding, the length of field 5 may be up to 3x this value. - 5: The subpacket data. Printable ASCII is shown as ASCII, but other - values are rendered as %XX where XX is the hex value for the byte. - - -Format of the "--status-fd" output -================================== -Every line is prefixed with "[GNUPG:] ", followed by a keyword with -the type of the status line and a some arguments depending on the -type (maybe none); an application should always be prepared to see -more arguments in future versions. - - - NEWSIG - May be issued right before a signature verification starts. This - is useful to define a context for parsing ERROR status - messages. No arguments are currently defined. - - GOODSIG <long keyid> <username> - The signature with the keyid is good. For each signature only - one of the three codes GOODSIG, BADSIG or ERRSIG will be - emitted and they may be used as a marker for a new signature. - The username is the primary one encoded in UTF-8 and %XX - escaped. - - EXPSIG <long keyid> <username> - The signature with the keyid is good, but the signature is - expired. The username is the primary one encoded in UTF-8 and - %XX escaped. - - EXPKEYSIG <long keyid> <username> - The signature with the keyid is good, but the signature was - made by an expired key. The username is the primary one - encoded in UTF-8 and %XX escaped. - - REVKEYSIG <long keyid> <username> - The signature with the keyid is good, but the signature was - made by a revoked key. The username is the primary one - encoded in UTF-8 and %XX escaped. - - BADSIG <long keyid> <username> - The signature with the keyid has not been verified okay. - The username is the primary one encoded in UTF-8 and %XX - escaped. - - ERRSIG <long keyid> <pubkey_algo> <hash_algo> \ - <sig_class> <timestamp> <rc> - It was not possible to check the signature. This may be - caused by a missing public key or an unsupported algorithm. - A RC of 4 indicates unknown algorithm, a 9 indicates a missing - public key. The other fields give more information about - this signature. sig_class is a 2 byte hex-value. - - Note, that TIMESTAMP may either be a number with seconds since - epoch or an ISO 8601 string which can be detected by the - presence of the letter 'T' inside. - - VALIDSIG <fingerprint in hex> <sig_creation_date> <sig-timestamp> - <expire-timestamp> <sig-version> <reserved> <pubkey-algo> - <hash-algo> <sig-class> <primary-key-fpr> - - The signature with the keyid is good. This is the same as - GOODSIG but has the fingerprint as the argument. Both status - lines are emitted for a good signature. All arguments here - are on one long line. sig-timestamp is the signature creation - time in seconds after the epoch. expire-timestamp is the - signature expiration time in seconds after the epoch (zero - means "does not expire"). sig-version, pubkey-algo, hash-algo, - and sig-class (a 2-byte hex value) are all straight from the - signature packet. PRIMARY-KEY-FPR is the fingerprint of the - primary key or identical to the first argument. This is - useful to get back to the primary key without running gpg - again for this purpose. - - Note, that *-TIMESTAMP may either be a number with seconds - since epoch or an ISO 8601 string which can be detected by the - presence of the letter 'T' inside. - - SIG_ID <radix64_string> <sig_creation_date> <sig-timestamp> - This is emitted only for signatures of class 0 or 1 which - have been verified okay. The string is a signature id - and may be used in applications to detect replay attacks - of signed messages. Note that only DLP algorithms give - unique ids - others may yield duplicated ones when they - have been created in the same second. - - Note, that SIG-TIMESTAMP may either be a number with seconds - since epoch or an ISO 8601 string which can be detected by the - presence of the letter 'T' inside. - - - ENC_TO <long keyid> <keytype> <keylength> - The message is encrypted to this keyid. - keytype is the numerical value of the public key algorithm, - keylength is the length of the key or 0 if it is not known - (which is currently always the case). - - NODATA <what> - No data has been found. Codes for what are: - 1 - No armored data. - 2 - Expected a packet but did not found one. - 3 - Invalid packet found, this may indicate a non OpenPGP - message. - 4 - signature expected but not found - You may see more than one of these status lines. - - UNEXPECTED <what> - Unexpected data has been encountered - 0 - not further specified 1 - - - TRUST_UNDEFINED <error token> - TRUST_NEVER <error token> - TRUST_MARGINAL - TRUST_FULLY - TRUST_ULTIMATE - For good signatures one of these status lines are emitted - to indicate how trustworthy the signature is. The error token - values are currently only emiited by gpgsm. - - PKA_TRUST_GOOD <mailbox> - PKA_TRUST_BAD <mailbox> - Depending on the outcome of the PKA check one of the above - status codes is emitted in addition to a TRUST_* status. - Without PKA info available or - - SIGEXPIRED - This is deprecated in favor of KEYEXPIRED. - - KEYEXPIRED <expire-timestamp> - The key has expired. expire-timestamp is the expiration time - in seconds after the epoch. - - Note, that TIMESTAMP may either be a number with seconds since - epoch or an ISO 8601 string which can be detected by the - presence of the letter 'T' inside. - - KEYREVOKED - The used key has been revoked by its owner. No arguments yet. - - BADARMOR - The ASCII armor is corrupted. No arguments yet. - - RSA_OR_IDEA - The IDEA algorithms has been used in the data. A - program might want to fallback to another program to handle - the data if GnuPG failed. This status message used to be emitted - also for RSA but this has been dropped after the RSA patent expired. - However we can't change the name of the message. - - SHM_INFO - SHM_GET - SHM_GET_BOOL - SHM_GET_HIDDEN - - GET_BOOL - GET_LINE - GET_HIDDEN - GOT_IT - - NEED_PASSPHRASE <long main keyid> <long keyid> <keytype> <keylength> - Issued whenever a passphrase is needed. - keytype is the numerical value of the public key algorithm - or 0 if this is not applicable, keylength is the length - of the key or 0 if it is not known (this is currently always the case). - - NEED_PASSPHRASE_SYM <cipher_algo> <s2k_mode> <s2k_hash> - Issued whenever a passphrase for symmetric encryption is needed. - - NEED_PASSPHRASE_PIN <card_type> <chvno> [<serialno>] - Issued whenever a PIN is requested to unlock a card. - - MISSING_PASSPHRASE - No passphrase was supplied. An application which encounters this - message may want to stop parsing immediately because the next message - will probably be a BAD_PASSPHRASE. However, if the application - is a wrapper around the key edit menu functionality it might not - make sense to stop parsing but simply ignoring the following - BAD_PASSPHRASE. - - BAD_PASSPHRASE <long keyid> - The supplied passphrase was wrong or not given. In the latter case - you may have seen a MISSING_PASSPHRASE. - - GOOD_PASSPHRASE - The supplied passphrase was good and the secret key material - is therefore usable. - - DECRYPTION_FAILED - The symmetric decryption failed - one reason could be a wrong - passphrase for a symmetrical encrypted message. - - DECRYPTION_OKAY - The decryption process succeeded. This means, that either the - correct secret key has been used or the correct passphrase - for a conventional encrypted message was given. The program - itself may return an errorcode because it may not be possible to - verify a signature for some reasons. - - NO_PUBKEY <long keyid> - NO_SECKEY <long keyid> - The key is not available - - IMPORT_CHECK <long keyid> <fingerprint> <user ID> - This status is emitted in interactive mode right before - the "import.okay" prompt. - - IMPORTED <long keyid> <username> - The keyid and name of the signature just imported - - IMPORT_OK <reason> [<fingerprint>] - The key with the primary key's FINGERPRINT has been imported. - Reason flags: - 0 := Not actually changed - 1 := Entirely new key. - 2 := New user IDs - 4 := New signatures - 8 := New subkeys - 16 := Contains private key. - The flags may be ORed. - - IMPORT_PROBLEM <reason> [<fingerprint>] - Issued for each import failure. Reason codes are: - 0 := "No specific reason given". - 1 := "Invalid Certificate". - 2 := "Issuer Certificate missing". - 3 := "Certificate Chain too long". - 4 := "Error storing certificate". - - IMPORT_RES <count> <no_user_id> <imported> <imported_rsa> <unchanged> - <n_uids> <n_subk> <n_sigs> <n_revoc> <sec_read> <sec_imported> <sec_dups> <not_imported> - Final statistics on import process (this is one long line) - - FILE_START <what> <filename> - Start processing a file <filename>. <what> indicates the performed - operation: - 1 - verify - 2 - encrypt - 3 - decrypt - - FILE_DONE - Marks the end of a file processing which has been started - by FILE_START. - - BEGIN_DECRYPTION - END_DECRYPTION - Mark the start and end of the actual decryption process. These - are also emitted when in --list-only mode. - - BEGIN_ENCRYPTION <mdc_method> <sym_algo> - END_ENCRYPTION - Mark the start and end of the actual encryption process. - - BEGIN_SIGNING - Mark the start of the actual signing process. This may be used - as an indication that all requested secret keys are ready for - use. - - DELETE_PROBLEM reason_code - Deleting a key failed. Reason codes are: - 1 - No such key - 2 - Must delete secret key first - 3 - Ambigious specification - - PROGRESS what char cur total - Used by the primegen and Public key functions to indicate progress. - "char" is the character displayed with no --status-fd enabled, with - the linefeed replaced by an 'X'. "cur" is the current amount - done and "total" is amount to be done; a "total" of 0 indicates that - the total amount is not known. 100/100 may be used to detect the - end of operation. - Well known values for WHAT: - "pk_dsa" - DSA key generation - "pk_elg" - Elgamal key generation - "primegen" - Prime generation - "need_entropy" - Waiting for new entropy in the RNG - "file:XXX" - processing file XXX - (note that current gpg versions leave out the - "file:" prefix). - "tick" - generic tick without any special meaning - useful - for letting clients know that the server is - still working. - "starting_agent" - A gpg-agent was started because it is not - running as a daemon. - - - SIG_CREATED <type> <pubkey algo> <hash algo> <class> <timestamp> <key fpr> - A signature has been created using these parameters. - type: 'D' = detached - 'C' = cleartext - 'S' = standard - (only the first character should be checked) - class: 2 hex digits with the signature class - - Note, that TIMESTAMP may either be a number with seconds since - epoch or an ISO 8601 string which can be detected by the - presence of the letter 'T' inside. - - KEY_CREATED <type> <fingerprint> [<handle>] - A key has been created - type: 'B' = primary and subkey - 'P' = primary - 'S' = subkey - The fingerprint is one of the primary key for type B and P and - the one of the subkey for S. Handle is an arbitrary - non-whitespace string used to match key parameters from batch - key creation run. - - KEY_NOT_CREATED [<handle>] - The key from batch run has not been created due to errors. - - - SESSION_KEY <algo>:<hexdigits> - The session key used to decrypt the message. This message will - only be emitted when the special option --show-session-key - is used. The format is suitable to be passed to the option - --override-session-key - - NOTATION_NAME <name> - NOTATION_DATA <string> - name and string are %XX escaped; the data may be splitted - among several notation_data lines. - - USERID_HINT <long main keyid> <string> - Give a hint about the user ID for a certain keyID. - - POLICY_URL <string> - string is %XX escaped - - BEGIN_STREAM - END_STREAM - Issued by pipemode. - - INV_RECP <reason> <requested_recipient> - Issued for each unusable recipient. The reasons codes - currently in use are: - 0 := "No specific reason given". - 1 := "Not Found" - 2 := "Ambigious specification" - 3 := "Wrong key usage" - 4 := "Key revoked" - 5 := "Key expired" - 6 := "No CRL known" - 7 := "CRL too old" - 8 := "Policy mismatch" - 9 := "Not a secret key" - 10 := "Key not trusted" - - Note that this status is also used for gpgsm's SIGNER command - where it relates to signer's of course. - - NO_RECP <reserved> - Issued when no recipients are usable. - - ALREADY_SIGNED <long-keyid> - Warning: This is experimental and might be removed at any time. - - TRUNCATED <maxno> - The output was truncated to MAXNO items. This status code is issued - for certain external requests - - ERROR <error location> <error code> - - This is a generic error status message, it might be followed - by error location specific data. <error token> and - <error_location> should not contain a space. The error code - is a either a string commencing with a letter or such string - prefix with a numerical error code and an underscore; e.g.: - "151011327_EOF" - - ATTRIBUTE <fpr> <octets> <type> <index> <count> - <timestamp> <expiredate> <flags> - This is one long line issued for each attribute subpacket when - an attribute packet is seen during key listing. <fpr> is the - fingerprint of the key. <octets> is the length of the - attribute subpacket. <type> is the attribute type - (1==image). <index>/<count> indicates that this is the Nth - indexed subpacket of count total subpackets in this attribute - packet. <timestamp> and <expiredate> are from the - self-signature on the attribute packet. If the attribute - packet does not have a valid self-signature, then the - timestamp is 0. <flags> are a bitwise OR of: - 0x01 = this attribute packet is a primary uid - 0x02 = this attribute packet is revoked - 0x04 = this attribute packet is expired - - CARDCTRL <what> [<serialno>] - This is used to control smartcard operations. - Defined values for WHAT are: - 1 = Request insertion of a card. Serialnumber may be given - to request a specific card. - 2 = Request removal of a card. - 3 = Card with serialnumber detected - 4 = No card available. - 5 = No card reader available - - - PLAINTEXT <format> <timestamp> <filename> - This indicates the format of the plaintext that is about to be - written. The format is a 1 byte hex code that shows the - format of the plaintext: 62 ('b') is binary data, 74 ('t') is - text data with no character set specified, and 75 ('u') is - text data encoded in the UTF-8 character set. The timestamp - is in seconds since the epoch. If a filename is available it - gets printed as the third argument, percent-escaped as usual. - - PLAINTEXT_LENGTH <length> - This indicates the length of the plaintext that is about to be - written. Note that if the plaintext packet has partial length - encoding it is not possible to know the length ahead of time. - In that case, this status tag does not appear. - - SIG_SUBPACKET <type> <flags> <len> <data> - This indicates that a signature subpacket was seen. The - format is the same as the "spk" record above. - - SC_OP_FAILURE [<code>] - An operation on a smartcard definitely failed. Currently - there is no indication of the actual error code, but - application should be prepared to later accept more arguments. - Defined values for CODE are: - 0 - unspecified error (identically to a missing CODE) - 1 - canceled - 2 - bad PIN - - SC_OP_SUCCESS - A smart card operaion succeeded. This status is only printed - for certain operation and is mostly useful to check whether a - PIN change really worked. - - BACKUP_KEY_CREATED fingerprint fname - A backup key named FNAME has been created for the key with - KEYID. - - -Format of the "--attribute-fd" output -===================================== - -When --attribute-fd is set, during key listings (--list-keys, ---list-secret-keys) GnuPG dumps each attribute packet to the file -descriptor specified. --attribute-fd is intended for use with ---status-fd as part of the required information is carried on the -ATTRIBUTE status tag (see above). - -The contents of the attribute data is specified by 2440bis, but for -convenience, here is the Photo ID format, as it is currently the only -attribute defined: - - Byte 0-1: The length of the image header. Due to a historical - accident (i.e. oops!) back in the NAI PGP days, this is - a little-endian number. Currently 16 (0x10 0x00). - - Byte 2: The image header version. Currently 0x01. - - Byte 3: Encoding format. 0x01 == JPEG. - - Byte 4-15: Reserved, and currently unused. - - All other data after this header is raw image (JPEG) data. - - -Format of the "--list-config" output -==================================== - ---list-config outputs information about the GnuPG configuration for -the benefit of frontends or other programs that call GnuPG. There are -several list-config items, all colon delimited like the rest of the ---with-colons output. The first field is always "cfg" to indicate -configuration information. The second field is one of (with -examples): - -version: the third field contains the version of GnuPG. - - cfg:version:1.3.5 - -pubkey: the third field contains the public key algorithmdcaiphers - this version of GnuPG supports, separated by semicolons. The - algorithm numbers are as specified in RFC-2440. - - cfg:pubkey:1;2;3;16;17 - -cipher: the third field contains the symmetric ciphers this version of - GnuPG supports, separated by semicolons. The cipher numbers - are as specified in RFC-2440. - - cfg:cipher:2;3;4;7;8;9;10 - -digest: the third field contains the digest (hash) algorithms this - version of GnuPG supports, separated by semicolons. The - digest numbers are as specified in RFC-2440. - - cfg:digest:1;2;3;8;9;10 - -compress: the third field contains the compression algorithms this - version of GnuPG supports, separated by semicolons. The - algorithm numbers are as specified in RFC-2440. - - cfg:compress:0;1;2;3 - -group: the third field contains the name of the group, and the fourth - field contains the values that the group expands to, separated - by semicolons. - -For example, a group of: - group mynames = paige 0x12345678 joe patti - -would result in: - cfg:group:mynames:patti;joe;0x12345678;paige - - -Key generation -============== - Key generation shows progress by printing different characters to - stderr: - "." Last 10 Miller-Rabin tests failed - "+" Miller-Rabin test succeeded - "!" Reloading the pool with fresh prime numbers - "^" Checking a new value for the generator - "<" Size of one factor decreased - ">" Size of one factor increased - - The prime number for Elgamal is generated this way: - - 1) Make a prime number q of 160, 200, 240 bits (depending on the keysize) - 2) Select the length of the other prime factors to be at least the size - of q and calculate the number of prime factors needed - 3) Make a pool of prime numbers, each of the length determined in step 2 - 4) Get a new permutation out of the pool or continue with step 3 - if we have tested all permutations. - 5) Calculate a candidate prime p = 2 * q * p[1] * ... * p[n] + 1 - 6) Check that this prime has the correct length (this may change q if - it seems not to be possible to make a prime of the desired length) - 7) Check whether this is a prime using trial divisions and the - Miller-Rabin test. - 8) Continue with step 4 if we did not find a prime in step 7. - 9) Find a generator for that prime. - - This algorithm is based on Lim and Lee's suggestion from the - Crypto '97 proceedings p. 260. - - -Unattended key generation -========================= -This feature allows unattended generation of keys controlled by a -parameter file. To use this feature, you use --gen-key together with ---batch and feed the parameters either from stdin or from a file given -on the commandline. - -The format of this file is as follows: - o Text only, line length is limited to about 1000 chars. - o You must use UTF-8 encoding to specify non-ascii characters. - o Empty lines are ignored. - o Leading and trailing spaces are ignored. - o A hash sign as the first non white space character indicates a comment line. - o Control statements are indicated by a leading percent sign, the - arguments are separated by white space from the keyword. - o Parameters are specified by a keyword, followed by a colon. Arguments - are separated by white space. - o The first parameter must be "Key-Type", control statements - may be placed anywhere. - o Key generation takes place when either the end of the parameter file - is reached, the next "Key-Type" parameter is encountered or at the - control statement "%commit" - o Control statements: - %echo <text> - Print <text>. - %dry-run - Suppress actual key generation (useful for syntax checking). - %commit - Perform the key generation. An implicit commit is done - at the next "Key-Type" parameter. - %pubring <filename> - %secring <filename> - Do not write the key to the default or commandline given - keyring but to <filename>. This must be given before the first - commit to take place, duplicate specification of the same filename - is ignored, the last filename before a commit is used. - The filename is used until a new filename is used (at commit points) - and all keys are written to that file. If a new filename is given, - this file is created (and overwrites an existing one). - Both control statements must be given. - o The order of the parameters does not matter except for "Key-Type" - which must be the first parameter. The parameters are only for the - generated keyblock and parameters from previous key generations are not - used. Some syntactically checks may be performed. - The currently defined parameters are: - Key-Type: <algo-number>|<algo-string> - Starts a new parameter block by giving the type of the - primary key. The algorithm must be capable of signing. - This is a required parameter. - Key-Length: <length-in-bits> - Length of the key in bits. Default is 1024. - Key-Usage: <usage-list> - Space or comma delimited list of key usage, allowed values are - "encrypt", "sign", and "auth". This is used to generate the - key flags. Please make sure that the algorithm is capable of - this usage. Note that OpenPGP requires that all primary keys - are capable of certification, so no matter what usage is given - here, the "cert" flag will be on. If no Key-Usage is - specified, all the allowed usages for that particular - algorithm are used. - Subkey-Type: <algo-number>|<algo-string> - This generates a secondary key. Currently only one subkey - can be handled. - Subkey-Length: <length-in-bits> - Length of the subkey in bits. Default is 1024. - Subkey-Usage: <usage-list> - Similar to Key-Usage. - Passphrase: <string> - If you want to specify a passphrase for the secret key, - enter it here. Default is not to use any passphrase. - Name-Real: <string> - Name-Comment: <string> - Name-Email: <string> - The 3 parts of a key. Remember to use UTF-8 here. - If you don't give any of them, no user ID is created. - Expire-Date: <iso-date>|(<number>[d|w|m|y]) - Set the expiration date for the key (and the subkey). It - may either be entered in ISO date format (2000-08-15) or as - number of days, weeks, month or years. Without a letter days - are assumed. - Preferences: <string> - Set the cipher, hash, and compression preference values for - this key. This expects the same type of string as "setpref" - in the --edit menu. - Revoker: <algo>:<fpr> [sensitive] - Add a designated revoker to the generated key. Algo is the - public key algorithm of the designated revoker (i.e. RSA=1, - DSA=17, etc.) Fpr is the fingerprint of the designated - revoker. The optional "sensitive" flag marks the designated - revoker as sensitive information. Only v4 keys may be - designated revokers. - Handle: <string> - This is an optional parameter only used with the status lines - KEY_CREATED and KEY_NOT_CREATED. STRING may be up to 100 - characters and should not contain spaces. It is useful for - batch key generation to associate a key parameter block with a - status line. - Keyserver: <string> - This is an optional parameter that specifies the preferred - keyserver URL for the key. - - -Here is an example: -$ cat >foo <<EOF - %echo Generating a standard key - Key-Type: DSA - Key-Length: 1024 - Subkey-Type: ELG-E - Subkey-Length: 1024 - Name-Real: Joe Tester - Name-Comment: with stupid passphrase - Name-Email: joe@foo.bar - Expire-Date: 0 - Passphrase: abc - %pubring foo.pub - %secring foo.sec - # Do a commit here, so that we can later print "done" :-) - %commit - %echo done -EOF -$ gpg --batch --gen-key foo - [...] -$ gpg --no-default-keyring --secret-keyring ./foo.sec \ - --keyring ./foo.pub --list-secret-keys -/home/wk/work/gnupg-stable/scratch/foo.sec ------------------------------------------- -sec 1024D/915A878D 2000-03-09 Joe Tester (with stupid passphrase) <joe@foo.bar> -ssb 1024g/8F70E2C0 2000-03-09 - - - -Layout of the TrustDB -===================== -The TrustDB is built from fixed length records, where the first byte -describes the record type. All numeric values are stored in network -byte order. The length of each record is 40 bytes. The first record of -the DB is always of type 1 and this is the only record of this type. - -FIXME: The layout changed, document it here. - - Record type 0: - -------------- - Unused record, can be reused for any purpose. - - Record type 1: - -------------- - Version information for this TrustDB. This is always the first - record of the DB and the only one with type 1. - 1 byte value 1 - 3 bytes 'gpg' magic value - 1 byte Version of the TrustDB (2) - 1 byte marginals needed - 1 byte completes needed - 1 byte max_cert_depth - The three items are used to check whether the cached - validity value from the dir record can be used. - 1 u32 locked flags [not used] - 1 u32 timestamp of trustdb creation - 1 u32 timestamp of last modification which may affect the validity - of keys in the trustdb. This value is checked against the - validity timestamp in the dir records. - 1 u32 timestamp of last validation [currently not used] - (Used to keep track of the time, when this TrustDB was checked - against the pubring) - 1 u32 record number of keyhashtable [currently not used] - 1 u32 first free record - 1 u32 record number of shadow directory hash table [currently not used] - It does not make sense to combine this table with the key table - because the keyid is not in every case a part of the fingerprint. - 1 u32 record number of the trusthashtbale - - - Record type 2: (directory record) - -------------- - Informations about a public key certificate. - These are static values which are never changed without user interaction. - - 1 byte value 2 - 1 byte reserved - 1 u32 LID . (This is simply the record number of this record.) - 1 u32 List of key-records (the first one is the primary key) - 1 u32 List of uid-records - 1 u32 cache record - 1 byte ownertrust - 1 byte dirflag - 1 byte maximum validity of all the user ids - 1 u32 time of last validity check. - 1 u32 Must check when this time has been reached. - (0 = no check required) - - - Record type 3: (key record) - -------------- - Informations about a primary public key. - (This is mainly used to lookup a trust record) - - 1 byte value 3 - 1 byte reserved - 1 u32 LID - 1 u32 next - next key record - 7 bytes reserved - 1 byte keyflags - 1 byte pubkey algorithm - 1 byte length of the fingerprint (in bytes) - 20 bytes fingerprint of the public key - (This is the value we use to identify a key) - - Record type 4: (uid record) - -------------- - Informations about a userid - We do not store the userid but the hash value of the userid because that - is sufficient. - - 1 byte value 4 - 1 byte reserved - 1 u32 LID points to the directory record. - 1 u32 next next userid - 1 u32 pointer to preference record - 1 u32 siglist list of valid signatures - 1 byte uidflags - 1 byte validity of the key calculated over this user id - 20 bytes ripemd160 hash of the username. - - - Record type 5: (pref record) - -------------- - This record type is not anymore used. - - 1 byte value 5 - 1 byte reserved - 1 u32 LID; points to the directory record (and not to the uid record!). - (or 0 for standard preference record) - 1 u32 next - 30 byte preference data - - Record type 6 (sigrec) - ------------- - Used to keep track of key signatures. Self-signatures are not - stored. If a public key is not in the DB, the signature points to - a shadow dir record, which in turn has a list of records which - might be interested in this key (and the signature record here - is one). - - 1 byte value 6 - 1 byte reserved - 1 u32 LID points back to the dir record - 1 u32 next next sigrec of this uid or 0 to indicate the - last sigrec. - 6 times - 1 u32 Local_id of signatures dir or shadow dir record - 1 byte Flag: Bit 0 = checked: Bit 1 is valid (we have a real - directory record for this) - 1 = valid is set (but may be revoked) - - - - Record type 8: (shadow directory record) - -------------- - This record is used to reserve a LID for a public key. We - need this to create the sig records of other keys, even if we - do not yet have the public key of the signature. - This record (the record number to be more precise) will be reused - as the dir record when we import the real public key. - - 1 byte value 8 - 1 byte reserved - 1 u32 LID (This is simply the record number of this record.) - 2 u32 keyid - 1 byte pubkey algorithm - 3 byte reserved - 1 u32 hintlist A list of records which have references to - this key. This is used for fast access to - signature records which are not yet checked. - Note, that this is only a hint and the actual records - may not anymore hold signature records for that key - but that the code cares about this. - 18 byte reserved - - - - Record Type 10 (hash table) - -------------- - Due to the fact that we use fingerprints to lookup keys, we can - implement quick access by some simple hash methods, and avoid - the overhead of gdbm. A property of fingerprints is that they can be - used directly as hash values. (They can be considered as strong - random numbers.) - What we use is a dynamic multilevel architecture, which combines - hashtables, record lists, and linked lists. - - This record is a hashtable of 256 entries; a special property - is that all these records are stored consecutively to make one - big table. The hash value is simple the 1st, 2nd, ... byte of - the fingerprint (depending on the indirection level). - - When used to hash shadow directory records, a different table is used - and indexed by the keyid. - - 1 byte value 10 - 1 byte reserved - n u32 recnum; n depends on the record length: - n = (reclen-2)/4 which yields 9 for the current record length - of 40 bytes. - - the total number of such record which makes up the table is: - m = (256+n-1) / n - which is 29 for a record length of 40. - - To look up a key we use the first byte of the fingerprint to get - the recnum from this hashtable and look up the addressed record: - - If this record is another hashtable, we use 2nd byte - to index this hash table and so on. - - if this record is a hashlist, we walk all entries - until we found one a matching one. - - if this record is a key record, we compare the - fingerprint and to decide whether it is the requested key; - - - Record type 11 (hash list) - -------------- - see hash table for an explanation. - This is also used for other purposes. - - 1 byte value 11 - 1 byte reserved - 1 u32 next next hash list record - n times n = (reclen-5)/5 - 1 u32 recnum - - For the current record length of 40, n is 7 - - - - Record type 254 (free record) - --------------- - All these records form a linked list of unused records. - 1 byte value 254 - 1 byte reserved (0) - 1 u32 next_free - - - -Packet Headers -=============== - -GNUPG uses PGP 2 packet headers and also understands OpenPGP packet header. -There is one enhancement used with the old style packet headers: - - CTB bits 10, the "packet-length length bits", have values listed in - the following table: - - 00 - 1-byte packet-length field - 01 - 2-byte packet-length field - 10 - 4-byte packet-length field - 11 - no packet length supplied, unknown packet length - - As indicated in this table, depending on the packet-length length - bits, the remaining 1, 2, 4, or 0 bytes of the packet structure field - are a "packet-length field". The packet-length field is a whole - number field. The value of the packet-length field is defined to be - the value of the whole number field. - - A value of 11 is currently used in one place: on compressed data. - That is, a compressed data block currently looks like <A3 01 . . .>, - where <A3>, binary 10 1000 11, is an indefinite-length packet. The - proper interpretation is "until the end of the enclosing structure", - although it should never appear outermost (where the enclosing - structure is a file). - -+ This will be changed with another version, where the new meaning of -+ the value 11 (see below) will also take place. -+ -+ A value of 11 for other packets enables a special length encoding, -+ which is used in case, where the length of the following packet can -+ not be determined prior to writing the packet; especially this will -+ be used if large amounts of data are processed in filter mode. -+ -+ It works like this: After the CTB (with a length field of 11) a -+ marker field is used, which gives the length of the following datablock. -+ This is a simple 2 byte field (MSB first) containing the amount of data -+ following this field, not including this length field. After this datablock -+ another length field follows, which gives the size of the next datablock. -+ A value of 0 indicates the end of the packet. The maximum size of a -+ data block is limited to 65534, thereby reserving a value of 0xffff for -+ future extensions. These length markers must be inserted into the data -+ stream just before writing the data out. -+ -+ This 2 byte field is large enough, because the application must buffer -+ this amount of data to prepend the length marker before writing it out. -+ Data block sizes larger than about 32k doesn't make any sense. Note -+ that this may also be used for compressed data streams, but we must use -+ another packet version to tell the application that it can not assume, -+ that this is the last packet. - - -GNU extensions to the S2K algorithm -=================================== -S2K mode 101 is used to identify these extensions. -After the hash algorithm the 3 bytes "GNU" are used to make -clear that these are extensions for GNU, the next bytes gives the -GNU protection mode - 1000. Defined modes are: - 1001 - do not store the secret part at all - 1002 - a stub to access smartcards (not used in 1.2.x) - - -Pipemode -======== -NOTE: This is deprecated and will be removed in future versions. - -This mode can be used to perform multiple operations with one call to -gpg. It comes handy in cases where you have to verify a lot of -signatures. Currently we support only detached signatures. This mode -is a kludge to avoid running gpg n daemon mode and using Unix Domain -Sockets to pass the data to it. There is no easy portable way to do -this under Windows, so we use plain old pipes which do work well under -Windows. Because there is no way to signal multiple EOFs in a pipe we -have to embed control commands in the data stream: We distinguish -between a data state and a control state. Initially the system is in -data state but it won't accept any data. Instead it waits for -transition to control state which is done by sending a single '@' -character. While in control state the control command os expected and -this command is just a single byte after which the system falls back -to data state (but does not necesary accept data now). The simplest -control command is a '@' which just inserts this character into the -data stream. - -Here is the format we use for detached signatures: -"@<" - Begin of new stream -"@B" - Detached signature follows. - This emits a control packet (1,'B') -<detached_signature> -"@t" - Signed text follows. - This emits the control packet (2, 'B') -<signed_text> -"@." - End of operation. The final control packet forces signature - verification -"@>" - End of stream - - - - - - -Other Notes -=========== - * For packet version 3 we calculate the keyids this way: - RSA := low 64 bits of n - ELGAMAL := build a v3 pubkey packet (with CTB 0x99) and calculate - a rmd160 hash value from it. This is used as the - fingerprint and the low 64 bits are the keyid. - - * Revocation certificates consist only of the signature packet; - "import" knows how to handle this. The rationale behind it is - to keep them small. - - - - - - - -Keyserver Message Format -========================= - -The keyserver may be contacted by a Unix Domain socket or via TCP. - -The format of a request is: - -==== -command-tag -"Content-length:" digits -CRLF -======= - -Where command-tag is - -NOOP -GET <user-name> -PUT -DELETE <user-name> - - -The format of a response is: - -====== -"GNUPG/1.0" status-code status-text -"Content-length:" digits -CRLF -============ -followed by <digits> bytes of data - - -Status codes are: - - o 1xx: Informational - Request received, continuing process - - o 2xx: Success - The action was successfully received, understood, - and accepted - - o 4xx: Client Error - The request contains bad syntax or cannot be - fulfilled - - o 5xx: Server Error - The server failed to fulfill an apparently - valid request - - - -Documentation on HKP (the http keyserver protocol): - -A minimalistic HTTP server on port 11371 recognizes a GET for /pks/lookup. -The standard http URL encoded query parameters are this (always key=value): - -- op=index (like pgp -kv), op=vindex (like pgp -kvv) and op=get (like - pgp -kxa) - -- search=<stringlist>. This is a list of words that must occur in the key. - The words are delimited with space, points, @ and so on. The delimiters - are not searched for and the order of the words doesn't matter (but see - next option). - -- exact=on. This switch tells the hkp server to only report exact matching - keys back. In this case the order and the "delimiters" are important. - -- fingerprint=on. Also reports the fingerprints when used with 'index' or - 'vindex' - -The keyserver also recognizes http-POSTs to /pks/add. Use this to upload -keys. - - -A better way to do this would be a request like: - - /pks/lookup/<gnupg_formatierte_user_id>?op=<operation> - -This can be implemented using Hurd's translator mechanism. -However, I think the whole key server stuff has to be re-thought; -I have some ideas and probably create a white paper. - diff --git a/rt/docs/design_docs/groups_notes b/rt/docs/design_docs/groups_notes deleted file mode 100644 index 234fd37fe..000000000 --- a/rt/docs/design_docs/groups_notes +++ /dev/null @@ -1,88 +0,0 @@ -CREATE TABLE Prinicpals ( - id int auto_increment - PrincipalType VARCHAR(16) not_null, - PrincipalId int # foreign key to Users or Groups, depending -) - -CREATE TABLE Groups ( - id int auto_increment, - Domain varchar(255), - Instance varchar(16), - Name varchar(255), - Description varchar(255), -); -CREATE TABLE ACL ( - id INTEGER NOT NULL AUTO_INCREMENT, - Principal integer NULL , #Foreign key to principals - RightName varchar(25) NULL , - RightDomain varchar(25) NULL , - RightInstance integer NULL , - PRIMARY KEY (id) -); - -CREATE TABLE GroupMembers ( - id int auto_increment, - Group int, # foreign key to Principals - Member int # foreign key to Principals -) - -create table GroupMembersCache ( - id int auto_increment, - Group int, # foreign key to Principals - Member int, # foreign key to Principals - Via int, #foreign key to g_m_u -) - -insert into principals values ('bubbles); -insert into principals values ('fubar'); -insert into principals values ('sheeri'); -insert into principals values ('sgw'); - -insert into principals values ('staff'); -insert into principals values ('sysadmin'); -insert into principals values ('senior admin'); - - -insert into group_members values(1, 'staff', 'bubbles'); -insert into group_members values(2, 'sysadmin', 'sheeri'); -insert into group_members values(3,'senior admin', 'sgw'); -insert into group_members values(4,'senior admin', 'fubar'); -insert into group_members values(5, 'sysadmin', 'senior admin') - -Groups - - - -Domain Queues -Instance <queueid#> -Name AdminCc, Cc - -/Queues/1/AdminCc -/Queues/3/Cc - -Domain Tickets -Instance <#n> -Name Owner, Requestor, Cc, AdminCc - -/Tickets/1/Owner -/Tickets/1/Requestor -/Tickets/1/Cc - Has members: /Queues/whatever queue the ticket has/Cc -/Tickets/1/AdminCc - Has members: /Queues/whatever queue the ticket has/AdminCc - - -Domain Users -Instance <userid> - -/Users/1/MyDelegates -/Users/1/MyOtherDelegates - - -Domain System -Name Admins, AdminManagers - -/System/Administrators -/System/Blah - - diff --git a/rt/docs/design_docs/link-definitions.txt b/rt/docs/design_docs/link-definitions.txt deleted file mode 100644 index e109744cf..000000000 --- a/rt/docs/design_docs/link-definitions.txt +++ /dev/null @@ -1,143 +0,0 @@ -For 2.0, those Linking actions should be supported: - -1. DependentOn; TobiX-style. - - BASE is dependent on TARGET. - - ...meaning that TARGET has to be resolved before BASE (really) is - resolved. - - According to TobiX, those "weird action" makes sense: - ...when the link and/or TARGET is created, the BASE might be stalled. - Alternatively, this should be very trivial to request through the UIs. - ...when the TARGET is resolved, BASE will be reopened if it's stalled. - - An alternative to those "weird actions" is to have some run-time logic that - takes care of this; i.e. letting the search interface handle "please hide - all requests with unresolved dependencies" - - TobiX will need to make dependency links into Bugzilla. - - Dependency links should be made when more work to BASE should be done - after the TARGET is resolved and/or BASE can't be resolved before TARGET is - resolved. - - Dependency links are often 1:1, but n:n links makes sense; one ticket can - depend on several others, several tickets can depend on one ticket, etc. - - Loops don't make sense at all, but the system above won't break if it - encounter loops. - - Dependency links is more for workflow than anything else. When a new - TARGET is created, some of the work might be passed over to another - department/person ... but _not_ the responsibility for the communication - with the external requestor. - -2. MemberOf link (grouping) - - BASE is a member of TARGET. - - TobiX-style "weird actions": - ...when TARGET is beeing replied to, all BASE requestors should get the - reply. - - ...when TARGET is resolved, all BASE tickets should be resolved (unless - they have other unresolved Dependencies/MemberOf links). - - ...when all BASEs to one TARGET are resolved, TARGET should be resolved. - - The alternative is to let the user choose "reply to all" and "resolve all" - through the user interfaces. - - MemberOf should be used when BASE ticket states more or less the same as - the TARGET ticket, and we do want to give a reply to all requestors, but we - don't want to merge them (Individual tickets from individual external - requestors should be respected as separate entities). If BASE tickets from - more than one external requestor is linked to a TARGET ticket, we denote - the TARGET ticket as a "Group ticket". This is only a documentation - definition, you won't find any references to "Group tickets" in the source. - - I think the proper etiquette should be to clearly state in a reply to a - group ticket that the mail is going to several persons, and that the - requestor should reply back if they feel their Ticket hasn't got the - attention it deserves. The user documentation should reflect this. - - MemberOf links can also be used to hand away the work flow. The person in - charge of the TARGET ticket will also be in charge of the BASE tickets and - the communication with the end user. - - If a work task needs to be splitted into two subtasks, MemberOf might also be - used. - - 1:n links makes more sense, but n:n can also work in some cases. - The reply stuff might break seriously upon loops. Recursement might be - handy for splitting a work task into subtasks (making a hierarchical tree - of the worktasks). - - -3. Merge (connecting) - - BASE is the same as TARGET. - - ...the system should somehow merge together transactions for both tickets. - ...BASE should be more or less deleted, only the TARGET should apply. - ...actions done toward BASE should be redirected to TARGET. - - I think MergeLinks should be used when two tickets accidentally has - appeared twice in the system, and/or there is no reason to keep the two - tickets separately. It might be that it's the same requestor (i.e. - clicking the "send" button twice in a web environment) or that we don't - care much about giving the requestor individual follow-up (typically - "internal" requestors, etc.) - - Based on user feedback, merged tickets will be displayed as the same ticket -within RT's user interfaces. but the original tickets' transactions will be -kept separated in the database. this may require some magic. - -4. RefersTo / No Action link (linking) - - BASE is somewhat related to TARGET - - No special actions will be taken. - - Loops might maybe make sense - -BASE and TARGET are usually Tickets within one RT instance, but it -might also point to external RT instances, other DB systems, etc. - - - - -In future revisions, it should be very easy to set up site-specific link action types. -We should also consider to include more linking actions in the box. - -An example stolen from John Rouillard. Eventually the [comments] should be -removed, and the text modified to fit the planned 2.0 link actions: - - ticket problem - 1 can't connect to hosts with netscape - 2 ping is broken - 3 Can't send email: error no space on spool/mqueue - - You have the above in the queue. You realize that DNS is down. Spawn - a ticket - - 4 DNS is down - - mergelink 1 and 2 to it [I would rather say "make a MemberOf link _or_ a - dependency link from 1 and 2 to 4" --TobiX] (if you choose to stall 1 and - 2 automatically feel free, its just a shell script change) [well, you - might choose dependency instead of MemberOf --TobiX]. The person working - on 3 has come to the conclusion that outgoing mail is backing up because - of the DNS failure. She has cleared space by copying the mail queue to - another disk, but can't really get email working till DNS is up. So she - creates a Dependency linkon ticket 4 stalling ticket 3. - - We finally get DNS working and resolve ticket 3. What happens? Tickets 1 - and 2 are resolved and email is sent to requestors notifying them of the - resolution [This is the default behaviour for 2.0 MemberOf-linked tickets. - Remember that if we send Replies to "Group Tickets" (that is, the target - of several "MemberOf" links) --TobiX]. Ticket 4 [should be 3? --TobiX] is - reopened and the person working on it starts flushing the mail queue and - the moved mailq by hand. - diff --git a/rt/docs/design_docs/realflow.txt b/rt/docs/design_docs/realflow.txt deleted file mode 100644 index 3717e273b..000000000 --- a/rt/docs/design_docs/realflow.txt +++ /dev/null @@ -1,191 +0,0 @@ -- I have a MonitoredQueue that sets tickets to "Monitored" - if its subject matches /monitored/. - -- I want to have a kind of Ticket that are 'Monitored'. -- I want all monitored tickets, when they are overdue for - 14 days, to: - - send notification to manager - - mark as stalled -- I want all monitored tickets, when they are overdue for - 28 days, to: - - mark as rejected -- I want to query all tickets that are monitored as such -- I want to modify 14 => 15 and have it affect all existing - tickets that are monitored - -{ -- I want to add a new "overdue for 27 days, add a 'ultimatum' - correspondence to it" rule for all monitored tickets. -- I want to add a new "overdue for 27 days, add a 'ultimatum' - correspondence to it" rule for all _new_ monitored tickets - without affecting existing ones. -} - -- The user of OrderRequest queue needs to fill a numeric "CF", - called "Price". -- On creation, it needs to create following approvals: - - "Manager" approval if CF.Price is > 1000 - - "President" approval if CF.Price is > 2000 -- When all of "M", "P" are resolved (if any, or if there were none - to begin with), Create a new approval, "Finance". -- If any approvals above is rejected, reject the original ticket. -- If "Finance" is resolved, resolve original ticket. -- If "Finance" is rejected, create an approval for "CEO". -- If "CEO" is resolved, resolve the original ticket. -- If "CEO" is rejected, reject the original ticket. - -[RuleAction CreateTicketWithRuleset] - -> ReleaseMyLockOnRuleset $ruleset - -> UnlessLockOnRuleset $ruleset - # i.e. if no active tickets still have a lock on it - -> ForceCreateTicketWithRuleset $ruleset - -[Queue OrderRequest] - -> Condition: OnCreate - Action: AddTicketRuleSet "PurchaseApproval" - # Triggers immediately - -[RuleSet: PurchaseApproval] - -> Condition: OnCreate - Condition: CF.Price > 1000 - Action: CreateTicketWithRuleset "ManagerApproval" - -> Condition: OnCreate - Condition: CF.Price > 2000 - Action: CreateTicketWithRuleset "PresidentApproval" - -> Condition: OnCreate - Action: CreateTicketWithRuleset "FinanceApproval" - -> Condition: OnReject - Action: DeleteTree - -[RuleSet: ManagerApproval] - -> Condition: OnCreate - Action: Prohibit Ruleset "FinanceApproval" - -> Condition: OnResolve - Action: CreateTicketWithRuleset "FinanceApproval" - -> Condition: OnReject - Action: RejectTicket TOP - -[RuleSet: PresidentApproval] - -> Condition: OnCreate - Action: Prohibit CreateTicketWithRuleset "FinanceApproval" - -> Condition: OnResolve - Action: CreateTicketWithRuleset "FinanceApproval" - -> Condition: OnReject - Action: RejectTicket TOP - -[RuleSet: FinanceApproval] - -> Condition: OnCreate - Action: Prohibit RuleSet "CEOApproval" - -> Condition: OnResolve - Action: ResolveTicket TOP - -> Condition: OnReject - Action: CreateTicketWithRuleset "CEOApproval" - -[RuleSet: CEOApproval] - -> Condition: OnResolve - Action: ResolveTicket TOP - -> Condition: OnReject - Action: RejectTicket TOP - - - -Prohibit Ticket Operation: - Ruleset CEOApproval - - - - - - - - ,--------. -[TOP] --> [M] --> [F] - ` `-> [P] -' - ` - `-> [X] --> [Y] - - -[TOP] => [Approval] - -> Queue: B - -> Rule: yyy - -> Workflow: W - -> Stage: Approval - -> Rule: xxx - -isa_ok( $Approval->Type, 'RT::Ticket' ); -is( $Approval->Workflow->Name, 'W' ); -is( $Approval->Stage->Name, 'Approval' ); - -[Queue: A] - -> Workflow: W - -[Workflow: W] - -> Stage: TOP - -> Stage: Approval - -> Stage: SUCCESS - -> Stage: FAIL - -"RuleCollections" - -[Stage: TOP] - -> Rule: OnCreate RunStage Approval - -ok( TicketA->Rules->HasEntry($ApprovalRule) ) -ok( TicketB->Rules->HasEntry($ApprovalRule) ) - -[Rule: Approval] - -> Rule: OnResolve RunStage SUCCESS - -> Rule: OnReject RunStage FAIL - -[Stage: SUCCESS] - -> Rule: OnCreate SetStatus('resolved') TOP - -[Stage: FAIL] - -> Rule: OnCreate SetStatus('rejected') TOP - -[Unassociated] - - Rule FOO: OnAnything { - CreateTicketIfNotBlocked StageFOO - AddLink DependedOnBy TOP to Stage1 - AssignRule DoStage2 to Stage1 - AssignRule DoStage3 to Stage1 - } - - Rule BAR: OnAnything { - CreateTicketIfNotBlocked StageBAR - DoSomethingBizzare - } - - ,==> [Stage0] ==>. - , . -[TOP] ==> [Stage1] ==> [Stage3] - ` ' - `==> [Stage2] ==>' - -OnTransaction: - $self->Ticket->Queues->Scrips->Apply - -OnTransaction: - $self->Ticket->Queues->Scrips->Apply - ->Scrips->Apply - -OnTransaction: - $self->Ticket->Queues->Scrips->Apply - ->Stages->Scrips->Apply - -[QueueX] - - Rule: - OnCreate: - RunRule FOO - -[QueueY] - - Rule: - OnWhatever: - RunRule FOO - - -[TOP] => [Stage1] => [Stage2] => [END] - `- => [Stage3] => [END] - ` -> [Stage4] - -[Stages] - -> diff --git a/rt/docs/design_docs/recursive_group_membership_algorithm b/rt/docs/design_docs/recursive_group_membership_algorithm deleted file mode 100644 index 250b9ad0d..000000000 --- a/rt/docs/design_docs/recursive_group_membership_algorithm +++ /dev/null @@ -1,109 +0,0 @@ -Group A has members 1, 2, 3 - - Cached members 1 is a member of A via "" - 2 is a member of A via "" - 3 is a member of A via "" - - -Group B has members A, 4, 5 - - Cached members: 4 is a member of B via "" $1 - 5 is a member of B via "" $2 - A is a member of B via "" $3 - 1 is a member of B via "$3" $4 - 2 is a member of B via "$3" $5 - 3 is a member of B via "$3" $6 - -Group C has members A, B, 6 - 6 is a member of C via "" $7 - A is a member of C via "" $8 - 1 is a member of C via $8 $9 - 2 is a member of C via $8 $10 - 3 is a member of C via $8 $11 - B is a member of C via "" $12 - 4 is a member of C via $12 $13 - 5 is a member of C via $12 $14 - A is a member of C via $12 $15 - 1 is a member of C via $15 $16 - 2 is a member of C via $15 $17 - 3 is a member of C via $15 $18 - - - -Group D has members A, C - - A is a member of D via "" $19 - 1 is a member of D via $19 $20 - 2 is a member of D via $19 $21 - 3 is a member of D via $19 $22 - C is a member of D via "" $23 - 6 is a member of D via $23 $24 - A is a member of D via $23 $25 - 1 is a member of D via $25 $26 - 2 is a member of D via $25 $27 - 3 is a member of D via $25 $28 - B is a member of D via $23 $29 - 4 is a member of D via $29 $30 - 5 is a member of D via $29 $31 - A is a member of D via $29 $32 - 1 is a member of D via $32 $33 - 2 is a member of D via $32 $34 - 3 is a member of D via $32 $35 - - - -Adding a new user, 7, to group A. - - - Add the user to group A in the groups table. - - Find all entries for group A in the cache table. - - For each entry in that list: - Add "7 is a member of $entry->top via $entry->id" - -Deleting a user, 7, from group A: - - Remove the user from group A in the groups table. - find all entries in the cache table where the principal id is user 7 and - the parent id is A. (requires a self join) - nuke them - - Alternatively: - find all entries for A in the cache table. - For each one, find the child whose id is 7. - Nuke it - - -Adding a group, B to group D. - - Add group B as a member of D in the groups table. - In the cache table: - $id = Add group B as a member of D via "" - - For each member of group B (4, 5, A): - - $sid= 4 is a member of D via $id - $sid= 5 is a member of D via $id - $sid= A is a member of D via $id - - if the member is a group itself, recurse down: - - 1 is a member of D via $sid - 2 is a member of D via $sid - 3 is a member of D via $sid - - Find all places where D is a member of $foo. - Repeat the above procedure, substituting $foo for D - and making $id D's id. - -Removing B as a member of D: - - Remove B as a member of D in the groups table. - Find all references to D in the pseudogroups table. - Find all children of D which are B: - Recurse down with the following algorithm: - If it's a user, delete it. - If it's a group, recurse through each member, - deleting its children and then deleting the - group itself. diff --git a/rt/docs/design_docs/rql_parser_machine.graphviz b/rt/docs/design_docs/rql_parser_machine.graphviz deleted file mode 100644 index 93ea989c1..000000000 --- a/rt/docs/design_docs/rql_parser_machine.graphviz +++ /dev/null @@ -1,35 +0,0 @@ - -/* GraphViz graph representing the state diagram of the RQL parser. -*/ - -/* XXX: It's not up to date anymore, we should delete it or update. -*/ - -digraph G { - - PAREN -> PAREN; - PAREN -> KEYWORD; - PAREN -> AGGREG; - - AGGREG -> KEYWORD; - AGGREG -> PAREN; - - KEYWORD -> OP; - - OP -> VALUE; - - VALUE -> PAREN; - VALUE -> AGGREG; - -/* - Blue lines represent added complexity of q[IN (x,y,z)] support. - The only place that the "blue tree" can be entered is at IN, and - exited at PAREN. -*/ - KEYWORD -> IN [color=blue]; - IN -> PAREN [color=blue]; - PAREN -> VALUE [color=blue]; - VALUE -> COMMA [color=blue]; - COMMA -> VALUE [color=blue]; - VALUE -> PAREN [color=blue]; -} diff --git a/rt/docs/design_docs/rt-mvc b/rt/docs/design_docs/rt-mvc deleted file mode 100644 index 3518b7d9a..000000000 --- a/rt/docs/design_docs/rt-mvc +++ /dev/null @@ -1,32 +0,0 @@ -Goals: - - - Never write an init block for a page that just views/edits pages - No style embedded in view/edit pages - - Validation / Error display and re-editing. - - -Implementation. - - - For a given object's fields: - - print a label for the field - print the current values for the field - print an edit widget for create - print an edit widget for update - - - - for a given form buttons for "perform the action" "don't perform the main action" - - -Edit widgets - - - text input - hidden - fixed enum as { dropdown, select multiple, sleect single, radio} - checkbox fixed enum - diff --git a/rt/docs/design_docs/ruleset-workflow.txt b/rt/docs/design_docs/ruleset-workflow.txt deleted file mode 100644 index f19dbd765..000000000 --- a/rt/docs/design_docs/ruleset-workflow.txt +++ /dev/null @@ -1,158 +0,0 @@ -# For an online version, see http://wiki.bestpractical.com/?RulesetWorkflow - -_*This is a design document for a work in progress. -It describes features that do not exist today and may never exist*_ - -== Text Description - -* The user of PurchaseOrder queue fill in a numeric "CF", called "Price". -* On creation, it needs to create following approvals: -** "ManagerApproval" if CF.Price is > 1000 -** "PresidentApproval" if CF.Price is > 2000 -* When all of "M", "P" are resolved (or if there were none to begin with), Create "FinanceApproval". -* If any approvals above is rejected, reject the original ticket. -* If "FinanceApproval" is resolved, resolve original ticket. -* If "FinanceApproval" is rejected, create an approval for "CEOApproval". -* If "CEOApproval" is resolved, resolve the original ticket. -* If "CEOApproval" is rejected, reject the original ticket. - -== ASCII Diagram - - ,----------. ,---------------------->[DONE] - | \ / ^ - [TOP]-+-?---->[M]---->[F] | - | | / \ | - `-?->[P]-+-' `-(!)->[C]-----------------' - | | | - | | `-(!)---------->[FAIL] - | | ^ - `-(!)----------------------------------' - -== Objects - -Note that "Scrips" are now called "Rules". - -=== RuleAction "AquireMyLocks" - - FOREACH $Scrip IN $TicketObj->Scrips - WHERE $Scrip.Action.Type == "TryCreateTicketWithRuleset" - DO LockRuleset $Scrip.Action.Argument - -=== RuleAction "TryCreateTicketWithRuleset" - - DO ReleaseMyLockOnRuleset $Argument - UNLESS RulesetLocked $Argument - DO CreateTicketWithRuleset $Argument - -=== RuleAction "CreateTicketWithRuleset" - - GIVEN $Ticket AS CreateTicket(@OtherArguments) - DO SetTicketRuleSet $Argument - DO RunTicketRuleSet $Argument - -=== GlobalRule "AquireLocks" - -* AppliesTo: All Objects -* Condition: OnCreate -* Action: AquireMyLocks - -=== Queue "PurchaseOrder" - -* Rule: -** Condition: OnCreate -** Action: SetTicketRuleSet "PurchaseFlow" -** Action: RunTicketRuleSet "PurchaseFlow" - -=== RuleSet "PurchaseFlow" - -* Rule (implicitly run by AcquireMyLocks): -** Condition: OnCreate -** Action: LockRuleSet "ManagerApproval" -** Action: LockRuleSet "PresidentApproval" -** Action: LockRuleSet "FinanceApproval" - -* Rule: -** Condition: OnCreate -** Condition: CF.Price > 1000 -** Action: TryCreateTicketWithRuleset "ManagerApproval" - -* Rule: -** Condition: OnCreate -** Condition: CF.Price > 2000 -** Action: TryCreateTicketWithRuleset "PresidentApproval" - -* Rule: -** Condition: OnCreate -** Condition: "Finance" is not blocked -** Action: TryCreateTicketWithRuleset "FinanceApproval" - -* Rule: -** Condition: OnReject -** Action: DeleteTree - -=== RuleSet: "ManagerApproval" - -* Rule (implicitly run by AcquireMyLocks): -** Condition: OnCreate -** Action: LockRuleSet "FinanceApproval" - -* Rule: -** Condition: OnResolve -** Action: TryCreateTicketWithRuleset "FinanceApproval" - -* Rule: -** Condition: OnReject -** Action: RejectTicket "PurchaseFlow" - -=== RuleSet: "PresidentApproval" - -* Rule (implicitly run by AcquireMyLocks): -** Condition: OnCreate -** Action: LockRuleSet "FinanceApproval" - -* Rule: -** Condition: OnResolve -** Action: TryCreateTicketWithRuleset "FinanceApproval" - -* Rule: -** Condition: OnReject -** Action: RejectTicket "PurchaseFlow" - -=== RuleSet: "FinanceApproval" - -* Rule: -** Condition: OnResolve -** Action: ResolveTicket "PurchaseFlow" - -* Rule: -** Condition: OnReject -** Action: ForceCreateTicketWithRuleset "CEOApproval" - -=== RuleSet: "CEOApproval" - -* Rule: -** Condition: OnResolve -** Action: ResolveTicket "PurchaseFlow" - -* Rule: -** Condition: OnReject -** Action: RejectTicket "PurchaseFlow" - -### FNORD FNORD FNORD FNORD FNORD FNORD FNORD FNORD FNORD ### - -== Another Text Description - -* I have a MonitoredQueue that sets tickets to "Monitored" if its subject matches /monitored/. -* I want to have a kind of Ticket that are 'Monitored'. -* I want all monitored tickets, when they are overdue for 14 days, to: -** Send notification to manager -** Mark as stalled -* I want all monitored tickets, when they are overdue for 28 days, to: -** Mark as rejected -* I want to query all tickets that are monitored as such -* I want to modify 14 => 15 and have it affect all existing tickets that are monitored -* I want to add a new "overdue for 27 days, add a 'ultimatum' correspondence to it" rule -** For all monitored tickets. -* I want to add a new "overdue for 27 days, add a 'ultimatum' correspondence to it" rule -** For all _new_ monitored tickets. -** Without affecting existing ones. diff --git a/rt/docs/design_docs/subscription-definitions.txt b/rt/docs/design_docs/subscription-definitions.txt deleted file mode 100755 index deda35cda..000000000 --- a/rt/docs/design_docs/subscription-definitions.txt +++ /dev/null @@ -1,113 +0,0 @@ -NEW SCRIP NOTES - - -RT Actions: - - - EmailOwnerAsComment - Send mail to the ticket owner from the queue's comment address - - EmailOwnerOrAdminWatchersAsComment - Send mail to the ticket owner, or if there is no owner, the ticket's admin watchers - from the queue's comment addresses - - EmailAdminWatchersAsComment - Send mail to the ticket's adminstrative watchers from the queue's comment address - - - - EmailOwner - Send mail to the ticket owner from the queue's correspond address - - EmailOwnerOrAdminWatchers - Send mail to the ticket owner, or if there is no owner, the ticket's admin watchers - from the queue's correspond addresses - - EmailAdminWatchers - Send mail to the ticket's adminstrative watchers from the queue's correspond address - - EmailWatchers - Send mail to the ticket watchers from the queue's correspond address - - AutoReply - Sendmail to the requestor from the queue's correspond address. - - - -RT Conditions: - OnCreate - OnEachTransaction - OnComment - OnCorrespond - - - - - -What is an Action? - -...some piece of code that can do something whenever a transaction is done. -The actions shipped with RT sends email and can handle some logic that makes -sense for some instances. site-specific modules can be dropped in to -perform special actions. - - -What can an Action do? - -- decide whether it's applicable or not -- prepare -- commit -- describe itself - -...and if it's a subclass of SendEmail, you can also override a lot. - -Currently the schema.mysql contains a list of the basic subscription-related -actions that will be bundled with RT. - - -What is a Scrip? - -...it's an entry in the database that tells that an action is to be -performed with a certain template and argument. Template and argument -doesn't make sense in all contexts. A scrip can be limited to transaction -types; the current implementation allows a comma-separated list (though for -a "cleaner" schema design, it should be a separate table for this?). It has -a name and a description. - - -What is a ScripScope? - -...an indication of what queues the different Scrips applies to. It should -be easy to remove/insert ScripScope objects by the admin tools. - - -What is a Watcher? - -...it's a request for beeing kept updated on a ticket and/or a queue -and/or whatever. It is to be used by the Actions. Watcher items can -easily be enabled/disabled through the `Quiet' attribute. `Type' might -indicate what emails the watcher wants to get and how to get them. - -The Bcc/Cc watchers should be handled by the NotifyWatchers action which is -run regardless of the Scrips. - - -What is a Template? - -...A template is a text template that is to be used for outgoing email - -or for different use for different actions. One template can be used by -several Scrips. - - -How does the system determinate whom to send mail to? - -The ScripScope table in the DB should indicate whether a Scrip is relevant -for a queue or not /* TobiX thinks that this might eventually be extended to -keywords, tickets, etc, and not only Queues */ ... the Scope table should -indicate whether the Scrip is relevant for a given transaction type ... then -the given Action should determinate whether it applies or not, and finally -the Action has to find out (via the Watchers table) whom it applies to, and -how to contact them ... and the Template tells how the mails that are sent -out should look like. - - diff --git a/rt/docs/design_docs/ticket_templates b/rt/docs/design_docs/ticket_templates deleted file mode 100644 index 7850edf73..000000000 --- a/rt/docs/design_docs/ticket_templates +++ /dev/null @@ -1,16 +0,0 @@ -===Create-Ticket: foo - Subject: APPROVE <%TOP-Subject%> - Status: status - Queue: <%TOP-Queue%> - Owner: <%TOP-Owner%> - Depends-on: <%TOP-Id%> - Child-of: <%TOP-Id%> - Refers-to: <%TOP-Id%> - Content-Type: text/plain - Content: This is content -blah -blah -blah -===Create-Ticket: bar -Subject: <%foo-Subject%> - diff --git a/rt/docs/design_docs/users b/rt/docs/design_docs/users deleted file mode 100644 index 71c4476c9..000000000 --- a/rt/docs/design_docs/users +++ /dev/null @@ -1,14 +0,0 @@ -RT2 makes everybody a user. some sites won't like this. there -should be away to make an "anonymous" user who the mailgate makes -the requestor for all mailed in tickets. it would then set the -ticket 'requestor' watcher's alternate email address to the real -requestor's email. - -additionally, eventually, users will need to be deleted. RT doesn't -want any user deleted. Instead, there will be a flag in the user's -entry in the users table called 'Disabled.' Disabled users will -not be able to be granted rights. - - The process of disabling a user should remove their acls and -should force the giving away of their tickets or reject the disabling. - |