File Coverage

blib/lib/Lim/Plugin/SoftHSM.pm
Criterion Covered Total %
statement 9 9 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 12 12 100.0


line stmt bran cond sub pod time code
1             package Lim::Plugin::SoftHSM;
2              
3 1     1   25602 use common::sense;
  1         12  
  1         6  
4 1     1   65 use Carp;
  1         2  
  1         94  
5              
6 1     1   9 use base qw(Lim::Component);
  1         8  
  1         827  
7              
8             =encoding utf8
9              
10             =head1 NAME
11              
12             Lim::Plugin::SoftHSM - SoftHSM management plugin for Lim
13              
14             =head1 VERSION
15              
16             Version 0.14
17              
18             =cut
19              
20             our $VERSION = '0.14';
21              
22             =head1 SYNOPSIS
23              
24             use Lim::Plugin::SoftHSM;
25              
26             # Create a Server object
27             $server = Lim::Plugin::SoftHSM->Server;
28              
29             # Create a Client object
30             $client = Lim::Plugin::SoftHSM->Client;
31              
32             # Create a CLI object
33             $cli = Lim::Plugin::SoftHSM->CLI;
34              
35             =head1 DESCRIPTION
36              
37             This plugin lets you manage a SoftHSM installation via Lim.
38              
39             =head1 METHODS
40              
41             =over 4
42              
43             =item $plugin_name = Lim::Plugin::SoftHSM->Name
44              
45             Returns the plugin's name.
46              
47             =cut
48              
49             sub Name {
50             'SoftHSM';
51             }
52              
53             =item $plugin_description = Lim::Plugin::SoftHSM->Description
54              
55             Returns the plugin's description.
56              
57             =cut
58              
59             sub Description {
60             'This plugin lets you manage a SoftHSM installation via Lim.';
61             }
62              
63             =item $call_hash_ref = Lim::Plugin::SoftHSM->Calls
64              
65             Returns a hash reference to the calls that can be made to this plugin, used both
66             in Server and Client to verify input and output arguments.
67              
68             See CALLS for list of calls and arguments.
69              
70             =cut
71              
72             sub Calls {
73             {
74             ReadVersion => {
75             out => {
76             version => 'string',
77             program => {
78             name => 'string',
79             version => 'string'
80             }
81             }
82             },
83             #
84             # Calls for config files
85             #
86             ReadConfigs => {
87             out => {
88             file => {
89             name => 'string',
90             write => 'bool',
91             read => 'bool'
92             }
93             }
94             },
95             CreateConfig => {
96             in => {
97             file => {
98             '' => 'required',
99             name => 'string',
100             content => 'string'
101             }
102             }
103             },
104             ReadConfig => {
105             in => {
106             file => {
107             '' => 'required',
108             name => 'string'
109             }
110             },
111             out => {
112             file => {
113             name => 'string',
114             content => 'string'
115             }
116             }
117             },
118             UpdateConfig => {
119             in => {
120             file => {
121             '' => 'required',
122             name => 'string',
123             content => 'string'
124             }
125             }
126             },
127             DeleteConfig => {
128             in => {
129             file => {
130             '' => 'required',
131             name => 'string'
132             }
133             }
134             },
135             #
136             # Calls for softhsm executable tool
137             #
138             ReadShowSlots => {
139             out => {
140             slot => {
141             id => 'integer',
142             token_label => 'string',
143             token_present => 'bool',
144             token_initialized => 'bool',
145             user_pin_initialized => 'bool',
146             }
147             }
148             },
149             CreateInitToken => {
150             in => {
151             token => {
152             '' => 'required',
153             slot => 'integer',
154             label => 'string',
155             so_pin => 'string',
156             pin => 'string'
157             }
158             }
159             },
160             CreateImport => {
161             in => {
162             key_pair => {
163             '' => 'required',
164             content => 'string',
165             file_pin => 'string optional',
166             slot => 'integer',
167             pin => 'string',
168             label => 'string',
169             id => 'string'
170             }
171             }
172             },
173             ReadExport => {
174             in => {
175             key_pair => {
176             '' => 'required',
177             file_pin => 'string optional',
178             slot => 'integer',
179             pin => 'string',
180             id => 'string'
181             }
182             },
183             out => {
184             key_pair => {
185             id => 'string',
186             content => 'string'
187             }
188             }
189             },
190             UpdateOptimize => {
191             in => {
192             slot => {
193             '' => 'required',
194             id => 'integer',
195             pin => 'string'
196             }
197             }
198             },
199             UpdateTrusted => {
200             in => {
201             key_pair => {
202             '' => 'required',
203             trusted => 'bool',
204             slot => 'integer',
205             so_pin => 'string',
206             type => 'string',
207             label => 'string optional',
208             id => 'string optional'
209             }
210             }
211             }
212             };
213             }
214              
215             =item $command_hash_ref = Lim::Plugin::SoftHSM->Commands
216              
217             Returns a hash reference to the CLI commands that can be made by this plugin.
218              
219             See COMMANDS for list of commands and arguments.
220              
221             =cut
222              
223             sub Commands {
224             {
225             version => [ 'Show version of the plugin and SoftHSM' ],
226             configs => [ 'List configuration files' ],
227             config => {
228             view => [ '', 'Display the content of a configuration file' ],
229             edit => [ '', 'Edit a configuration file' ]
230             },
231             show => {
232             slots => [ 'List information about SoftHSM slots' ]
233             },
234             init => {
235             token => [ '
236             },
237             import => [ '[--slot ] [--pin ] [--id ] [--label
238             export => [ '[--slot ] [--pin ] [--id ] [--file-pin ] ', 'Export a key from SoftHSM into a local file' ],
239             optimize => [ '[--pin ] ', 'Optimize slot(s)' ],
240             trust => [ '[--slot ] [--so-pin ] [--type ] < --id | --label
241             untrust => [ '[--slot ] [--so-pin ] [--type ] < --id | --label
242             };
243             }
244              
245             =back
246              
247             =head1 CALLS
248              
249             See L on how calls and callback functions should be
250             used.
251              
252             =over 4
253              
254             =item $client->ReadVersion(sub { my ($call) = @_; })
255              
256             Get the version of the plugin and version of SoftHSM found.
257              
258             $response = {
259             version => string, # Version of the plugin
260             program => # Single hash or an array of hashes as below:
261             {
262             name => string, # Program name
263             version => string, # Program version
264             }
265             };
266              
267             =item $client->ReadConfigs(sub { my ($call) = @_; })
268              
269             Get a list of all config files that can be managed by this plugin.
270              
271             $response = {
272             file => # Single hash or an array of hashes as below:
273             {
274             name => string, # Full path file name
275             read => bool, # True if readable
276             write => bool, # True if writable
277             }
278             };
279              
280             =item $client->CreateConfig($input, sub { my ($call) = @_; })
281              
282             Create a new config file, returns an error if it failed to create the config
283             file otherwise there is no response.
284              
285             $input = {
286             file => # Single hash or an array of hashes as below:
287             {
288             name => string, # Full path file name
289             content => string, # Configuration content
290             }
291             };
292              
293             =item $client->ReadConfig($input, sub { my ($call) = @_; })
294              
295             Returns a config file as a content.
296              
297             $input = {
298             file => # Single hash or an array of hashes as below:
299             {
300             name => string, # Full path file name
301             }
302             };
303              
304             $response = {
305             file => # Single hash or an array of hashes as below:
306             {
307             name => string, # Full path file name
308             content => string, # Configuration content
309             }
310             };
311              
312             =item $client->UpdateConfig($input, sub { my ($call) = @_; })
313              
314             Update a config file, this will overwrite the file. Returns an error if it
315             failed to update the config file otherwise there is no reponse.
316              
317             $input = {
318             file => # Single hash or an array of hashes as below:
319             {
320             name => string, # Full path file name
321             content => string, # Configuration content
322             }
323             };
324              
325             =item $client->DeleteConfig($input, sub { my ($call) = @_; })
326              
327             Delete a config file, returns an error if it failed to delete the config file
328             otherwise there is no reponse.
329              
330             $input = {
331             file => # Single hash or an array of hashes as below:
332             {
333             name => string, # Full path file name
334             }
335             };
336              
337             =item $client->ReadShowSlots(sub { my ($call) = @_; })
338              
339             Get a list of all SoftHSM slots that are available.
340              
341             $response = {
342             slot => # Single hash or an array of hashes as below:
343             {
344             id => integer, # Slot id
345             token_initialized => bool, # True if the token has been initialized
346             token_label => string, # Token label
347             token_present => bool, # True if there is a token present
348             user_pin_initialized => bool, # True if the user pin for the token has
349             # been initialized
350             }
351             };
352              
353             =item $client->CreateInitToken($input, sub { my ($call) = @_; })
354              
355             Initialize a slot, returns an error if it failed to initialize the slot
356             otherwise there is no response.
357              
358             $input = {
359             token => # Single hash or an array of hashes as below:
360             {
361             slot => integer, # Slot id
362             label => string, # Label
363             pin => string, # User pin
364             so_pin => string, # Security Officer pin
365             }
366             };
367              
368             =item $client->CreateImport($input, sub { my ($call) = @_; })
369              
370             Import a key into a slot, returns an error if it failed to import the key
371             otherwise there is no response.
372              
373             $input = {
374             key_pair => # Single hash or an array of hashes as below:
375             {
376             slot => integer, # Slot to import to
377             id => string, # Key id
378             label => string, # Key label
379             pin => string, # User pin
380             content => string, # Key in PKCS#8 format
381             file_pin => string, # File pin if encrypted (optional)
382             }
383             };
384              
385             =item $client->ReadExport($input, sub { my ($call) = @_; })
386              
387             Export a key from a slot, returns an error if it failed to export the key.
388              
389             $input = {
390             key_pair => # Single hash or an array of hashes as below:
391             {
392             slot => integer, # Slot to export from
393             id => string, # Key id
394             pin => string, # User pin
395             file_pin => string, # File pin to use for encryption (optional)
396             }
397             };
398              
399             $response = {
400             key_pair => # Single hash or an array of hashes as below:
401             {
402             id => string, # Key id
403             content => string, # Key in PKCS#8 format
404             }
405             };
406              
407             =item $client->UpdateOptimize($input, sub { my ($call) = @_; })
408              
409             Optimize the SoftHSM database, returns an error if it failed to optimize the
410             database otherwise there is no response.
411              
412             WARNING: Make sure that no application is currently using SoftHSM and session
413             objects.
414              
415             $input = {
416             slot => # Single hash or an array of hashes as below:
417             {
418             id => integer, # Slot id
419             pin => string, # User pin
420             }
421             };
422              
423             =item $client->UpdateTrusted($input, sub { my ($call) = @_; })
424              
425             Update the trusted status of a key, returns an error if it failed to update the
426             key otherwise there is no response. Must have either key id or key label.
427              
428             $input = {
429             key_pair => # Single hash or an array of hashes as below:
430             {
431             slot => integer, # Slot where the key is
432             id => string, # Key id (optional)
433             label => string, # Key label (optional)
434             type => string, # Key type
435             so_pin => string, # Security Officer pin
436             trusted => bool, # True if the key should be trusted
437             }
438             };
439              
440             =back
441              
442             =head1 COMMANDS
443              
444             =over 4
445              
446             =item version
447              
448             Show version of the plugin and SoftHSM.
449              
450             =item configs
451              
452             List configuration files.
453              
454             =item config view
455              
456             Display the content of a configuration file.
457              
458             =item config edit
459              
460             Edit a configuration file.
461              
462             =item show slots
463              
464             List information about SoftHSM slots.
465              
466             =item init token
467              
468             Initialize a slot.
469              
470             =item import [--slot ] [--pin ] [--id ] [--label
471              
472             Import a key into SoftHSM from a local file.
473              
474             =item export [--slot ] [--pin ] [--id ] [--file-pin ]
475              
476             Export a key from SoftHSM into a local file.
477              
478             =item optimize [--pin ]
479              
480             Optimize slot(s).
481              
482             =item trust [--slot ] [--so-pin ] [--type ] < --id | --label
483              
484             Mark a key as trusted.
485              
486             =item untrust [--slot ] [--so-pin ] [--type ] < --id | --label
487              
488             Remove the trusted marking on a key.
489              
490             =back
491              
492             =head1 AUTHOR
493              
494             Jerry Lundström, C<< >>
495              
496             =head1 BUGS
497              
498             Please report any bugs or feature requests to L.
499              
500             =head1 SUPPORT
501              
502             You can find documentation for this module with the perldoc command.
503              
504             perldoc Lim::Plugin::SoftHSM
505              
506             You can also look for information at:
507              
508             =over 4
509              
510             =item * Lim issue tracker (report bugs here)
511              
512             L
513              
514             =back
515              
516             =head1 ACKNOWLEDGEMENTS
517              
518             =head1 LICENSE AND COPYRIGHT
519              
520             Copyright 2012-2013 Jerry Lundström.
521              
522             This program is free software; you can redistribute it and/or modify it
523             under the terms of either: the GNU General Public License as published
524             by the Free Software Foundation; or the Artistic License.
525              
526             See http://dev.perl.org/licenses/ for more information.
527              
528              
529             =cut
530              
531             1; # End of Lim::Plugin::SoftHSM