I am working on a library which follows PKCS#11 standard.
https://www.cryptsoft.com/pkcs11doc/v220/
The library can generate RSA Keypair in token by the function C_GenerateKeyPair and returns appropriate object handles with return value CKR_OK.
The token(applet) not supports load of private/public key except generate key pair. What will be the appropriate return value of create RSA private/public key using C_CreateObject?
Now I am returning CKR_GENERAL_ERROR, is it okay?
Allowed return values are
CKR_ARGUMENTS_BAD, CKR_ATTRIBUTE_READ_ONLY,
CKR_ATTRIBUTE_TYPE_INVALID, CKR_ATTRIBUTE_VALUE_INVALID,
CKR_CRYPTOKI_NOT_INITIALIZED, CKR_DEVICE_ERROR, CKR_DEVICE_MEMORY,
CKR_DEVICE_REMOVED, CKR_DOMAIN_PARAMS_INVALID, CKR_FUNCTION_FAILED,
CKR_GENERAL_ERROR, CKR_HOST_MEMORY, CKR_OK, CKR_PIN_EXPIRED,
CKR_SESSION_CLOSED, CKR_SESSION_HANDLE_INVALID, CKR_SESSION_READ_ONLY,
CKR_TEMPLATE_INCOMPLETE, CKR_TEMPLATE_INCONSISTENT,
CKR_TOKEN_WRITE_PROTECTED, CKR_USER_NOT_LOGGED_IN.
Thanks for your help
Update
I have two types of applet, one supports load of RSA private/public key to token and another not supports. It can only possible to identify if the token supports load of key is the response of transmitted APDU. So I can't take decision only to check the class attribute of C_CreateObject.
If your library does not support C_CreateObject at all then the best choice IMO is CKR_FUNCTION_NOT_SUPPORTED.
Chapter 11 in PKCS#11 v2.20 states:
A Cryptoki library need not support every function in the Cryptoki API. However, even an unsupported function must have a "stub" in the library which simply returns the value CKR_FUNCTION_NOT_SUPPORTED.
If your library does support C_CreateObject for creation of other object types (e.g. certificates, data objects etc.) then the best choice IMO is CKR_ATTRIBUTE_VALUE_INVALID.
Chapter 10.1.1 in PKCS#11 v2.20 states:
If the supplied template specifies an invalid value for a valid attribute, then the attempt should fail with the error code CKR_ATTRIBUTE_VALUE_INVALID.
UPDATE
Now that you have shared more details about your library in the comments I can add more detailed explanation:
It seems I can call your implementation of C_CreateObject with template containing CKA_CLASS=CKO_CERTIFICATE and it will create certificate object on this particular token and return CKR_OK. If I call it with template containing CKA_CLASS=CKO_PRIVATE_KEY then your code will decide to return an error right after the evaluation of the supplied value of this attribute. IMO there is no doubt that chapter 10.1.1 of PKCS#11 v2.20 recommends you to return CKR_ATTRIBUTE_VALUE_INVALID in this case.
However if are not willing to follow behavior recommended by the specification and there is no predefined error code you like, you can introduce your own vendor defined code (see my older answer for more details):
#define CKR_TOKEN_OPERATION_NOT_SUPPORTED (CKR_VENDOR_DEFINED|0x0000001)
IMO confusion level for inexperienced developer will be the same regardless of error code you return. In the end he/she will need to consult your documentation or logs produced by your library to find out the real reason why he/she received the error.
Related
I am developer of the PKCS#11 library. I think that the function C_DeriveKey should fail with the error code
CKR_KEY_FUNCTION_NOT_PERMITTED
if the key has CKA_DERIVE=0.But this error code is not listed as a possible return value for C_DeriveKey in the specification document . What is the right error code to be returned by C_DeriveKey in this case?
I agree that the specification is not very clear on this case. There is a newer version of the specification available (v3.0 from March 2020, link), but it does not bring more clarity on this. I would make the following considerations:
General note on return values
The introduction on return values in section 5.1 gives the following disclaimer (link):
Because of the complexity of the Cryptoki specification, it is recommended that Cryptoki applications attempt to give some leeway when interpreting Cryptoki functions’ return values. We have attempted to specify the behavior of Cryptoki functions as completely as was feasible; nevertheless, there are presumably some gaps. For example, it is possible that a particular error code which might apply to a particular Cryptoki function is unfortunately not actually listed in the description of that function as a possible error code.
The last part directly acknowledges that the list of possible return values for each function may be incomplete. For that reason, C_DeriveKey not listing CKR_KEY_FUNCTION_NOT_PERMITTED as a possible return code may not be authoritative, if there are other reasons for why the function should return this value.
Definition of the return codes
Section 5.1.6 gives the following definitions (link):
CKR_KEY_FUNCTION_NOT_PERMITTED: An attempt has been made to use a key for a cryptographic purpose that the key’s attributes are not set to allow it to do. For example, to use a key for performing encryption, that key MUST have its CKA_ENCRYPT attribute set to CK_TRUE (the fact that the key MUST have a CKA_ENCRYPT attribute implies that the key cannot be a private key). This return value has lower priority than CKR_KEY_TYPE_INCONSISTENT.
CKR_KEY_TYPE_INCONSISTENT: The specified key is not the correct type of key to use with the specified mechanism. This return value has a higher priority than CKR_KEY_FUNCTION_NOT_PERMITTED.
From this definition I would conclude that CKR_KEY_TYPE_INCONSISTENT is not the right return code for the scenario we are discussing, because it relates the mechanism to the "type" of the key. If we understand "type" in the sense of CKA_KEY_TYPE, it is completely unrelated to the attribute CKA_DERIVE.
Moreover, the attribute CKA_ENCRYPT is given as an example in the definition of CKR_KEY_FUNCTION_NOT_PERMITTED. This attribute is very similar to CKA_DERIVE, i.e. CKA_ENCRYPT controlling whether the key can be used for encryption and CKA_DERIVE controlling whether the key can be used for deriving. Thus, if CKR_KEY_FUNCTION_NOT_PERMITTED is the right return code for the case when CKA_ENCRYPT is not set, it seems reasonable that it would also be the right return code for the case when CKA_DERIVE is not set.
Reference implementations
I looked at some PKCS#11 libraries to check how they handle the case that C_DeriveKey is called on a key with CKA_DERIVE set to CK_FALSE. Most of the implementations I found do not implement the C_DeriveKey function at all (i.e. they always return CKR_FUNCTION_NOT_SUPPORTED). For the libraries that do implement this function, I observed the following behaviors:
OpenSC returns CKR_KEY_TYPE_INCONSISTENT (reference):
CK_ATTRIBUTE derive_attribute = { CKA_DERIVE, &can_derive, sizeof(can_derive) };
...
rv = object->ops->get_attribute(session, object, &derive_attribute);
if (rv != CKR_OK || !can_derive) {
rv = CKR_KEY_TYPE_INCONSISTENT;
goto out;
}
I also checked how OpenSC handles the other attributes that are similar to CKA_DERIVE. It seems the C_EncryptInit function is not implemented in OpenSC (presumably because this is a public key operation?), but C_DecryptInit is. This function implements a check for CKA_DECRYPT (reference), but returns CKR_KEY_TYPE_INCONSISTENT, which goes against the example that was given in the specification of CKR_KEY_FUNCTION_NOT_PERMITTED.
SoftHSMv2 returns CKR_KEY_FUNCTION_NOT_PERMITTED (reference):
// Check if key can be used for derive
if (!key->getBooleanValue(CKA_DERIVE, false))
return CKR_KEY_FUNCTION_NOT_PERMITTED;
openCryptoki: I could not find any check for CKA_DERIVE. They do check CKF_DERIVE against the feature flags of the mechanism and return CKR_MECHANISM_INVALID if the flag is not set (reference), i.e. if the mechanism does not support derivation, but this is not the same as checking CKA_DERIVE against the flags of the key.
illumos-gate (IllumOS being a fork of the discontinued OpenSolaris) also returns CKR_KEY_FUNCTION_NOT_PERMITTED in their soft-key implementation (reference):
/* Check to see if key object allows for derivation. */
if (!(basekey_p->bool_attr_mask & DERIVE_BOOL_ON)) {
rv = CKR_KEY_FUNCTION_NOT_PERMITTED;
goto clean_exit1;
}
Interestingly, in older version of their code they returned CKR_KEY_TYPE_INCONSISTENT instead, and then changed it to CKR_KEY_FUNCTION_NOT_PERMITTED in this commit. The relevant part of the commit message seems to be 6177650 Wrong error code returned when key does not allow requested operation. The ID refers to a ticket in the OpenSolaris bug tracker, which is no longer online. There is an archive of the bug tracker here, but it does not contain any information on this ticket, unfortunately.
Of these reference implementations, I would consider OpenSC to be the most authoritative, in terms of how widely they are used.
Conclusion
Based on the above considerations, I would consider CKR_KEY_FUNCTION_NOT_PERMITTED to be the appropriate return code for the scenario we are discussing. This is supported by the following arguments:
The specification explicitly acknowledges that the list of possible return code for each function might be incomplete. Therefore, CKR_KEY_FUNCTION_NOT_PERMITTED not being listed for C_DeriveKey is not a strong counter-argument.
The specification explicitly lists CKA_ENCRYPT as an example for when CKR_KEY_FUNCTION_NOT_PERMITTED is an appropriate return code. The attribute CKA_ENCRYPT is similar to CKA_DERIVE, so it seems plausible that the return code is also appropriate for CKA_DERIVE.
The specification of CKR_KEY_TYPE_INCONSISTENT suggest that it is about the relation between the mechanism and the key type, not about other key attributes.
OpenSC uses CKR_KEY_TYPE_INCONSISTENT for the scenario we are discussing, but also uses this return code for C_DecryptInit in the case that CKA_DECRYPT is not set, which goes against the example given in the specification of CKR_KEY_FUNCTION_NOT_PERMITTED.
OpenSolaris/IllumOS deliberately switched from CKR_KEY_TYPE_INCONSISTENT to CKR_KEY_FUNCTION_NOT_PERMITTED as the return code for the scenario we are discussing. This suggests they also considered the latter the more fitting return code.
How can this be done in iText? I have a PDF with a signature from a client. I need to add an ocsp response to unsigned attributes.
I know how to change the signature itself using
org.bouncycastle.cms.CMSSignedData.replaceSigners(...).getEncoded()
but I don't know how to replace PdfName.CONTENTS in the PDF using new PdfString(newSignature).setHexWriting(true). If I use this code:
PdfDictionary other = new PdfDictionary();
other.put(PdfName.CONTENTS, new PdfString(newSignature).setHexWriting(true));
dicSignature.merge(other);
where dicSignature is the dictionary which contains the signature, then the signature (when the document is opened in Adobe Reader) is broken.
When iText manipulates a document using aPdfStamperin normal mode, it can (and often does) re-arrange the existing PDF objects. This obviously breaks the hash value of any existing integrated signature. Furthermore the byte ranges which would have to be signed, change. This most likely is your problem.
When iText manipulates a document using aPdfStamperin append mode, it leaves the PDF as is and only appends its additions and changes. While this in general is the way to go to keep integrated signatures from breaking, you cannot change the content of a signature this way because there are stricter rules concerning embedding signatures than for PDFs in general. Switching to append mode, therefore, would not fix your problem.
Thus, iText has an explicit method doing a signature insertion without otherwise changing the PDF:
MakeSignature.signDeferred(PdfReader reader,
String fieldName,
OutputStream outs,
ExternalSignatureContainer externalSignatureContainer)
throws DocumentException, IOException, GeneralSecurityException
Its name is due to the fact that this method originally is intended for the use case of deferred signing, i.e. first preparing the PDF for signing (i.e. adding all dictionaries and other necessary structures required to hash the byte ranges, including leaving a gap into which a signature container eventually shall be injected), calculating the hash value, and sending it to some other service while storing the prepared PDF locally. As soon as that other service returns the signature, the prepared PDF is located and the retrieved signature is inserted into it using this method.
The only difference to your use case is that there already is a signature in the gap. That signature, though, will be overwritten by your updated one when using signDeferred.
Having said all this, you may be in for a surprise if you expect that after you add an ocsp response to unsigned attributes, Adobe Reader uses these information for verification. In the context of integrated PDF signatures according to ISO-32000-1, section 12.8.3.3 PKCS#7 Signatures as used in ISO 32000,
the PKCS#7 object should contain [...] Revocation information as an signed attribute (PDF 1.6): This attribute may include all the revocation information that is necessary to carry out revocation checks for the signer's certificate and its issuer certificates. Since revocation information is a signed attribute, it must be obtained before the computation of the digital signature. This means that the software used by the signer must be able to construct the certification path and the associated revocation information. If one of the elements cannot be obtained (e.g. no connection is possible), a signature with this attribute will not be possible.
I am creating HTTP request using Apache HTTP Client version 4.3.4. I see there are some classes like HttpGet,... and there is also a class BasicHttpRequest. I am not sure which one to use.
Whats the difference and which one should be used in which condition ?
BasicHttpRequest is provided by the core library. As its name suggests it is pretty basic: it enforces no particular method name or type, nor does it attempt to validate the request URI. The URI parameter can be any arbitrary garbage. HttpClient will dutifully transmit it to server as is, if it is unable to parse it to a valid URI.
HttpUriRequest variety on the other hand will enforce specific method type and will require a valid URI. Another important feature is that HttpUriRequest can be aborted at any point of their execution.
You should always be using classes that implement HttpUriRequest per default.
I was just browsing the 4.3.6 javadoc attempting to locate your BasicHttpRequest and was unable to find it. Do you have a reference to the javadoc of this class?
I would be under the impression that BasicHttpRequest would be a base class providing operations and attributes common to more than one HttpRequest. It may be extremely generic for extension purposes.
To the first part of your question, use HttpGet, HttpPost etc for their specific operations. If you only need to HTTP/GET information then use HttpGet, if you need to post a form or document body, then use HttpPost. If you are attempting to use things like the Head, Put, Delete method, then use the correspoding HttpXXX class.
In my applet, key is hardcoded and i want to give this key as the parameter of install() method.
The install method takes 3 parameter as
install(byte[] bArray, short bOffset, byte bLength)
How can i give the key value as the parameter of the install method?
Normally a Java Card implementation also implements Global Platform. In that case the user parameters can be given as part of the INSTALL for INSTALL command. The Global Platform card specification is available for free, although registration is required.
You can find the specification of the parameters in 11.5.2.3.7 INSTALL Command Parameters of the provided document. It is important to provide the instance AID first. Then there is a specific format for the Application Specific Parameters (tag C9, then a length byte, then the parameters in binary). You need to parse this structure in the Java Card install method as well.
If you cannot debug the install method then return the parameters as response data of a test APDU.
What is the best way to version REST URIs? Currently we have a version # in the URI itself, ie.
http://example.com/users/v4/1234/
for version 4 of this representation.
Does the version belong in the queryString? ie.
http://example.com/users/1234?version=4
Or is versioning best accomplished another way?
Do not version URLs, because ...
you break permalinks
The url changes will spread like a disease through your interface. What do you do with representations that have not changed but point to the representation that has? If you change the url, you break old clients. If you leave the url, your new clients may not work.
Versioning media types is a much more flexible solution.
Assuming that your resource is returning some variant of application/vnd.yourcompany.user+xml all you need to do is create support for a new application/vnd.yourcompany.userV2+xml media type and through the magic of content negotiation your v1 and v2 clients can co-exist peacefully.
In a RESTful interface, the closest thing you have to a contract is the definition of the media-types that are exchanged between the client and the server.
The URLs that the client uses to interact with the server should be provided by the server embedded in previously retrieved representations. The only URL that needs to be known by the client is the root URL of the interface. Adding version numbers to urls only has value if you construct urls on the client, which you are not suppose to do with a RESTful interface.
If you need to make a change to your media-types that will break your existing clients then create a new one and leave your urls alone!
And for those readers currently saying that this makes no sense if I am using application/xml and application/json as media-types. How are we supposed to version those? You're not. Those media-types are pretty much useless to a RESTful interface unless you parse them using code-download, at which point versioning is a moot point.
I would say making it part of the URI itself (option 1) is best because v4 identifies a different resource than v3. Query parameters like in your second option can be best used to pass-in additional (query) info related to the request, rather than the resource.
Ah, I'm putting my old grumpy hat on again.
From a ReST perspective, it doesn't matter at all. Not a sausage.
The client receives a URI it wants to follow, and treats it as an opaque string. Put whatever you want in it, the client has no knowledge of such a thing as a version identifier on it.
What the client knows is that it can process the media type, and I'll advise to follow Darrel's advice. Also I personally feel that needing to change the format used in a restful architecture 4 times should bring huge massive warning signs that you're doing something seriously wrong, and completely bypassing the need to design your media type for change resiliance.
But either way, the client can only process a document with a format it can understand, and follow links in it. It should know about the link relationships (the transitions). So what's in the URI is completely irrelevant.
I personally would vote for http://localhost/3f3405d5-5984-4683-bf26-aca186d21c04
A perfectly valid identifier that will prevent any further client developer or person touching the system to question if one should put v4 at the beginning or at the end of a URI (and I suggest that, from the server perspective, you shouldn't have 4 versions, but 4 media types).
You should NOT put the version in the URL, you should put the version in the Accept Header of the request - see my post on this thread:
Best practices for API versioning?
If you start sticking versions in the URL you end up with silly URLs like this:
http://company.com/api/v3.0/customer/123/v2.0/orders/4321/
And there are a bunch of other problems that creep in as well - see my blog:
http://thereisnorightway.blogspot.com/2011/02/versioning-and-types-in-resthttp-api.html
These (less-specific) SO questions about REST API versioning may be helpful:
Versioning RESTful services?
Best practices for web service REST API versioning
There are 4 different approaches to versioning the API:
Adding version to the URI path:
http://example.com/api/v1/foo
http://example.com/api/v2/foo
When you have breaking change, you must increment the version like: v1, v2, v3...
You can implement a controller in you code like this:
#RestController
public class FooVersioningController {
#GetMapping("v1/foo")
public FooV1 fooV1() {
return new FooV1("firstname lastname");
}
#GetMapping("v2/foo")
public FooV2 fooV2() {
return new FooV2(new Name("firstname", "lastname"));
}
Request parameter versioning:
http://example.com/api/v2/foo/param?version=1
http://example.com/api/v2/foo/param?version=2
The version parameter can be optional or required depending on how you want the API to be used.
The implementation can be similar to this:
#GetMapping(value = "/foo/param", params = "version=1")
public FooV1 paramV1() {
return new FooV1("firstname lastname");
}
#GetMapping(value = "/foo/param", params = "version=2")
public FooV2 paramV2() {
return new FooV2(new Name("firstname", "lastname"));
}
Passing a custom header:
http://localhost:8080/foo/produces
With header:
headers[Accept=application/vnd.company.app-v1+json]
or:
headers[Accept=application/vnd.company.app-v2+json]
Largest advantage of this scheme is mostly semantics: You aren’t cluttering the URI with anything to do with the versioning.
Possible implementation:
#GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v1+json")
public FooV1 producesV1() {
return new FooV1("firstname lastname");
}
#GetMapping(value = "/foo/produces", produces = "application/vnd.company.app-v2+json")
public FooV2 producesV2() {
return new FooV2(new Name("firstname", "lastname"));
}
Changing Hostnames or using API Gateways:
Essentially, you’re moving the API from one hostname to another. You might even just call this building a new API to the same resources.
Also,you can do this using API Gateways.
I wanted to create versioned APIs and I found this article very useful:
http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-rest-or-http
There is a small section on "I want my API to be versioned". I found it simple and easy to understand. The crux is to use Accept field in the header to pass version information.
If the REST services require authentication before use, you could easily associate the API key/token with an API version and do the routing internally. To use a new version of the API, a new API key could be required, linked to that version.
Unfortunately, this solution only works for auth-based APIs. However, it does keep versions out of the URIs.
If you use URIs for versioning, then the version number should be in the URI of the API root, so every resource identifier can include it.
Technically a REST API does not break by URL changes (the result of the uniform interface constraint). It breaks only when the related semantics (for example an API specific RDF vocab) changes in a non backward compatible way (rare). Currently a lot of ppl do not use links for navigation (HATEOAS constraint) and vocabs to annotate their REST responses (self-descriptive message constraint) that's why their clients break.
Custom MIME types and MIME type versioning does not help, because putting the related metadata and the structure of the representation into a short string does not work. Ofc. the metadata and the structure will frequently change, and so the version number too...
So to answer your question the best way to annotate your requests and responses with vocabs (Hydra, linked data) and forget versioning or use it only by non backward compatible vocab changes (for example if you want to replace a vocab with another one).
I'd include the version as an optional value at the end of the URI. This could be a suffix like /V4 or a query parameter like you've described. You might even redirect the /V4 to the query parameter so you support both variations.
I vote up for doing this in mime type but not in URL.
But the reason is not the same as other guys.
I think the URL should be unique (excepting those redirects) for locating the unique resource.
So, if you accept /v2.0 in URLs, why it is not /ver2.0 or /v2/ or /v2.0.0? Or even -alpha and -beta? (then it totally becomes the concept of semver)
So, the version in mime type is more acceptable than the URL.